WockyC2SPorter

## WockyC2SPorter WockyC2SPorter — Wrapper around a WockyXmppConnection providing a higher level API. |

## Synopsis

    struct              WockyC2SPorterClass;
    void                wocky_c2s_porter_enable_power_saving_mode
                                                            (WockyC2SPorter *porter,
                                                             gboolean enable);
    WockyPorter *       wocky_c2s_porter_new                (WockyXmppConnection *connection,
                                                             const gchar *full_jid);
    guint               wocky_c2s_porter_register_handler_from_server
                                                            (WockyC2SPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             ...);
    guint               wocky_c2s_porter_register_handler_from_server_by_stanza
                                                            (WockyC2SPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             WockyStanza *stanza);
    guint               wocky_c2s_porter_register_handler_from_server_va
                                                            (WockyC2SPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             va_list ap);

## Description

Sends and receives WockyStanza from an underlying WockyXmppConnection.

## Details

### struct WockyC2SPorterClass

    struct WockyC2SPorterClass {
    };

The class of a WockyC2SPorter.

### wocky_c2s_porter_enable_power_saving_mode ()

    void                wocky_c2s_porter_enable_power_saving_mode
                                                            (WockyC2SPorter *porter,
                                                             gboolean enable);

Enable or disable power saving. In power saving mode, Wocky will attempt to queue "uninteresting" stanza until it is either manually flushed, until important stanza arrives, or until the power saving mode is disabled.

Queueable stanzas are: - <presence></presence> and <presence></presence> - all PEP updates

Whenever stanza is handled, all previously queued stanzas (if any) are handled as well, in the order they arrived. This preserves stanza ordering.

Note that exiting the power saving mode will immediately handle any queued stanzas.

`porter` : | a WockyC2SPorter
`enable` : | A boolean specifying whether power saving mode should be used

### wocky_c2s_porter_new ()

    WockyPorter *       wocky_c2s_porter_new                (WockyXmppConnection *connection,
                                                             const gchar *full_jid);

Convenience function to create a new WockyC2SPorter.

`connection` : | WockyXmppConnection which will be used to receive and send WockyStanza
`full_jid` : | the full JID of the user
Returns : | a new WockyPorter.

### wocky_c2s_porter_register_handler_from_server ()

    guint               wocky_c2s_porter_register_handler_from_server
                                                            (WockyC2SPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             ...);

Registers a handler for incoming stanzas from the local user's server; that is, stanzas with no "from" attribute, or where the sender is the user's own bare or full JID.

For example, to register a handler for roster pushes, call:

    1
    2
    3
    4
    5
    6
    id = wocky_c2s_porter_register_handler_from_server (porter,
      WOCKY_STANZA_TYPE_MESSAGE, WOCKY_STANZA_SUB_TYPE_SET,
      WOCKY_PORTER_HANDLER_PRIORITY_NORMAL, roster_push_received_cb, NULL,
      '(',
        "query", ':', WOCKY_XMPP_NS_ROSTER,
      ')', NULL);

`self` : | A WockyC2SPorter instance (passed to `callback`).
`type` : | The type of stanza to be handled, or WOCKY_STANZA_TYPE_NONE to match any type of stanza.
`sub_type` : | The subtype of stanza to be handled, or WOCKY_STANZA_SUB_TYPE_NONE to match any type of stanza.
`priority` : | a priority between `WOCKY_PORTER_HANDLER_PRIORITY_MIN` and `WOCKY_PORTER_HANDLER_PRIORITY_MAX` (often `WOCKY_PORTER_HANDLER_PRIORITY_NORMAL`). Handlers with a higher priority (larger number) are called first.
`callback` : | A WockyPorterHandlerFunc, which should return `FALSE` to decline the stanza (Wocky will continue to the next handler, if any), or `TRUE` to stop further processing.
`user_data` : | Passed to `callback`.
Returns : | a non-zero ID for use with `wocky_porter_unregister_handler()`.

### wocky_c2s_porter_register_handler_from_server_by_stanza ()

    guint               wocky_c2s_porter_register_handler_from_server_by_stanza
                                                            (WockyC2SPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             WockyStanza *stanza);

A WockyStanza version of `wocky_c2s_porter_register_handler_from_server()`; see that function for more details.

`self` : | A WockyC2SPorter instance (passed to `callback`).
`type` : | The type of stanza to be handled, or WOCKY_STANZA_TYPE_NONE to match any type of stanza.
`sub_type` : | The subtype of stanza to be handled, or WOCKY_STANZA_SUB_TYPE_NONE to match any type of stanza.
`priority` : | a priority between `WOCKY_PORTER_HANDLER_PRIORITY_MIN` and `WOCKY_PORTER_HANDLER_PRIORITY_MAX` (often `WOCKY_PORTER_HANDLER_PRIORITY_NORMAL`). Handlers with a higher priority (larger number) are called first.
`callback` : | A WockyPorterHandlerFunc, which should return `FALSE` to decline the stanza (Wocky will continue to the next handler, if any), or `TRUE` to stop further processing.
`user_data` : | Passed to `callback`.
`stanza` : | a WockyStanza. The handler will match a stanza only if the stanza received is a superset of the one passed to this function, as per `wocky_node_is_superset()`.
Returns : | a non-zero ID for use with `wocky_porter_unregister_handler()`.

### wocky_c2s_porter_register_handler_from_server_va ()

    guint               wocky_c2s_porter_register_handler_from_server_va
                                                            (WockyC2SPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             va_list ap);

A va_list version of `wocky_c2s_porter_register_handler_from_server()`; see that function for more details.

`self` : | A WockyC2SPorter instance (passed to `callback`).
`type` : | The type of stanza to be handled, or WOCKY_STANZA_TYPE_NONE to match any type of stanza.
`sub_type` : | The subtype of stanza to be handled, or WOCKY_STANZA_SUB_TYPE_NONE to match any type of stanza.
`priority` : | a priority between `WOCKY_PORTER_HANDLER_PRIORITY_MIN` and `WOCKY_PORTER_HANDLER_PRIORITY_MAX` (often `WOCKY_PORTER_HANDLER_PRIORITY_NORMAL`). Handlers with a higher priority (larger number) are called first.
`callback` : | A WockyPorterHandlerFunc, which should return `FALSE` to decline the stanza (Wocky will continue to the next handler, if any), or `TRUE` to stop further processing.
`user_data` : | Passed to `callback`.
`ap` : | a `wocky_stanza_build()` specification. The handler will match a stanza only if the stanza received is a superset of the one passed to this function, as per `wocky_node_is_superset()`.
Returns : | a non-zero ID for use with `wocky_porter_unregister_handler()`.