WockyPorter

## WockyPorter WockyPorter |

## Synopsis

    #define             WOCKY_PORTER_ERROR
    #define             WOCKY_PORTER_HANDLER_PRIORITY_MAX
    #define             WOCKY_PORTER_HANDLER_PRIORITY_MIN
    #define             WOCKY_PORTER_HANDLER_PRIORITY_NORMAL
    enum                WockyPorterError;
    gboolean            (*WockyPorterHandlerFunc)           (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             gpointer user_data);
    struct              WockyPorterInterface;
    void                wocky_porter_acknowledge_iq         (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             ...);
    void                wocky_porter_close_async            (WockyPorter *porter,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_porter_close_finish           (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);
    GQuark              wocky_porter_error_quark            (void);
    void                wocky_porter_force_close_async      (WockyPorter *porter,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_porter_force_close_finish     (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);
    const gchar *       wocky_porter_get_bare_jid           (WockyPorter *self);
    const gchar *       wocky_porter_get_full_jid           (WockyPorter *self);
    const gchar *       wocky_porter_get_resource           (WockyPorter *self);
    guint               wocky_porter_register_handler_from  (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             ...);
    guint               wocky_porter_register_handler_from_anyone
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             ...);
    guint               wocky_porter_register_handler_from_anyone_by_stanza
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             WockyStanza *stanza);
    guint               wocky_porter_register_handler_from_anyone_va
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             va_list ap);
    guint               wocky_porter_register_handler_from_by_stanza
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             WockyStanza *stanza);
    guint               wocky_porter_register_handler_from_va
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             va_list ap);
    void                wocky_porter_send                   (WockyPorter *porter,
                                                             WockyStanza *stanza);
    void                wocky_porter_send_async             (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_porter_send_finish            (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_porter_send_iq_async          (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    void                wocky_porter_send_iq_error          (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             WockyXmppError error_code,
                                                             const gchar *message);
    WockyStanza *       wocky_porter_send_iq_finish         (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_porter_send_iq_gerror         (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             const GError *error);
    void                wocky_porter_start                  (WockyPorter *porter);
    void                wocky_porter_unregister_handler     (WockyPorter *porter,
                                                             guint id);

## Description

## Details

### WOCKY_PORTER_ERROR

    #define WOCKY_PORTER_ERROR (wocky_porter_error_quark ())

Get access to the error quark of the xmpp porter.

### WOCKY_PORTER_HANDLER_PRIORITY_MAX

    #define WOCKY_PORTER_HANDLER_PRIORITY_MAX G_MAXUINT

### WOCKY_PORTER_HANDLER_PRIORITY_MIN

    #define WOCKY_PORTER_HANDLER_PRIORITY_MIN 0

### WOCKY_PORTER_HANDLER_PRIORITY_NORMAL

    #define WOCKY_PORTER_HANDLER_PRIORITY_NORMAL (guint) (G_MAXUINT / 2)

### enum WockyPorterError

    typedef enum {
      WOCKY_PORTER_ERROR_NOT_STARTED,
      WOCKY_PORTER_ERROR_CLOSING,
      WOCKY_PORTER_ERROR_CLOSED,
      WOCKY_PORTER_ERROR_NOT_IQ,
      WOCKY_PORTER_ERROR_FORCIBLY_CLOSED,
    } WockyPorterError;

The WockyPorter specific errors.

`WOCKY_PORTER_ERROR_NOT_STARTED` | The WockyPorter has not been started yet
`WOCKY_PORTER_ERROR_CLOSING` | The WockyPorter is closing
`WOCKY_PORTER_ERROR_CLOSED` | The WockyPorter is closed
`WOCKY_PORTER_ERROR_NOT_IQ` | The WockyStanza is not an IQ
`WOCKY_PORTER_ERROR_FORCIBLY_CLOSED` | The WockyPorter has been forced to close

### WockyPorterHandlerFunc ()

    gboolean            (*WockyPorterHandlerFunc)           (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             gpointer user_data);

Handler called when a matching stanza has been received by the WockyPorter.

If a handler returns `TRUE`, this means that it has taken responsibility for handling the stanza and (if applicable) sending a reply.

If a handler returns `FALSE`, this indicates that it has declined to process the stanza. The next handler (if any) is invoked.

A handler must not assume that `stanza` will continue to exist after the handler has returned, unless it has taken a reference to `stanza` using `g_object_ref()`.

`porter` : | the WockyPorter dispatching the WockyStanza
`stanza` : | the WockyStanza being dispatched
`user_data` : | the data passed when the handler has been registered
Returns : | `TRUE` if the stanza has been handled, `FALSE` if not

### struct WockyPorterInterface

    struct WockyPorterInterface {
      GTypeInterface parent_iface;

      const gchar * (*get_full_jid) (WockyPorter *self);
      const gchar * (*get_bare_jid) (WockyPorter *self);
      const gchar * (*get_resource) (WockyPorter *self);

      void (*start) (WockyPorter *porter);

      void (*send_async) (WockyPorter *porter,
          WockyStanza *stanza,
          GCancellable *cancellable,
          GAsyncReadyCallback callback,
          gpointer user_data);

      gboolean (*send_finish) (WockyPorter *porter,
          GAsyncResult *result,
          GError **error);

      guint (*register_handler_from_by_stanza) (
          WockyPorter *self,
          WockyStanzaType type,
          WockyStanzaSubType sub_type,
          const gchar *from,
          guint priority,
          WockyPorterHandlerFunc callback,
          gpointer user_data,
          WockyStanza *stanza);

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

      void (*unregister_handler) (WockyPorter *self,
          guint id);

      void (*close_async) (WockyPorter *self,
          GCancellable *cancellable,
          GAsyncReadyCallback callback,
          gpointer user_data);

      gboolean (*close_finish) (WockyPorter *self,
          GAsyncResult *result,
          GError **error);

      void (*send_iq_async) (WockyPorter *porter,
          WockyStanza *stanza,
          GCancellable *cancellable,
          GAsyncReadyCallback callback,
          gpointer user_data);

      WockyStanza * (*send_iq_finish) (WockyPorter *porter,
          GAsyncResult *result,
          GError **error);

      void (*force_close_async) (WockyPorter *porter,
          GCancellable *cancellable,
          GAsyncReadyCallback callback,
          gpointer user_data);

      gboolean (*force_close_finish) (WockyPorter *porter,
          GAsyncResult *result,
          GError **error);
    };

The vtable for a porter implementation.

GTypeInterface `parent_iface`; | Fields shared with GTypeInterface.
`get_full_jid` () | Return the full JID of the user according to the porter; see `wocky_porter_get_full_jid()` for more details.
`get_bare_jid` () | Return the bare JID of the user according to the porter; see `wocky_porter_get_full_jid()` for more details.
`get_resource` () | Return the resource of the user according to the porter; see `wocky_porter_get_full_jid()` for more details.
`start` () | Start the porter; see `wocky_porter_start()` for more details.
`send_async` () | Start an asynchronous stanza send operation; see `wocky_porter_send_async()` for more details.
`send_finish` () | Finish an asynchronous stanza send operation; see `wocky_porter_send_finish()` for more details.
`register_handler_from_by_stanza` () | Register a stanza handler from a specific contact; see `wocky_porter_register_handler_from_by_stanza()` for more details.
`register_handler_from_anyone_by_stanza` () | Register a stanza hander from any contact; see `wocky_porter_register_handler_from_anyone_by_stanza()` for more details.
`unregister_handler` () | Unregister a stanza handler; see `wocky_porter_unregister_handler()` for more details.
`close_async` () | Start an asynchronous porter close operation; see `wocky_porter_close_async()` for more details.
`close_finish` () | Finish an asynchronous porter close operation; see `wocky_porter_close_finish()` for more details.
`send_iq_async` () | Start an asynchronous IQ stanza send operation; see `wocky_porter_send_iq_async()` for more details.
`send_iq_finish` () | Finish an asynchronous IQ stanza send operation; see `wocky_porter_send_iq_finish()` for more details.
`force_close_async` () | Start an asynchronous porter force close operation; see `wocky_porter_force_close_async()` for more details.
`force_close_finish` () | Finish an asynchronous porter force close operation; see `wocky_porter_force_close_finish()` for more details.

### wocky_porter_acknowledge_iq ()

    void                wocky_porter_acknowledge_iq         (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             ...);

Sends an acknowledgement for `stanza` back to the sender, as a shorthand for calling `wocky_stanza_build_iq_result()` and `wocky_porter_send()`.

`porter` : | a WockyPorter
`stanza` : | a stanza of type WOCKY_STANZA_TYPE_IQ and sub-type either WOCKY_STANZA_SUB_TYPE_SET or WOCKY_STANZA_SUB_TYPE_GET

### wocky_porter_close_async ()

    void                wocky_porter_close_async            (WockyPorter *porter,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous closing of a WockyPorter. This fires the WockyPorter::closing signal, flushes the sending queue, closes the XMPP stream and waits that the other side closes the XMPP stream as well. When this is done, `callback` is called. You can then call `wocky_porter_close_finish()` to get the result of the operation.

`porter` : | a WockyPorter
`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_porter_close_finish ()

    gboolean            wocky_porter_close_finish           (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes a close operation.

`porter` : | a WockyPorter
`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_porter_error_quark ()

    GQuark              wocky_porter_error_quark            (void);

Get the error quark used by the porter.

Returns : | the quark for porter errors.

### wocky_porter_force_close_async ()

    void                wocky_porter_force_close_async      (WockyPorter *porter,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Force the WockyPorter to close the TCP connection of the underlying WockyXmppConnection. If a close operation is pending, it will be completed with the `WOCKY_PORTER_ERROR_FORCIBLY_CLOSED` error. When the connection has been closed, `callback` will be called. You can then call `wocky_porter_force_close_finish()` to get the result of the operation.

`porter` : | a WockyPorter
`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_porter_force_close_finish ()

    gboolean            wocky_porter_force_close_finish     (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes a force close operation.

`porter` : | a WockyPorter
`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_porter_get_bare_jid ()

    const gchar *       wocky_porter_get_bare_jid           (WockyPorter *self);

`self` : | a porter
Returns : | the value of "bare-jid". [transfer none]

### wocky_porter_get_full_jid ()

    const gchar *       wocky_porter_get_full_jid           (WockyPorter *self);

`self` : | a porter
Returns : | the value of "full-jid". [transfer none]

### wocky_porter_get_resource ()

    const gchar *       wocky_porter_get_resource           (WockyPorter *self);

`self` : | a porter
Returns : | the value of "resource". [transfer none]

### wocky_porter_register_handler_from ()

    guint               wocky_porter_register_handler_from  (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             ...);

Register a new stanza handler. Stanza handlers are called when the Porter receives a new stanza matching the rules of the handler. Matching handlers are sorted by priority and are called until one claims to have handled the stanza (by returning `TRUE`).

If `from` is a bare JID, then the resource of the JID in the from attribute will be ignored: In other words, a handler registered against a bare JID will match _all_ stanzas from a JID with the same node and domain: "foo@bar.org" will match "foo@bar.org", "foo@bar.org/moose" and so forth.

To register an IQ handler from Juliet for all the Jingle stanzas related to one Jingle session:

    1
    2
    3
    4
    5
    6
    7
    8
    id = wocky_porter_register_handler (porter,
      WOCKY_STANZA_TYPE_IQ, WOCKY_STANZA_SUB_TYPE_NONE, NULL,
      WOCKY_PORTER_HANDLER_PRIORITY_NORMAL, jingle_cb,
      "juliet@example.com/Balcony",
      '(', "jingle",
        ':', "urn:xmpp:jingle:1",
        '@', "sid", "my_sid",
      ')', NULL);

To match stanzas from any sender, see `wocky_porter_register_handler_from_anyone()`. If the porter is a WockyC2SPorter, one can match stanzas sent by the server; see `wocky_c2s_porter_register_handler_from_server()`.

`self` : | A WockyPorter 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.
`from` : | the JID whose messages this handler is intended for (may not be `NULL`)
`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_porter_register_handler_from_anyone ()

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

Registers a handler for incoming stanzas from anyone, including those where the from attribute is missing.

For example, to register a handler matching all message stanzas received from anyone, call:

    1
    2
    3
    4
    id = wocky_porter_register_handler (porter,
      WOCKY_STANZA_TYPE_MESSAGE, WOCKY_STANZA_SUB_TYPE_NONE, NULL,
      WOCKY_PORTER_HANDLER_PRIORITY_NORMAL, message_received_cb, NULL,
      NULL);

As a more interesting example, the following matches incoming PEP notifications for contacts' geolocation information:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    id = wocky_porter_register_handler_from_anyone (porter,
       WOCKY_STANZA_TYPE_MESSAGE, WOCKY_STANZA_SUB_TYPE_NONE,
       WOCKY_PORTER_HANDLER_PRIORITY_MAX,
       msg_event_cb, self,
       '(', "event",
         ':', WOCKY_XMPP_NS_PUBSUB_EVENT,
         '(', "items",
           '@', "node", "http://jabber.org/protocol/geoloc",
         ')',
       ')',
       NULL);

`self` : | A WockyPorter 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_porter_register_handler_from_anyone_by_stanza ()

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

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

`self` : | A WockyPorter 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_porter_register_handler_from_anyone_va ()

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

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

`self` : | A WockyPorter 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()`.

### wocky_porter_register_handler_from_by_stanza ()

    guint               wocky_porter_register_handler_from_by_stanza
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             WockyStanza *stanza);

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

`self` : | A WockyPorter 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.
`from` : | the JID whose messages this handler is intended for (may not be `NULL`)
`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_porter_register_handler_from_va ()

    guint               wocky_porter_register_handler_from_va
                                                            (WockyPorter *self,
                                                             WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             guint priority,
                                                             WockyPorterHandlerFunc callback,
                                                             gpointer user_data,
                                                             va_list ap);

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

`self` : | A WockyPorter 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.
`from` : | the JID whose messages this handler is intended for (may not be `NULL`)
`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()`.

### wocky_porter_send ()

    void                wocky_porter_send                   (WockyPorter *porter,
                                                             WockyStanza *stanza);

Send a WockyStanza. This is a convenient function to not have to call `wocky_porter_send_async()` with lot of `NULL` arguments if you don't care to know when the stanza has been actually sent.

`porter` : | a WockyPorter
`stanza` : | the WockyStanza to send

### wocky_porter_send_async ()

    void                wocky_porter_send_async             (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous sending of a WockyStanza. When the stanza has been sent callback will be called. You can then call `wocky_porter_send_finish()` to get the result of the operation.

`porter` : | a WockyPorter
`stanza` : | the 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_porter_send_finish ()

    gboolean            wocky_porter_send_finish            (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes sending a WockyStanza.

`porter` : | a WockyPorter
`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_porter_send_iq_async ()

    void                wocky_porter_send_iq_async          (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request asynchronous sending of a WockyStanza of type `WOCKY_STANZA_TYPE_IQ` and sub-type `WOCKY_STANZA_SUB_TYPE_GET` or `WOCKY_STANZA_SUB_TYPE_SET`. When the reply to this IQ has been received callback will be called. You can then call wocky_porter_send_iq_finish to get the reply stanza.

`porter` : | a WockyPorter
`stanza` : | the 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_porter_send_iq_error ()

    void                wocky_porter_send_iq_error          (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             WockyXmppError error_code,
                                                             const gchar *message);

Sends an error reply for `stanza` back to its sender, with the given `error_code` and `message`, and including the child element from the original stanza.

To send error replies with more detailed error elements, see `wocky_porter_send_iq_gerror()`, or use `wocky_stanza_build_iq_error()` and `wocky_porter_send()` directly, possibly using `wocky_stanza_error_to_node()` to construct the error element.

`porter` : | the porter whence `stanza` came
`stanza` : | a stanza of type `WOCKY_STANZA_TYPE_IQ` and sub-type either WOCKY_STANZA_SUB_TYPE_SET or WOCKY_STANZA_SUB_TYPE_GET
`error_code` : | an XMPP Core stanza error code
`message` : | an optional error message to include with the reply. [allow-none]

### wocky_porter_send_iq_finish ()

    WockyStanza *       wocky_porter_send_iq_finish         (WockyPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the reply of an IQ query.

`porter` : | a WockyPorter
`result` : | a GAsyncResult
`error` : | a GError location to store the error occuring, or `NULL` to ignore.
Returns : | a reffed WockyStanza on success, `NULL` on error

### wocky_porter_send_iq_gerror ()

    void                wocky_porter_send_iq_gerror         (WockyPorter *porter,
                                                             WockyStanza *stanza,
                                                             const GError *error);

Sends an error reply for `stanza` back to its sender, building the `<error/>` element from the given `error`. To send error replies with simple XMPP Core stanza errors in the `WOCKY_XMPP_ERROR` domain, `wocky_porter_send_iq_error()` may be more convenient to use.

`porter` : | the porter whence `stanza` came
`stanza` : | a stanza of type `WOCKY_STANZA_TYPE_IQ` and sub-type either WOCKY_STANZA_SUB_TYPE_SET or WOCKY_STANZA_SUB_TYPE_GET
`error` : | an error whose domain is either `WOCKY_XMPP_ERROR`, some other stanza error domain supplied with Wocky (such as `WOCKY_JINGLE_ERROR` or `WOCKY_SI_ERROR`), or a custom domain registered with `wocky_xmpp_error_register_domain()`

### wocky_porter_start ()

    void                wocky_porter_start                  (WockyPorter *porter);

Start a WockyPorter to make it read and dispatch incoming stanzas.

`porter` : | a WockyPorter

### wocky_porter_unregister_handler ()

    void                wocky_porter_unregister_handler     (WockyPorter *porter,
                                                             guint id);

Unregister a registered handler. This handler won't be called when receiving stanzas anymore.

`porter` : | a WockyPorter
`id` : | the id of the handler to unregister