WockyPubsubService

## WockyPubsubService WockyPubsubService |

## Synopsis

    #define             WOCKY_PUBSUB_SERVICE_ERROR
    struct              WockyPubsubServiceClass;
    enum                WockyPubsubServiceError;
                        WockyPubsubSubscription;
    enum                WockyPubsubSubscriptionState;
    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);
    WockyPubsubNode *   wocky_pubsub_service_ensure_node    (WockyPubsubService *self,
                                                             const gchar *name);
    GQuark              wocky_pubsub_service_error_quark    (void);
    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);
    WockyPubsubNode *   wocky_pubsub_service_lookup_node    (WockyPubsubService *self,
                                                             const gchar *name);
    WockyPubsubService * wocky_pubsub_service_new           (WockySession *session,
                                                             const gchar *jid);
    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);
    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);
    WockyPubsubSubscription * wocky_pubsub_subscription_new (WockyPubsubNode *node,
                                                             const gchar *jid,
                                                             WockyPubsubSubscriptionState state,
                                                             const gchar *subid);

## Object Hierarchy

      GEnum
       +----WockyPubsubServiceError

      GBoxed
       +----WockyPubsubSubscription

      GEnum
       +----WockyPubsubSubscriptionState

## Description

## Details

### WOCKY_PUBSUB_SERVICE_ERROR

    #define WOCKY_PUBSUB_SERVICE_ERROR (wocky_pubsub_service_error_quark ())

### struct WockyPubsubServiceClass

    struct WockyPubsubServiceClass {
      GObjectClass parent_class;
      GType node_object_type;
    };

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()`

### 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

### 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”

### 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).

### 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);

### wocky_pubsub_service_create_node_finish ()

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

### 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_error_quark ()

    GQuark              wocky_pubsub_service_error_quark    (void);

### 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);

### wocky_pubsub_service_get_default_node_configuration_finish ()

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

### 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_new ()

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

### wocky_pubsub_service_retrieve_subscriptions_async ()

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

### wocky_pubsub_service_retrieve_subscriptions_finish ()

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

### wocky_pubsub_subscription_copy ()

    WockyPubsubSubscription * wocky_pubsub_subscription_copy
                                                            (WockyPubsubSubscription *sub);

### wocky_pubsub_subscription_free ()

    void                wocky_pubsub_subscription_free      (WockyPubsubSubscription *sub);

### wocky_pubsub_subscription_list_copy ()

    GList *             wocky_pubsub_subscription_list_copy (GList *subs);

### wocky_pubsub_subscription_list_free ()

    void                wocky_pubsub_subscription_list_free (GList *subs);

### wocky_pubsub_subscription_new ()

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