Top | ![]() |
![]() |
![]() |
![]() |
gboolean | inf_xml_connection_open () |
void | inf_xml_connection_close () |
void | inf_xml_connection_send () |
void | inf_xml_connection_sent () |
void | inf_xml_connection_received () |
void | inf_xml_connection_error () |
gpointer | local-certificate | Read |
char * | local-id | Read |
char * | network | Read |
InfCertificateChain * | remote-certificate | Read |
char * | remote-id | Read |
InfXmlConnectionStatus | status | Read |
InfXmlConnection is implemented by InfSimulatedConnection and InfXmppConnection.
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.
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.
void
inf_xml_connection_close (InfXmlConnection *connection
);
Closes the given connection.
void inf_xml_connection_send (InfXmlConnection *connection
,xmlNodePtr xml
);
Sends the given XML message to the remote host.
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.
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.
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.
typedef struct _InfXmlConnection InfXmlConnection;
InfXmlConnection is an opaque data type. You should only access it via the public API functions.
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.
Virtual function to start the connection. |
||
Virtual function to stop the connection. |
||
Virtual function to transmit data over the connection. |
||
Default signal handler of the “sent” signal. |
||
Default signal handler of the “received” signal. |
||
Default signal handler of the “error” signal. |
The possible connection status of an InfXmlConnection.
“local-certificate”
property “local-certificate” gpointer
The X.509 certificate (gnutls_x509_crt_t) of the local site.
Owner: InfXmlConnection
Flags: Read
“local-id”
property “local-id” char *
A unique identification on the network for the local site.
Owner: InfXmlConnection
Flags: Read
Default value: NULL
“network”
property “network” char *
An identifier for the type of network this connection is on.
Owner: InfXmlConnection
Flags: Read
Default value: NULL
“remote-certificate”
property“remote-certificate” InfCertificateChain *
The X.509 certificate of the remote site.
Owner: InfXmlConnection
Flags: Read
“remote-id”
property “remote-id” char *
A unique identification on the network for the remote site.
Owner: InfXmlConnection
Flags: Read
Default value: NULL
“status”
property“status” InfXmlConnectionStatus
The status of the connection.
Owner: InfXmlConnection
Flags: Read
Default value: INF_XML_CONNECTION_CLOSED
“error”
signalvoid 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.
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
“received”
signalvoid user_function (InfXmlConnection *connection, gpointer node, gpointer user_data)
Signal which is emitted when an XML node has been received by this connection.
connection |
The InfXmlConnection through which |
|
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
“sent”
signalvoid user_function (InfXmlConnection *connection, gpointer node, gpointer user_data)
Signal which is emitted when an XML node has been successfully transmitted with this connection.
connection |
The InfXmlConnection through which |
|
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