wocky-pubsub-helpers

## wocky-pubsub-helpers wocky-pubsub-helpers |

## Synopsis

    WockyStanza *       wocky_pubsub_make_event_stanza      (const gchar *node,
                                                             const gchar *from,
                                                             WockyNode **item_out);
    WockyStanza *       wocky_pubsub_make_stanza            (const gchar *service,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *pubsub_ns,
                                                             const gchar *action_name,
                                                             WockyNode **pubsub_node,
                                                             WockyNode **action_node);
    WockyStanza *       wocky_pubsub_make_publish_stanza    (const gchar *service,
                                                             const gchar *node,
                                                             WockyNode **pubsub_out,
                                                             WockyNode **publish_out,
                                                             WockyNode **item_out);
    gboolean            wocky_pubsub_distill_iq_reply       (GObject *source,
                                                             GAsyncResult *res,
                                                             const gchar *pubsub_ns,
                                                             const gchar *child_name,
                                                             WockyNodeTree **child_out,
                                                             GError **error);
    gboolean            wocky_pubsub_distill_ambivalent_iq_reply
                                                            (GObject *source,
                                                             GAsyncResult *res,
                                                             const gchar *pubsub_ns,
                                                             const gchar *child_name,
                                                             WockyNodeTree **child_out,
                                                             GError **error);
    gboolean            wocky_pubsub_distill_void_iq_reply  (GObject *source,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            wocky_pubsub_distill_stanza         (WockyStanza *result,
                                                             const gchar *pubsub_ns,
                                                             const gchar *child_name,
                                                             gboolean body_optional,
                                                             WockyNodeTree **child_out,
                                                             GError **error);

## Description

## Details

### wocky_pubsub_make_event_stanza ()

    WockyStanza *       wocky_pubsub_make_event_stanza      (const gchar *node,
                                                             const gchar *from,
                                                             WockyNode **item_out);

Generates a new message stanza to send to other contacts about an updated PEP node.

Note that this should only be used in link-local connections. Regular pubsub consists of making a publish stanza with `wocky_pubsub_make_publish_stanza()` and sending it to your own server. The server will then send the event stanza on to your contacts who have the appropriate capability.

`node` : | the the name of the pubsub node; may not be `NULL`
`from` : | a JID to use as the 'from' attribute, or `NULL`
`item_out` : | a location to store the `item` WockyNode, or `NULL`
Returns : | a new WockyStanza pubsub event stanza; free with `g_object_unref()`

### wocky_pubsub_make_stanza ()

    WockyStanza *       wocky_pubsub_make_stanza            (const gchar *service,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *pubsub_ns,
                                                             const gchar *action_name,
                                                             WockyNode **pubsub_node,
                                                             WockyNode **action_node);

`service` : | the JID of a PubSub service, or `NULL`
`sub_type` : |
`pubsub_ns` : | the namespace for the <pubsub/> node of the stanza
`action_name` : | the action node to add to <pubsub/>
`pubsub_node` : | address at which to store a pointer to the <pubsub/> node
`action_node` : | address at wihch to store a pointer to the <`action`/> node
Returns : | a new iq[type='set']/pubsub/`action` stanza

### wocky_pubsub_make_publish_stanza ()

    WockyStanza *       wocky_pubsub_make_publish_stanza    (const gchar *service,
                                                             const gchar *node,
                                                             WockyNode **pubsub_out,
                                                             WockyNode **publish_out,
                                                             WockyNode **item_out);

`service` : | the JID of a PubSub service, or `NULL`
`node` : | the name of a node on `service`; may not be `NULL`
`pubsub_out` : | address at which to store a pointer to the <pubsub/> node
`publish_out` : | address at which to store a pointer to the <publish/> node
`item_out` : | address at which to store a pointer to the <item/> node
Returns : | a new iq[type='set']/pubsub/publish/item stanza

### wocky_pubsub_distill_iq_reply ()

    gboolean            wocky_pubsub_distill_iq_reply       (GObject *source,
                                                             GAsyncResult *res,
                                                             const gchar *pubsub_ns,
                                                             const gchar *child_name,
                                                             WockyNodeTree **child_out,
                                                             GError **error);

Helper function to finish a `wocky_porter_send_iq_async()` operation and extract a particular pubsub child from the resulting reply, if needed.

`source` : | a WockyPorter instance
`res` : | a result passed to the callback for `wocky_porter_send_iq_async()`
`pubsub_ns` : | the namespace of the <pubsub/> node expected in this reply (such as WOCKY_XMPP_NS_PUBSUB), or `NULL` if one is not expected
`child_name` : | the name of the child of <pubsub/> expected in this reply (such as "subscriptions"); ignored if `pubsub_ns` is `NULL`
`child_out` : | location at which to store a reference to the node tree at `child_name`, or `NULL` if you don't need it.
`error` : | location at which to store an error if the call to `wocky_porter_send_iq_async()` returned an error, or if the reply was an error
Returns : | `TRUE` if the desired pubsub child was found; `FALSE` if sending the IQ failed, the reply had type='error', or the pubsub child was not found, with `error` set appropriately.

### wocky_pubsub_distill_ambivalent_iq_reply ()

    gboolean            wocky_pubsub_distill_ambivalent_iq_reply
                                                            (GObject *source,
                                                             GAsyncResult *res,
                                                             const gchar *pubsub_ns,
                                                             const gchar *child_name,
                                                             WockyNodeTree **child_out,
                                                             GError **error);

Helper function to finish a `wocky_porter_send_iq_async()` operation and extract a particular pubsub child from the resulting reply, if it is present. This is like `wocky_pubsub_distill_iq_reply()`, but is ambivalent as to whether the <pubsub/> structure has to be included.

`source` : | a WockyPorter instance
`res` : | a result passed to the callback for `wocky_porter_send_iq_async()`
`pubsub_ns` : | the namespace of the <pubsub/> node accepted in this reply (such as WOCKY_XMPP_NS_PUBSUB)
`child_name` : | the name of the child of <pubsub/> accepted in this reply (such as "subscriptions")
`child_out` : | location at which to store a reference to the node tree at `child_name`, if it is found, or to be set to `NULL` if it is not found
`error` : | location at which to store an error if the call to `wocky_porter_send_iq_async()` returned an error, or if the reply was an error
Returns : | `TRUE` if the IQ was a success; `FALSE` if sending the IQ failed or the reply had type='error', with `error` set appropriately.

### wocky_pubsub_distill_void_iq_reply ()

    gboolean            wocky_pubsub_distill_void_iq_reply  (GObject *source,
                                                             GAsyncResult *res,
                                                             GError **error);

Helper function to finish a `wocky_porter_send_iq_async()` operation where no pubsub child is expected in the resulting reply.

`source` : | a WockyPorter instance
`res` : | a result passed to the callback for `wocky_porter_send_iq_async()`
`error` : | location at which to store an error if the call to `wocky_porter_send_iq_async()` returned an error, or if the reply was an error
Returns : | `TRUE` if the IQ was a success; `FALSE` if sending the IQ failed or the reply had type='error', with `error` set appropriately.

### wocky_pubsub_distill_stanza ()

    gboolean            wocky_pubsub_distill_stanza         (WockyStanza *result,
                                                             const gchar *pubsub_ns,
                                                             const gchar *child_name,
                                                             gboolean body_optional,
                                                             WockyNodeTree **child_out,
                                                             GError **error);

Helper function to extract a particular pubsub child node from a reply, if it is present. If `body_optional` is `FALSE`, the <pubsub><`child_name`/></pubsub> tree being absent is not considered an error: `child_out` is set to `NULL` and the function returns `TRUE`.

If you are happy to delegate calling `wocky_porter_send_iq_finish()` and extracting stanza errors, you would probably be better served by one of `wocky_pubsub_distill_iq_reply()` or `wocky_pubsub_distill_ambivalent_iq_reply()`.

`result` : | an iq type='result'
`pubsub_ns` : | the namespace of the <pubsub/> node expected in this reply (such as WOCKY_XMPP_NS_PUBSUB)
`child_name` : | the name of the child of <pubsub/> expected in this reply (such as "subscriptions")
`body_optional` : | If `TRUE`, the child being absent is not considered an error
`child_out` : | location at which to store a reference to the node tree at `child_name`, if it is found, or to be set to `NULL` if it is not.
`error` : | location at which to store an error if the child node is not found and `body_optional` is `FALSE`
Returns : | `TRUE` if the child was found or was optional; `FALSE` with `error` set otherwise.