WockyC2SPorter

WockyC2SPorter — Wrapper around a WockyXmppConnection providing a higher level API.

Synopsis

struct              WockyC2SPorterClass;
void                wocky_c2s_porter_enable_power_saving_mode
                                                        (WockyC2SPorter *porter,
                                                         gboolean enable);
WockyPorter *       wocky_c2s_porter_new                (WockyXmppConnection *connection,
                                                         const gchar *full_jid);
guint               wocky_c2s_porter_register_handler_from_server
                                                        (WockyC2SPorter *self,
                                                         WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         guint priority,
                                                         WockyPorterHandlerFunc callback,
                                                         gpointer user_data,
                                                         ...);
guint               wocky_c2s_porter_register_handler_from_server_by_stanza
                                                        (WockyC2SPorter *self,
                                                         WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         guint priority,
                                                         WockyPorterHandlerFunc callback,
                                                         gpointer user_data,
                                                         WockyStanza *stanza);
guint               wocky_c2s_porter_register_handler_from_server_va
                                                        (WockyC2SPorter *self,
                                                         WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         guint priority,
                                                         WockyPorterHandlerFunc callback,
                                                         gpointer user_data,
                                                         va_list ap);
void                wocky_c2s_porter_send_whitespace_ping_async
                                                        (WockyC2SPorter *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            wocky_c2s_porter_send_whitespace_ping_finish
                                                        (WockyC2SPorter *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Description

Sends and receives WockyStanza from an underlying WockyXmppConnection.

Details

struct WockyC2SPorterClass

struct WockyC2SPorterClass {
};

The class of a WockyC2SPorter.


wocky_c2s_porter_enable_power_saving_mode ()

void                wocky_c2s_porter_enable_power_saving_mode
                                                        (WockyC2SPorter *porter,
                                                         gboolean enable);

Enable or disable power saving. In power saving mode, Wocky will attempt to queue "uninteresting" stanza until it is either manually flushed, until important stanza arrives, or until the power saving mode is disabled.

Queueable stanzas are:

  • <presence/> and <presence type="unavailable"/>;
  • PEP updates for a hardcoded list of namespaces.

Whenever stanza is handled, all previously queued stanzas (if any) are handled as well, in the order they arrived. This preserves stanza ordering.

Note that exiting the power saving mode will immediately handle any queued stanzas.

porter :

a WockyC2SPorter

enable :

A boolean specifying whether power saving mode should be used

wocky_c2s_porter_new ()

WockyPorter *       wocky_c2s_porter_new                (WockyXmppConnection *connection,
                                                         const gchar *full_jid);

Convenience function to create a new WockyC2SPorter.

connection :

WockyXmppConnection which will be used to receive and send WockyStanza

full_jid :

the full JID of the user

Returns :

a new WockyPorter.

wocky_c2s_porter_register_handler_from_server ()

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

Registers a handler for incoming stanzas from the local user's server; that is, stanzas with no "from" attribute, or where the sender is the user's own bare or full JID.

For example, to register a handler for roster pushes, call:

1
2
3
4
5
6
id = wocky_c2s_porter_register_handler_from_server (porter,
  WOCKY_STANZA_TYPE_MESSAGE, WOCKY_STANZA_SUB_TYPE_SET,
  WOCKY_PORTER_HANDLER_PRIORITY_NORMAL, roster_push_received_cb, NULL,
  '(',
    "query", ':', WOCKY_XMPP_NS_ROSTER,
  ')', NULL);

self :

A WockyC2SPorter 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_c2s_porter_register_handler_from_server_by_stanza ()

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

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

self :

A WockyC2SPorter 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_c2s_porter_register_handler_from_server_va ()

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

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

self :

A WockyC2SPorter 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_c2s_porter_send_whitespace_ping_async ()

void                wocky_c2s_porter_send_whitespace_ping_async
                                                        (WockyC2SPorter *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Request asynchronous sending of a whitespace ping. When the operation is finished callback will be called. You can then call wocky_c2s_porter_send_whitespace_ping_finish() to get the result of the operation. No pings are sent if there are already other stanzas or pings being sent when this function is called; it would be useless.

self :

a WockyC2SPorter

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

gboolean            wocky_c2s_porter_send_whitespace_ping_finish
                                                        (WockyC2SPorter *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes sending a whitespace ping.

self :

a WockyC2SPorter

result :

a GAsyncResult.

error :

a GError location to store the error occuring, or NULL to ignore.

Returns :

TRUE if the ping was succesfully sent, FALSE on error.