WockyPubsubService

## WockyPubsubService WockyPubsubService |

## Synopsis

                        WockyPubsubService;
                        WockyPubsubServiceClass;
                        WockyPubsubServicePrivate;
    enum                WockyPubsubServiceError;
    GQuark              wocky_pubsub_service_error_quark    (void);
    #define             WOCKY_PUBSUB_SERVICE_ERROR
    WockyPubsubService * wocky_pubsub_service_new           (WockySession *session,
                                                             const gchar *jid);
    WockyPubsubNode *   wocky_pubsub_service_ensure_node    (WockyPubsubService *self,
                                                             const gchar *name);
    WockyPubsubNode *   wocky_pubsub_service_lookup_node    (WockyPubsubService *self,
                                                             const gchar *name);
    void                wocky_pubsub_service_get_default_node_configuration_async
                                                            (WockyPubsubService *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    WockyDataForm *     wocky_pubsub_service_get_default_node_configuration_finish
                                                            (WockyPubsubService *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_pubsub_service_retrieve_subscriptions_async
                                                            (WockyPubsubService *self,
                                                             WockyPubsubNode *node,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_pubsub_service_retrieve_subscriptions_finish
                                                            (WockyPubsubService *self,
                                                             GAsyncResult *result,
                                                             GList **subscriptions,
                                                             GError **error);
    void                wocky_pubsub_service_create_node_async
                                                            (WockyPubsubService *self,
                                                             const gchar *name,
                                                             WockyDataForm *config,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    WockyPubsubNode *   wocky_pubsub_service_create_node_finish
                                                            (WockyPubsubService *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    enum                WockyPubsubSubscriptionState;
                        WockyPubsubSubscription;
    #define             WOCKY_TYPE_PUBSUB_SUBSCRIPTION
    GType               wocky_pubsub_subscription_get_type  (void);
    WockyPubsubSubscription * wocky_pubsub_subscription_new (WockyPubsubNode *node,
                                                             const gchar *jid,
                                                             WockyPubsubSubscriptionState state,
                                                             const gchar *subid);
    WockyPubsubSubscription * wocky_pubsub_subscription_copy
                                                            (WockyPubsubSubscription *sub);
    void                wocky_pubsub_subscription_free      (WockyPubsubSubscription *sub);
    GList *             wocky_pubsub_subscription_list_copy (GList *subs);
    void                wocky_pubsub_subscription_list_free (GList *subs);

## Object Hierarchy

      GObject
       +----WockyPubsubService

## Properties

      "jid"                      gchar*                : Read / Write / Construct Only
      "session"                  WockySession*         : Read / Write / Construct Only

## Signals

      "event-received"
      "node-deleted"                                   : Run Last
      "subscription-state-changed"                     : Run Last

## Description

## Details

### WockyPubsubService

    typedef struct _WockyPubsubService WockyPubsubService;

### WockyPubsubServiceClass

    typedef struct {
      GObjectClass parent_class;
      GType node_object_type;
    } WockyPubsubServiceClass;

The class structure for the WockyPubsubService type.

GObjectClass `parent_class`; | parent
GType `node_object_type`; | the subtype of WOCKY_TYPE_PUBSUB_NODE to be created by `wocky_pubsub_service_ensure_node()`

### WockyPubsubServicePrivate

    typedef struct _WockyPubsubServicePrivate WockyPubsubServicePrivate;

### enum WockyPubsubServiceError

    typedef enum {
      WOCKY_PUBSUB_SERVICE_ERROR_WRONG_REPLY,
    } WockyPubsubServiceError;

WockyPubsubService specific errors.

`WOCKY_PUBSUB_SERVICE_ERROR_WRONG_REPLY` | A wrong reply was received

### wocky_pubsub_service_error_quark ()

    GQuark              wocky_pubsub_service_error_quark    (void);

Returns : |

### WOCKY_PUBSUB_SERVICE_ERROR

    #define WOCKY_PUBSUB_SERVICE_ERROR (wocky_pubsub_service_error_quark ())

### wocky_pubsub_service_new ()

    WockyPubsubService * wocky_pubsub_service_new           (WockySession *session,
                                                             const gchar *jid);

`session` : |
`jid` : |
Returns : |

### wocky_pubsub_service_ensure_node ()

    WockyPubsubNode *   wocky_pubsub_service_ensure_node    (WockyPubsubService *self,
                                                             const gchar *name);

Fetches or creates an object representing a node on the pubsub service. Note that this does not ensure that a node exists on the server; it merely ensures a local representation.

`self` : | a pubsub service
`name` : | the name of a node on `self`
Returns : | a new reference to an object representing a node named `name` on `self`

### wocky_pubsub_service_lookup_node ()

    WockyPubsubNode *   wocky_pubsub_service_lookup_node    (WockyPubsubService *self,
                                                             const gchar *name);

Fetches an object representing a node on a pubsub service, if the object already exists; if not, returns `NULL`. Note that this does not check whether a node exists on the server; it only checks for a local representation.

`self` : | a pubsub service
`name` : | the name of a node on `self`
Returns : | a borrowed reference to a node, or `NULL`

### wocky_pubsub_service_get_default_node_configuration_async ()

    void                wocky_pubsub_service_get_default_node_configuration_async
                                                            (WockyPubsubService *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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

### wocky_pubsub_service_get_default_node_configuration_finish ()

    WockyDataForm *     wocky_pubsub_service_get_default_node_configuration_finish
                                                            (WockyPubsubService *self,
                                                             GAsyncResult *result,
                                                             GError **error);

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

### wocky_pubsub_service_retrieve_subscriptions_async ()

    void                wocky_pubsub_service_retrieve_subscriptions_async
                                                            (WockyPubsubService *self,
                                                             WockyPubsubNode *node,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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

### wocky_pubsub_service_retrieve_subscriptions_finish ()

    gboolean            wocky_pubsub_service_retrieve_subscriptions_finish
                                                            (WockyPubsubService *self,
                                                             GAsyncResult *result,
                                                             GList **subscriptions,
                                                             GError **error);

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

### wocky_pubsub_service_create_node_async ()

    void                wocky_pubsub_service_create_node_async
                                                            (WockyPubsubService *self,
                                                             const gchar *name,
                                                             WockyDataForm *config,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`self` : |
`name` : |
`config` : |
`cancellable` : |
`callback` : |
`user_data` : |

### wocky_pubsub_service_create_node_finish ()

    WockyPubsubNode *   wocky_pubsub_service_create_node_finish
                                                            (WockyPubsubService *self,
                                                             GAsyncResult *result,
                                                             GError **error);

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

### enum WockyPubsubSubscriptionState

    typedef enum {
        WOCKY_PUBSUB_SUBSCRIPTION_NONE,
        WOCKY_PUBSUB_SUBSCRIPTION_PENDING,
        WOCKY_PUBSUB_SUBSCRIPTION_SUBSCRIBED,
        WOCKY_PUBSUB_SUBSCRIPTION_UNCONFIGURED
    } WockyPubsubSubscriptionState;

Describes the state of a subscription to a node. Definitions are taken from XEP-0060 §4.2.

`WOCKY_PUBSUB_SUBSCRIPTION_NONE` | The node MUST NOT send event notifications or payloads to the Entity.
`WOCKY_PUBSUB_SUBSCRIPTION_PENDING` | An entity has requested to subscribe to a node and the request has not yet been approved by a node owner. The node MUST NOT send event notifications or payloads to the entity while it is in this state.
`WOCKY_PUBSUB_SUBSCRIPTION_SUBSCRIBED` | An entity has subscribed but its subscription options have not yet been configured. The node MAY send event notifications or payloads to the entity while it is in this state. The service MAY timeout unconfigured subscriptions.
`WOCKY_PUBSUB_SUBSCRIPTION_UNCONFIGURED` | An entity is subscribed to a node. The node MUST send all event notifications (and, if configured, payloads) to the entity while it is in this state (subject to subscriber configuration and content filtering).

### WockyPubsubSubscription

    typedef struct {
        WockyPubsubNode *node;
        gchar *jid;
        WockyPubsubSubscriptionState state;
        gchar *subid;
    } WockyPubsubSubscription;

Represents a subscription to a node on a pubsub service, as seen when listing your own subscriptions on a service with `wocky_pubsub_service_retrieve_subscriptions_async()` or subscribing to a node with `wocky_pubsub_node_subscribe_async()`.

WockyPubsubNode *`node`; | a PubSub node
gchar *`jid`; | the JID which is subscribed to `node`. This may be a bare JID, or a full JID with a resource, depending on which was specified when subscribing to `node`. See XEP-0060 §6.1 Subscribe to a Node
WockyPubsubSubscriptionState `state`; | the state of this subscription
gchar *`subid`; | a unique identifier for this subscription, if a JID is subscribed to a node multiple times, or `NULL` if there is no such identifier. See XEP-0060 §6.1.6 “Multiple Subscriptions”

### WOCKY_TYPE_PUBSUB_SUBSCRIPTION

    #define             WOCKY_TYPE_PUBSUB_SUBSCRIPTION

### wocky_pubsub_subscription_get_type ()

    GType               wocky_pubsub_subscription_get_type  (void);

Returns : |

### wocky_pubsub_subscription_new ()

    WockyPubsubSubscription * wocky_pubsub_subscription_new (WockyPubsubNode *node,
                                                             const gchar *jid,
                                                             WockyPubsubSubscriptionState state,
                                                             const gchar *subid);

`node` : |
`jid` : |
`state` : |
`subid` : |
Returns : |

### wocky_pubsub_subscription_copy ()

    WockyPubsubSubscription * wocky_pubsub_subscription_copy
                                                            (WockyPubsubSubscription *sub);

`sub` : |
Returns : |

### wocky_pubsub_subscription_free ()

    void                wocky_pubsub_subscription_free      (WockyPubsubSubscription *sub);

`sub` : |

### wocky_pubsub_subscription_list_copy ()

    GList *             wocky_pubsub_subscription_list_copy (GList *subs);

`subs` : |
Returns : |

### wocky_pubsub_subscription_list_free ()

    void                wocky_pubsub_subscription_list_free (GList *subs);

`subs` : |

## Property Details

### The `"jid"` property

      "jid"                      gchar*                : Read / Write / Construct Only

The jid of the pubsub service.

Default value: NULL

### The `"session"` property

      "session"                  WockySession*         : Read / Write / Construct Only

the Wocky Session associated with this pubsub service.

## Signal Details

### The `"event-received"` signal

    void                user_function                      (WockyPubsubService *service,
                                                            WockyPubsubNode    *node,
                                                            WockyStanza        *event_stanza,
                                                            gpointer            event_node,
                                                            gpointer            items_node,
                                                            gpointer            items,
                                                            gpointer            user_data)

Emitted when an event is received for a node.

`service` : | a pubsub service
`node` : | the node on `service` for which an event has been received wire
`event_stanza` : | the message/event stanza in its entirity
`event_node` : | the event node from the stanza
`items_node` : | the items node from the stanza
`items` : | a list of WockyNode *s for each item child of `items_node`
`user_data` : | user data set when the signal handler was connected.

### The `"node-deleted"` signal

    void                user_function                      (WockyPubsubService *node,
                                                            WockyPubsubNode    *stanza,
                                                            WockyStanza        *event_node,
                                                            gpointer            delete_node,
                                                            gpointer            arg4,
                                                            gpointer            user_data)        : Run Last

Emitted when a notification of a node's deletion is received from the server.

`node` : | a pubsub node
`stanza` : | the message/event stanza in its entirety
`event_node` : | the event node from `stanza`
`delete_node` : | the delete node from `stanza`
`user_data` : | user data set when the signal handler was connected.

### The `"subscription-state-changed"` signal

    void                user_function                      (WockyPubsubService      *service,
                                                            WockyPubsubNode         *node,
                                                            WockyStanza             *stanza,
                                                            gpointer                 event_node,
                                                            gpointer                 subscription_node,
                                                            WockyPubsubSubscription *subscription,
                                                            gpointer                 user_data)              : Run Last

`service` : | a pubsub service
`node` : | a pubsub node for which the subscription state has changed
`stanza` : | the message/event stanza in its entirety
`event_node` : | the event node from `stanza`
`subscription_node` : | the subscription node from `stanza`
`subscription` : | subscription information parsed from `subscription_node`
`user_data` : | user data set when the signal handler was connected.