InfXmlConnection

InfXmlConnection — Exchange of XML messages

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

gpointer local-certificate Read
char * local-id Read
char * network Read
InfCertificateChain * remote-certificate Read
char * remote-id Read
InfXmlConnectionStatus status Read

Signals

void error Run Last
void received Run Last
void sent Run Last

Types and Values

Object Hierarchy

    GEnum
    ╰── InfXmlConnectionStatus
    GInterface
    ╰── InfXmlConnection

Prerequisites

InfXmlConnection requires GObject.

Known Implementations

InfXmlConnection is implemented by InfSimulatedConnection and InfXmppConnection.

Includes

#include <libinfinity/common/inf-xml-connection.h>

Description

InfXmlConnection provides a generic interface for sending an receiving messages in the form of XML nodes. The rest of the libinfinity library works with InfXmlConnections to transfer data between nodes. Therefore, simply implementing this interface allows to use the core functionality of the library with any kind of network or transport.

Apart from the virtual functions, implementations also need to provide the “remote-id” and “local-id” properties. These properties represent string identifiers that are unique to the particular hosts in the network, such as IP addresses for IP connections. If the connection is supposed to be used with other communication methods (see InfCommunicationMethod) than the "central" one, these IDs must be unique and every host must see the same ID for the other hosts in the network. This is no longer fulfilled by simple IP addresses, but for example for JIDs when sending XML messages over a jabber server.

Functions

inf_xml_connection_open ()

gboolean
inf_xml_connection_open (InfXmlConnection *connection,
                         GError **error);

Attempts to open the given XML connection. If the process fails, error will be set. The connection needs to be in status INF_XML_CONNECTION_CLOSED for this function to be called. Even if this function succeeds, the connection process can fail later. In that case the status of connection will be reset to INF_XML_CONNECTION_CLOSED and the “error” signal will be emitted.

Parameters

connection

A infXmlConnection.

 

error

Location to store error information, if any.

 

Returns

TRUE on succes, or FALSE on error.


inf_xml_connection_close ()

void
inf_xml_connection_close (InfXmlConnection *connection);

Closes the given connection.

Parameters

connection

A InfXmlConnection.

 

inf_xml_connection_send ()

void
inf_xml_connection_send (InfXmlConnection *connection,
                         xmlNodePtr xml);

Sends the given XML message to the remote host.

Parameters

connection

A InfXmlConnection.

 

xml

A XML message to send. The function takes ownership of the XML node.

[transfer full]

inf_xml_connection_sent ()

void
inf_xml_connection_sent (InfXmlConnection *connection,
                         const xmlNodePtr xml);

Emits the "sent" signal on connection . This will most likely only be useful to implementors.

Parameters

connection

A InfXmlConnection.

 

xml

The XML message that has been sent.

[transfer none]

inf_xml_connection_received ()

void
inf_xml_connection_received (InfXmlConnection *connection,
                             const xmlNodePtr xml);

Emits the "received" signal on connection . This will most likely only be useful to implementors.

Parameters

connection

A InfXmlConnection.

 

xml

The XML message that has been received.

[transfer none]

inf_xml_connection_error ()

void
inf_xml_connection_error (InfXmlConnection *connection,
                          const GError *error);

Emits the "error" signal on connection . This will most likely only be useful to implementors.

Note that the error may or may not be fatal for the connection. If it is fatal, then a status notify to INF_XML_CONNECTION_CLOSING or INF_XML_CONNECTION_CLOSED will follow. If you are implementing a custom class implementing InfXmlConnection, make sure to always emit the "error" signal before doing the status notify because many users of the connection will release their reference when the connection is no longer connected.

Parameters

connection

A InfXmlConnection.

 

error

The error that occurred.

 

Types and Values

InfXmlConnection

typedef struct _InfXmlConnection InfXmlConnection;

InfXmlConnection is an opaque data type. You should only access it via the public API functions.


struct InfXmlConnectionInterface

struct InfXmlConnectionInterface {
  /* Virtual table */
  gboolean (*open)(InfXmlConnection* connection,
                   GError** error);
  void (*close)(InfXmlConnection* connection);
  void (*send)(InfXmlConnection* connection,
               xmlNodePtr xml);

  /* Signals */
  void (*sent)(InfXmlConnection* connection,
               const xmlNodePtr xml);
  void (*received)(InfXmlConnection* connection,
                   const xmlNodePtr xml);
  void (*error)(InfXmlConnection* connection,
                const GError* error);
};

Virtual functions and default signal handlers for the InfXmlConnection interface.

Members

open ()

Virtual function to start the connection.

 

close ()

Virtual function to stop the connection.

 

send ()

Virtual function to transmit data over the connection.

 

sent ()

Default signal handler of the “sent” signal.

 

received ()

Default signal handler of the “received” signal.

 

error ()

Default signal handler of the “error” signal.

 

enum InfXmlConnectionStatus

The possible connection status of an InfXmlConnection.

Members

INF_XML_CONNECTION_CLOSED

The connection is currently not established.

 

INF_XML_CONNECTION_CLOSING

The connection is in the process of being closed, no more data can be sent.

 

INF_XML_CONNECTION_OPEN

The connection is up and data can be transmitted.

 

INF_XML_CONNECTION_OPENING

The connection is being established.

 

Property Details

The “local-certificate” property

  “local-certificate”        gpointer

The X.509 certificate (gnutls_x509_crt_t) of the local site.

Owner: InfXmlConnection

Flags: Read


The “local-id” property

  “local-id”                 char *

A unique identification on the network for the local site.

Owner: InfXmlConnection

Flags: Read

Default value: NULL


The “network” property

  “network”                  char *

An identifier for the type of network this connection is on.

Owner: InfXmlConnection

Flags: Read

Default value: NULL


The “remote-certificate” property

  “remote-certificate”       InfCertificateChain *

The X.509 certificate of the remote site.

Owner: InfXmlConnection

Flags: Read


The “remote-id” property

  “remote-id”                char *

A unique identification on the network for the remote site.

Owner: InfXmlConnection

Flags: Read

Default value: NULL


The “status” property

  “status”                   InfXmlConnectionStatus

The status of the connection.

Owner: InfXmlConnection

Flags: Read

Default value: INF_XML_CONNECTION_CLOSED

Signal Details

The “error” signal

void
user_function (InfXmlConnection *connection,
               GError           *error,
               gpointer          user_data)

This signal is emitted when an error occurs for this connection. For example, if the connection cannot be established and the status changes from INF_XML_CONNECTION_OPENING to INF_XML_CONNECTION_CLOSED, then this signal is usually emitted with more details on the error.

Note however that the error may or may not be fatal for the connection. If it is fatal, then a status notify to INF_XML_CONNECTION_CLOSING or INF_XML_CONNECTION_CLOSED will follow.

Parameters

connection

The erroneous InfXmlConnection

 

error

A pointer to a GError object with details on the error

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “received” signal

void
user_function (InfXmlConnection *connection,
               gpointer          node,
               gpointer          user_data)

Signal which is emitted when an XML node has been received by this connection.

Parameters

connection

The InfXmlConnection through which node has been received

 

node

An xmlNodePtr referring to the XML node that has been received

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “sent” signal

void
user_function (InfXmlConnection *connection,
               gpointer          node,
               gpointer          user_data)

Signal which is emitted when an XML node has been successfully transmitted with this connection.

Parameters

connection

The InfXmlConnection through which node has been sent

 

node

An xmlNodePtr referring to the XML node that has been sent

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

InfXmppConnection