WockyXmppConnection

## WockyXmppConnection WockyXmppConnection — Low-level XMPP connection. |

## Synopsis

    enum                WockyXmppConnectionError;
    GQuark              wocky_xmpp_connection_error_quark   (void);
    #define             WOCKY_XMPP_CONNECTION_ERROR
    struct              WockyXmppConnectionClass;
    WockyXmppConnection * wocky_xmpp_connection_new         (GIOStream *stream);
    void                wocky_xmpp_connection_send_open_async
                                                            (WockyXmppConnection *connection,
                                                             const gchar *to,
                                                             const gchar *from,
                                                             const gchar *version,
                                                             const gchar *lang,
                                                             const gchar *id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_xmpp_connection_send_open_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_xmpp_connection_recv_open_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_xmpp_connection_recv_open_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             gchar **to,
                                                             gchar **from,
                                                             gchar **version,
                                                             gchar **lang,
                                                             gchar **id,
                                                             GError **error);
    void                wocky_xmpp_connection_send_stanza_async
                                                            (WockyXmppConnection *connection,
                                                             WockyStanza *stanza,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_xmpp_connection_send_stanza_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_xmpp_connection_recv_stanza_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    WockyStanza *       wocky_xmpp_connection_recv_stanza_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_xmpp_connection_send_close_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_xmpp_connection_send_close_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_xmpp_connection_force_close_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_xmpp_connection_force_close_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_xmpp_connection_send_whitespace_ping_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_xmpp_connection_send_whitespace_ping_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_xmpp_connection_reset         (WockyXmppConnection *connection);
    gchar *             wocky_xmpp_connection_new_id        (WockyXmppConnection *self);

## Description

Sends and receives WockyStanzas from an underlying GIOStream.

## Details

### enum WockyXmppConnectionError

    typedef enum {
      WOCKY_XMPP_CONNECTION_ERROR_EOS,
      WOCKY_XMPP_CONNECTION_ERROR_CLOSED,
      WOCKY_XMPP_CONNECTION_ERROR_NOT_OPEN,
      WOCKY_XMPP_CONNECTION_ERROR_IS_CLOSED,
      WOCKY_XMPP_CONNECTION_ERROR_IS_OPEN,
    } WockyXmppConnectionError;

The WockyXmppConnection specific errors that can occur while reading a stream.

`WOCKY_XMPP_CONNECTION_ERROR_EOS` | Connection got closed before receiving an XMPP stream close.
`WOCKY_XMPP_CONNECTION_ERROR_CLOSED` | Other side closed the xmpp stream.
`WOCKY_XMPP_CONNECTION_ERROR_NOT_OPEN` | Trying to send or receive while the connection isn't open.
`WOCKY_XMPP_CONNECTION_ERROR_IS_CLOSED` | Trying to send or receive while the connection is closed.
`WOCKY_XMPP_CONNECTION_ERROR_IS_OPEN` | Trying to send or receive the connection opening when it's already open

### wocky_xmpp_connection_error_quark ()

    GQuark              wocky_xmpp_connection_error_quark   (void);

Get the error quark used by the connection.

Returns : | the quark for connection errors.

### WOCKY_XMPP_CONNECTION_ERROR

    #define WOCKY_XMPP_CONNECTION_ERROR (wocky_xmpp_connection_error_quark ())

Get access to the error quark of the xmpp connection.

### struct WockyXmppConnectionClass

    struct WockyXmppConnectionClass {
    };

The class of a WockyXmppConnection.

### wocky_xmpp_connection_new ()

    WockyXmppConnection * wocky_xmpp_connection_new         (GIOStream *stream);

Convenience function to create a new WockyXmppConnection.

`stream` : | GIOStream over wich all the data will be sent/received.
Returns : | a new WockyXmppConnection.

### wocky_xmpp_connection_send_open_async ()

    void                wocky_xmpp_connection_send_open_async
                                                            (WockyXmppConnection *connection,
                                                             const gchar *to,
                                                             const gchar *from,
                                                             const gchar *version,
                                                             const gchar *lang,
                                                             const gchar *id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous sending of an XMPP stream opening over the stream. When the operation is finished `callback` will be called. You can then call `wocky_xmpp_connection_send_open_finish()` to get the result of the operation.

`connection` : | a WockyXmppConnection.
`to` : | destination in the XMPP opening (can be NULL).
`from` : | sender in the XMPP opening (can be NULL).
`version` : | XMPP version sent (can be NULL).
`lang` : | language sent (can be NULL).
`id` : | XMPP Stream ID, if any, or NULL
`cancellable` : | optional GCancellable object, NULL to ignore.
`callback` : | callback to call when the request is satisfied.
`user_data` : | the data to pass to callback function.

### wocky_xmpp_connection_send_open_finish ()

    gboolean            wocky_xmpp_connection_send_open_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes sending a stream opening.

`connection` : | a WockyXmppConnection.
`result` : | a GAsyncResult.
`error` : | a GError location to store the error occuring, or NULL to ignore.
Returns : | TRUE if the opening was succesfully sent, FALSE on error.

### wocky_xmpp_connection_recv_open_async ()

    void                wocky_xmpp_connection_recv_open_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous receiving of an XMPP stream opening over the stream. When the operation is finished `callback` will be called. You can then call `wocky_xmpp_connection_recv_open_finish()` to get the result of the operation.

`connection` : | a WockyXmppConnection.
`cancellable` : | optional GCancellable object, NULL to ignore.
`callback` : | callback to call when the request is satisfied.
`user_data` : | the data to pass to callback function.

### wocky_xmpp_connection_recv_open_finish ()

    gboolean            wocky_xmpp_connection_recv_open_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             gchar **to,
                                                             gchar **from,
                                                             gchar **version,
                                                             gchar **lang,
                                                             gchar **id,
                                                             GError **error);

Finishes receiving a stream opening.

`connection` : | a WockyXmppConnection.
`result` : | a GAsyncResult.
`to` : | Optional location to store the to attribute in the XMPP open stanza will be stored (free after usage).
`from` : | Optional location to store the from attribute in the XMPP open stanza will be stored (free after usage).
`version` : | Optional location to store the version attribute in the XMPP open stanza will be stored (free after usage).
`lang` : | Optional location to store the lang attribute in the XMPP open stanza will be stored (free after usage).
`id` : | Optional location to store the Session ID of the XMPP stream (free after usage)
`error` : | a GError location to store the error occuring, or NULL to ignore.
Returns : | TRUE if the opening was succesfully received, FALSE on error.

### wocky_xmpp_connection_send_stanza_async ()

    void                wocky_xmpp_connection_send_stanza_async
                                                            (WockyXmppConnection *connection,
                                                             WockyStanza *stanza,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous sending of a WockyStanza. When the operation is finished `callback` will be called. You can then call `wocky_xmpp_connection_send_stanza_finish()` to get the result of the operation.

Can only be called after wocky_xmpp_connection_send_open_async has finished its operation.

`connection` : | a WockyXmppConnection
`stanza` : | WockyStanza to send.
`cancellable` : | optional GCancellable object, NULL to ignore.
`callback` : | callback to call when the request is satisfied.
`user_data` : | the data to pass to callback function.

### wocky_xmpp_connection_send_stanza_finish ()

    gboolean            wocky_xmpp_connection_send_stanza_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes sending a stanza.

`connection` : | a WockyXmppConnection.
`result` : | a GAsyncResult.
`error` : | a GError location to store the error occuring, or NULL to ignore.
Returns : | TRUE if the stanza was succesfully sent, FALSE on error.

### wocky_xmpp_connection_recv_stanza_async ()

    void                wocky_xmpp_connection_recv_stanza_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronous receive a WockyStanza. When the operation is finished `callback` will be called. You can then call `wocky_xmpp_connection_recv_stanza_finish()` to get the result of the operation.

Can only be called after wocky_xmpp_connection_recv_open_async has finished its operation.

`connection` : | a WockyXmppConnection
`cancellable` : | optional GCancellable object, NULL to ignore.
`callback` : | callback to call when the request is satisfied.
`user_data` : | the data to pass to callback function.

### wocky_xmpp_connection_recv_stanza_finish ()

    WockyStanza *       wocky_xmpp_connection_recv_stanza_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes receiving a stanza

`connection` : | a WockyXmppConnection.
`result` : | a GAsyncResult.
`error` : | a GError location to store the error occuring, or NULL to ignore.
Returns : | A WockyStanza or NULL on error (unref after usage)

### wocky_xmpp_connection_send_close_async ()

    void                wocky_xmpp_connection_send_close_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous sending of an XMPP stream close. When the operation is finished `callback` will be called. You can then call `wocky_xmpp_connection_send_close_finish()` to get the result of the operation.

Can only be called after wocky_xmpp_connection_send_open_async has finished its operation.

`connection` : | a WockyXmppConnection.
`cancellable` : | optional GCancellable object, NULL to ignore.
`callback` : | callback to call when the request is satisfied.
`user_data` : | the data to pass to callback function.

### wocky_xmpp_connection_send_close_finish ()

    gboolean            wocky_xmpp_connection_send_close_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes send the xmpp stream close.

`connection` : | a WockyXmppConnection.
`result` : | a GAsyncResult.
`error` : | a GError location to store the error occuring, or NULL to ignore.
Returns : | TRUE on success or FALSE on error.

### wocky_xmpp_connection_force_close_async ()

    void                wocky_xmpp_connection_force_close_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### wocky_xmpp_connection_force_close_finish ()

    gboolean            wocky_xmpp_connection_force_close_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

### wocky_xmpp_connection_send_whitespace_ping_async ()

    void                wocky_xmpp_connection_send_whitespace_ping_async
                                                            (WockyXmppConnection *connection,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous sending of a whitespace ping. When the operation is finished `callback` will be called. You can then call `wocky_xmpp_connection_send_whitespace_ping_finish()` to get the result of the operation.

Can only be called after wocky_xmpp_connection_send_open_async has finished its operation.

`connection` : | a WockyXmppConnection
`cancellable` : | optional GCancellable object, NULL to ignore.
`callback` : | callback to call when the request is satisfied.
`user_data` : | the data to pass to callback function.

### wocky_xmpp_connection_send_whitespace_ping_finish ()

    gboolean            wocky_xmpp_connection_send_whitespace_ping_finish
                                                            (WockyXmppConnection *connection,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes sending a whitespace ping.

`connection` : | a WockyXmppConnection.
`result` : | a GAsyncResult.
`error` : | a GError location to store the error occuring, or NULL to ignore.
Returns : | TRUE if the ping was succesfully sent, FALSE on error.

### wocky_xmpp_connection_reset ()

    void                wocky_xmpp_connection_reset         (WockyXmppConnection *connection);

Reset the XMPP Connection. After the reset the connection is back in its initial state (as if `wocky_xmpp_connection_send_open_async()` and `wocky_xmpp_connection_recv_open_async()` were never called).

`connection` : | a WockyXmppConnection.

### wocky_xmpp_connection_new_id ()

    gchar *             wocky_xmpp_connection_new_id        (WockyXmppConnection *self);

`self` : | a WockyXmppConnection.
Returns : | A short unique string for usage as the id attribute on a stanza (free after usage).