WockyPubsubNode

## WockyPubsubNode WockyPubsubNode |

## Synopsis

                        WockyPubsubNodeClass;
                        WockyPubsubNodePrivate;
    const gchar *       wocky_pubsub_node_get_name          (WockyPubsubNode *self);
    WockyStanza *       wocky_pubsub_node_make_publish_stanza
                                                            (WockyPubsubNode *self,
                                                             WockyNode **pubsub_out,
                                                             WockyNode **publish_out,
                                                             WockyNode **item_out);
    void                wocky_pubsub_node_subscribe_async   (WockyPubsubNode *self,
                                                             const gchar *jid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    WockyPubsubSubscription * wocky_pubsub_node_subscribe_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_pubsub_node_unsubscribe_async (WockyPubsubNode *self,
                                                             const gchar *jid,
                                                             const gchar *subid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_pubsub_node_unsubscribe_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_pubsub_node_delete_async      (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_pubsub_node_delete_finish     (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_pubsub_node_list_subscribers_async
                                                            (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_pubsub_node_list_subscribers_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GList **subscribers,
                                                             GError **error);
    enum                WockyPubsubAffiliationState;
                        WockyPubsubAffiliation;
    #define             WOCKY_TYPE_PUBSUB_AFFILIATION
    GType               wocky_pubsub_affiliation_get_type   (void);
    WockyPubsubAffiliation * wocky_pubsub_affiliation_new   (WockyPubsubNode *node,
                                                             const gchar *jid,
                                                             WockyPubsubAffiliationState state);
    WockyPubsubAffiliation * wocky_pubsub_affiliation_copy  (WockyPubsubAffiliation *aff);
    void                wocky_pubsub_affiliation_free       (WockyPubsubAffiliation *aff);
    GList *             wocky_pubsub_affiliation_list_copy  (GList *affs);
    void                wocky_pubsub_affiliation_list_free  (GList *affs);
    void                wocky_pubsub_node_list_affiliates_async
                                                            (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_pubsub_node_list_affiliates_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GList **affiliates,
                                                             GError **error);
    void                wocky_pubsub_node_modify_affiliates_async
                                                            (WockyPubsubNode *self,
                                                             const GList *affiliates,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_pubsub_node_modify_affiliates_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_pubsub_node_get_configuration_async
                                                            (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    WockyDataForm *     wocky_pubsub_node_get_configuration_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);

## Description

## Details

### WockyPubsubNodeClass

    typedef struct {
    } WockyPubsubNodeClass;

The class of a WockyPubsubNode.

### WockyPubsubNodePrivate

    typedef struct _WockyPubsubNodePrivate WockyPubsubNodePrivate;

### wocky_pubsub_node_get_name ()

    const gchar *       wocky_pubsub_node_get_name          (WockyPubsubNode *self);

`self` : |
Returns : |

### wocky_pubsub_node_make_publish_stanza ()

    WockyStanza *       wocky_pubsub_node_make_publish_stanza
                                                            (WockyPubsubNode *self,
                                                             WockyNode **pubsub_out,
                                                             WockyNode **publish_out,
                                                             WockyNode **item_out);

`self` : |
`pubsub_out` : |
`publish_out` : |
`item_out` : |
Returns : |

### wocky_pubsub_node_subscribe_async ()

    void                wocky_pubsub_node_subscribe_async   (WockyPubsubNode *self,
                                                             const gchar *jid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Attempts to subscribe to `self`.

`self` : | a pubsub node
`jid` : | the JID to use as the subscribed JID (usually the connection's bare or full JID); may not be `NULL`
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is completed
`user_data` : | data to pass to `callback`

### wocky_pubsub_node_subscribe_finish ()

    WockyPubsubSubscription * wocky_pubsub_node_subscribe_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);

`self` : |
`result` : |
`error` : |
Returns : |

### wocky_pubsub_node_unsubscribe_async ()

    void                wocky_pubsub_node_unsubscribe_async (WockyPubsubNode *self,
                                                             const gchar *jid,
                                                             const gchar *subid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Attempts to unsubscribe from `self`.

`self` : | a pubsub node
`jid` : | the JID subscribed to `self` (usually the connection's bare or full JID); may not be `NULL`
`subid` : | the identifier associated with the subscription
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is completed
`user_data` : | data to pass to `callback`

### wocky_pubsub_node_unsubscribe_finish ()

    gboolean            wocky_pubsub_node_unsubscribe_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);

`self` : |
`result` : |
`error` : |
Returns : |

### wocky_pubsub_node_delete_async ()

    void                wocky_pubsub_node_delete_async      (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`self` : |
`cancellable` : |
`callback` : |
`user_data` : |

### wocky_pubsub_node_delete_finish ()

    gboolean            wocky_pubsub_node_delete_finish     (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);

`self` : |
`result` : |
`error` : |
Returns : |

### wocky_pubsub_node_list_subscribers_async ()

    void                wocky_pubsub_node_list_subscribers_async
                                                            (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves the list of subscriptions to a node you own. `callback` may complete the call using `wocky_pubsub_node_list_subscribers_finish()`.

(A note on naming: this is §8.8.1 — Retrieve Subscriptions List — in XEP-0060, not to be confused with §5.6 — Retrieve Subscriptions. The different terminology in Wocky is intended to help disambiguate!)

`self` : | a pubsub node
`cancellable` : | optional GCancellable object
`callback` : | function to call when the subscribers have been retrieved or an error has occured
`user_data` : | data to pass to `callback`.

### wocky_pubsub_node_list_subscribers_finish ()

    gboolean            wocky_pubsub_node_list_subscribers_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GList **subscribers,
                                                             GError **error);

Completes a call to `wocky_pubsub_node_list_subscribers_async()`. The list returned in `subscribers` should be freed with `wocky_pubsub_subscription_list_free()` when it is no longer needed.

`self` : | a pubsub node
`result` : | the result passed to a callback
`subscribers` : | location at which to store a list of WockyPubsubSubscription pointers, or `NULL`
`error` : | location at which to store an error, or `NULL`
Returns : | `TRUE` if the list of subscribers was successfully retrieved; `FALSE` and sets `error` if an error occured.

### enum WockyPubsubAffiliationState

    typedef enum {
        WOCKY_PUBSUB_AFFILIATION_OWNER,
        WOCKY_PUBSUB_AFFILIATION_PUBLISHER,
        WOCKY_PUBSUB_AFFILIATION_PUBLISH_ONLY,
        WOCKY_PUBSUB_AFFILIATION_MEMBER,
        WOCKY_PUBSUB_AFFILIATION_NONE,
        WOCKY_PUBSUB_AFFILIATION_OUTCAST
    } WockyPubsubAffiliationState;

Possible affiliations to a PubSub node, which determine privileges an entity has. See XEP-0060 §4.1 for the details.

`WOCKY_PUBSUB_AFFILIATION_OWNER` | Owner
`WOCKY_PUBSUB_AFFILIATION_PUBLISHER` | Publisher
`WOCKY_PUBSUB_AFFILIATION_PUBLISH_ONLY` | Publish-Only
`WOCKY_PUBSUB_AFFILIATION_MEMBER` | Member
`WOCKY_PUBSUB_AFFILIATION_NONE` | None
`WOCKY_PUBSUB_AFFILIATION_OUTCAST` | Outcast

### WockyPubsubAffiliation

    typedef struct {
        WockyPubsubNode *node;
        gchar *jid;
        WockyPubsubAffiliationState state;
    } WockyPubsubAffiliation;

Represents an affiliation to a node, as returned by `wocky_pubsub_node_list_affiliates_finish()`.

WockyPubsubNode *`node`; | the node to which this affiliation relates
gchar *`jid`; | the bare JID affiliated to `node`
WockyPubsubAffiliationState `state`; | the state of `jid`'s affiliation to `node`

### WOCKY_TYPE_PUBSUB_AFFILIATION

    #define             WOCKY_TYPE_PUBSUB_AFFILIATION

### wocky_pubsub_affiliation_get_type ()

    GType               wocky_pubsub_affiliation_get_type   (void);

Returns : |

### wocky_pubsub_affiliation_new ()

    WockyPubsubAffiliation * wocky_pubsub_affiliation_new   (WockyPubsubNode *node,
                                                             const gchar *jid,
                                                             WockyPubsubAffiliationState state);

`node` : | a node
`jid` : | the JID affiliated to `node`
`state` : | the state of `jid`'s affiliation to `node`
Returns : | a new structure representing an affiliation, which should ultimately be freed with `wocky_pubsub_affiliation_free()`

### wocky_pubsub_affiliation_copy ()

    WockyPubsubAffiliation * wocky_pubsub_affiliation_copy  (WockyPubsubAffiliation *aff);

`aff` : | an existing affiliation structure
Returns : | a duplicate of `aff`; the duplicate should ultimately be freed with `wocky_pubsub_affiliation_free()`

### wocky_pubsub_affiliation_free ()

    void                wocky_pubsub_affiliation_free       (WockyPubsubAffiliation *aff);

Frees an affiliation, previously allocated with `wocky_pubsub_affiliation_new()` or `wocky_pubsub_affiliation_copy()`

`aff` : | an affiliation

### wocky_pubsub_affiliation_list_copy ()

    GList *             wocky_pubsub_affiliation_list_copy  (GList *affs);

Shorthand for manually copying `affs`, duplicating each element with `wocky_pubsub_affiliation_copy()`.

`affs` : | a list of WockyPubsubAffiliation
Returns : | a deep copy of `affs`, which should ultimately be freed with `wocky_pubsub_affiliation_list_free()`.

### wocky_pubsub_affiliation_list_free ()

    void                wocky_pubsub_affiliation_list_free  (GList *affs);

Frees a list of WockyPubsubAffiliation structures, as shorthand for calling `wocky_pubsub_affiliation_free()` for each element, followed by `g_list_free()`.

`affs` : | a list of WockyPubsubAffiliation

### wocky_pubsub_node_list_affiliates_async ()

    void                wocky_pubsub_node_list_affiliates_async
                                                            (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves the list of entities affilied to a node you own. `callback` may complete the call using `wocky_pubsub_node_list_affiliates_finish()`.

(A note on naming: this is §8.9.1 — Retrieve Affiliations List — in XEP-0060, not to be confused with §5.7 — Retrieve Affiliations. The slightly different terminology in Wocky is intended to help disambiguate!)

`self` : | a pubsub node
`cancellable` : | optional GCancellable object
`callback` : | function to call when the affiliates have been retrieved or an error has occured
`user_data` : | data to pass to `callback`.

### wocky_pubsub_node_list_affiliates_finish ()

    gboolean            wocky_pubsub_node_list_affiliates_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GList **affiliates,
                                                             GError **error);

Completes a call to `wocky_pubsub_node_list_affiliates_async()`. The list returned in `affiliates` should be freed with `wocky_pubsub_affiliation_list_free()` when it is no longer needed.

`self` : | a pubsub node
`result` : | the result passed to a callback
`affiliates` : | location at which to store a list of WockyPubsubAffiliation pointers, or `NULL`
`error` : | location at which to store an error, or `NULL`
Returns : | `TRUE` if the list of subscribers was successfully retrieved; `FALSE` and sets `error` if an error occured.

### wocky_pubsub_node_modify_affiliates_async ()

    void                wocky_pubsub_node_modify_affiliates_async
                                                            (WockyPubsubNode *self,
                                                             const GList *affiliates,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Modifies the entities affiliated to a node that you own.

`self` : | a pubsub node
`affiliates` : | a list of WockyPubsubAffiliation structures, describing only the affiliations which should be changed.
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is completed
`user_data` : | data to pass to `callback`

### wocky_pubsub_node_modify_affiliates_finish ()

    gboolean            wocky_pubsub_node_modify_affiliates_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete a call to `wocky_pubsub_node_modify_affiliates_async()`.

`self` : | a node
`result` : | the result
`error` : | location at which to store an error, if one occurred.
Returns : | `TRUE` if the affiliates were successfully modified; `FALSE` and sets `error` otherwise.

### wocky_pubsub_node_get_configuration_async ()

    void                wocky_pubsub_node_get_configuration_async
                                                            (WockyPubsubNode *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves the current configuration for a node owned by the user.

`self` : | a node
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the request is completed
`user_data` : | data to pass to `callback`

### wocky_pubsub_node_get_configuration_finish ()

    WockyDataForm *     wocky_pubsub_node_get_configuration_finish
                                                            (WockyPubsubNode *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete a call to `wocky_pubsub_node_get_configuration_async()`.

`self` : | a node
`result` : | the result
`error` : | location at which to store an error, if one occurred.
Returns : | a form representing the node configuration on success; `NULL` and sets `error` otherwise