## InfXmlConnection InfXmlConnection |

## Synopsis

                        InfXmlConnection;
    struct              InfXmlConnectionIface;
    enum                InfXmlConnectionStatus;
    gboolean            inf_xml_connection_open             (InfXmlConnection *connection,
                                                             GError **error);
    void                inf_xml_connection_close            (InfXmlConnection *connection);
    void                inf_xml_connection_send             (InfXmlConnection *connection,
                                                             xmlNodePtr xml);
    void                inf_xml_connection_sent             (InfXmlConnection *connection,
                                                             const xmlNodePtr xml);
    void                inf_xml_connection_received         (InfXmlConnection *connection,
                                                             const xmlNodePtr xml);
    void                inf_xml_connection_error            (InfXmlConnection *connection,
                                                             const GError *error);

## Object Hierarchy

      GInterface
       +----InfXmlConnection

      GEnum
       +----InfXmlConnectionStatus

## Prerequisites

InfXmlConnection requires GObject.

## Known Implementations

InfXmlConnection is implemented by InfSimulatedConnection and InfXmppConnection.

## Properties

      "local-id"                 gchar*                : Read
      "network"                  gchar*                : Read
      "remote-id"                gchar*                : Read
      "status"                   InfXmlConnectionStatus  : Read

## Signals

      "error"                                          : Run Last
      "received"                                       : Run Last
      "sent"                                           : Run Last

## Description

## Details

### InfXmlConnection

    typedef struct _InfXmlConnection InfXmlConnection;

### struct InfXmlConnectionIface

    struct InfXmlConnectionIface {
      GTypeInterface parent;

      /* 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);
    };

### enum InfXmlConnectionStatus

    typedef enum {
      INF_XML_CONNECTION_CLOSED,
      INF_XML_CONNECTION_CLOSING,
      INF_XML_CONNECTION_OPEN,
      INF_XML_CONNECTION_OPENING
    } InfXmlConnectionStatus;

### 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.

`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.

`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.

`connection` : | A InfXmlConnection.
`xml` : | A XML message to send. The function takes ownership of the XML node.

### 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.

`connection` : | A InfXmlConnection.
`xml` : | The XML message that has been sent.

### 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.

`connection` : | A InfXmlConnection.
`xml` : | The XML message that has been received.

### 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.

`connection` : | A InfXmlConnection.
`error` : | The error that occured.

## Property Details

### The `"local-id"` property

      "local-id"                 gchar*                : Read

A unique identification on the network for the local site.

Default value: NULL

### The `"network"` property

      "network"                  gchar*                : Read

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

Default value: NULL

### The `"remote-id"` property

      "remote-id"                gchar*                : Read

A unique identification on the network for the remote site.

Default value: NULL

### The `"status"` property

      "status"                   InfXmlConnectionStatus  : Read

The status of the connection.

Default value: INF_XML_CONNECTION_CLOSED

## Signal Details

### The `"error"` signal

    void                user_function                      (InfXmlConnection *connection,
                                                            gpointer          error,
                                                            gpointer          user_data)       : Run Last

`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.

### The `"received"` signal

    void                user_function                      (InfXmlConnection *connection,
                                                            gpointer          node,
                                                            gpointer          user_data)       : Run Last

`connection` : | The InfXmlConnection through which `node` has been received
`node` : | An xmlNodePtr refering to the XML node that has been received
`user_data` : | user data set when the signal handler was connected.

### The `"sent"` signal

    void                user_function                      (InfXmlConnection *connection,
                                                            gpointer          node,
                                                            gpointer          user_data)       : Run Last

`connection` : | The InfXmlConnection through which `node` has been sent
`node` : | An xmlNodePtr refering to the XML node that has been sent
`user_data` : | user data set when the signal handler was connected.