WockyStanza

WockyStanza

Synopsis

struct              WockyStanzaClass;
enum                WockyStanzaSubType;
enum                WockyStanzaType;
WockyStanza *       wocky_stanza_build                  (WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         const gchar *from,
                                                         const gchar *to,
                                                         ...);
WockyStanza *       wocky_stanza_build_iq_error         (WockyStanza *iq,
                                                         ...);
WockyStanza *       wocky_stanza_build_iq_error_va      (WockyStanza *iq,
                                                         va_list ap);
WockyStanza *       wocky_stanza_build_iq_result        (WockyStanza *iq,
                                                         ...);
WockyStanza *       wocky_stanza_build_iq_result_va     (WockyStanza *iq,
                                                         va_list ap);
WockyStanza *       wocky_stanza_build_to_contact       (WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         const gchar *from,
                                                         WockyContact *to,
                                                         ...);
WockyStanza *       wocky_stanza_build_va               (WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         const gchar *from,
                                                         const gchar *to,
                                                         va_list ap);
WockyStanza *       wocky_stanza_copy                   (WockyStanza *old);
gboolean            wocky_stanza_extract_errors         (WockyStanza *stanza,
                                                         WockyXmppErrorType *type,
                                                         GError **core,
                                                         GError **specialized,
                                                         WockyNode **specialized_node);
gboolean            wocky_stanza_extract_stream_error   (WockyStanza *stanza,
                                                         GError **stream_error);
const gchar *       wocky_stanza_get_from               (WockyStanza *self);
WockyContact *      wocky_stanza_get_from_contact       (WockyStanza *self);
const gchar *       wocky_stanza_get_to                 (WockyStanza *self);
WockyContact *      wocky_stanza_get_to_contact         (WockyStanza *self);
WockyNode *         wocky_stanza_get_top_node           (WockyStanza *self);
void                wocky_stanza_get_type_info          (WockyStanza *stanza,
                                                         WockyStanzaType *type,
                                                         WockyStanzaSubType *sub_type);
gboolean            wocky_stanza_has_type               (WockyStanza *stanza,
                                                         WockyStanzaType expected_type);
WockyStanza *       wocky_stanza_new                    (const gchar *name,
                                                         const gchar *ns);
void                wocky_stanza_set_from_contact       (WockyStanza *self,
                                                         WockyContact *contact);
void                wocky_stanza_set_to_contact         (WockyStanza *self,
                                                         WockyContact *contact);

Description

Details

struct WockyStanzaClass

struct WockyStanzaClass {
};

The class of a WockyStanza.


enum WockyStanzaSubType

typedef enum {
  WOCKY_STANZA_SUB_TYPE_NONE,
  WOCKY_STANZA_SUB_TYPE_AVAILABLE,
  WOCKY_STANZA_SUB_TYPE_NORMAL,
  WOCKY_STANZA_SUB_TYPE_CHAT,
  WOCKY_STANZA_SUB_TYPE_GROUPCHAT,
  WOCKY_STANZA_SUB_TYPE_HEADLINE,
  WOCKY_STANZA_SUB_TYPE_UNAVAILABLE,
  WOCKY_STANZA_SUB_TYPE_PROBE,
  WOCKY_STANZA_SUB_TYPE_SUBSCRIBE,
  WOCKY_STANZA_SUB_TYPE_UNSUBSCRIBE,
  WOCKY_STANZA_SUB_TYPE_SUBSCRIBED,
  WOCKY_STANZA_SUB_TYPE_UNSUBSCRIBED,
  WOCKY_STANZA_SUB_TYPE_GET,
  WOCKY_STANZA_SUB_TYPE_SET,
  WOCKY_STANZA_SUB_TYPE_RESULT,
  WOCKY_STANZA_SUB_TYPE_ERROR,
  WOCKY_STANZA_SUB_TYPE_UNKNOWN,
} WockyStanzaSubType;

XMPP stanza sub types.

WOCKY_STANZA_SUB_TYPE_NONE

no sub type

WOCKY_STANZA_SUB_TYPE_AVAILABLE

"available" stanza sub type

WOCKY_STANZA_SUB_TYPE_NORMAL

"normal" stanza sub type

WOCKY_STANZA_SUB_TYPE_CHAT

"chat" stanza sub type

WOCKY_STANZA_SUB_TYPE_GROUPCHAT

"groupchat" stanza sub type

WOCKY_STANZA_SUB_TYPE_HEADLINE

"headline" stanza sub type

WOCKY_STANZA_SUB_TYPE_UNAVAILABLE

"unavailable" stanza sub type

WOCKY_STANZA_SUB_TYPE_PROBE

"probe" stanza sub type

WOCKY_STANZA_SUB_TYPE_SUBSCRIBE

"subscribe" stanza sub type

WOCKY_STANZA_SUB_TYPE_UNSUBSCRIBE

"unsubscribe" stanza sub type

WOCKY_STANZA_SUB_TYPE_SUBSCRIBED

"subscribed" stanza sub type

WOCKY_STANZA_SUB_TYPE_UNSUBSCRIBED

"unsubscribed" stanza sub type

WOCKY_STANZA_SUB_TYPE_GET

"get" stanza sub type

WOCKY_STANZA_SUB_TYPE_SET

"set" stanza sub type

WOCKY_STANZA_SUB_TYPE_RESULT

"result" stanza sub type

WOCKY_STANZA_SUB_TYPE_ERROR

"error" stanza sub type

WOCKY_STANZA_SUB_TYPE_UNKNOWN

unknown stanza sub type

enum WockyStanzaType

typedef enum {
  WOCKY_STANZA_TYPE_NONE,
  WOCKY_STANZA_TYPE_MESSAGE,
  WOCKY_STANZA_TYPE_PRESENCE,
  WOCKY_STANZA_TYPE_IQ,
  WOCKY_STANZA_TYPE_STREAM,
  WOCKY_STANZA_TYPE_STREAM_FEATURES,
  WOCKY_STANZA_TYPE_AUTH,
  WOCKY_STANZA_TYPE_CHALLENGE,
  WOCKY_STANZA_TYPE_RESPONSE,
  WOCKY_STANZA_TYPE_SUCCESS,
  WOCKY_STANZA_TYPE_FAILURE,
  WOCKY_STANZA_TYPE_STREAM_ERROR,
  WOCKY_STANZA_TYPE_UNKNOWN,
} WockyStanzaType;

XMPP stanza types.

WOCKY_STANZA_TYPE_NONE

no stanza type

WOCKY_STANZA_TYPE_MESSAGE

<message/> stanza

WOCKY_STANZA_TYPE_PRESENCE

<presence/> stanza

WOCKY_STANZA_TYPE_IQ

<iq/> stanza

WOCKY_STANZA_TYPE_STREAM

<stream/> stanza

WOCKY_STANZA_TYPE_STREAM_FEATURES

<stream:features/> stanza

WOCKY_STANZA_TYPE_AUTH

<auth/> stanza

WOCKY_STANZA_TYPE_CHALLENGE

<challenge/> stanza

WOCKY_STANZA_TYPE_RESPONSE

<response/> stanza

WOCKY_STANZA_TYPE_SUCCESS

<success/> stanza

WOCKY_STANZA_TYPE_FAILURE

<failure/> stanza

WOCKY_STANZA_TYPE_STREAM_ERROR

<stream:error/> stanza

WOCKY_STANZA_TYPE_UNKNOWN

unknown stanza type

wocky_stanza_build ()

WockyStanza *       wocky_stanza_build                  (WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         const gchar *from,
                                                         const gchar *to,
                                                         ...);

Build a XMPP stanza from a list of arguments. For example, the following invocation:

1
2
3
4
5
6
7
8
9
10
11
wocky_stanza_build (
   WOCKY_STANZA_TYPE_MESSAGE, WOCKY_STANZA_SUB_TYPE_NONE,
   "alice@collabora.co.uk", "bob@collabora.co.uk",
   WOCKY_NODE_START, "html",
     WOCKY_NODE_XMLNS, "http://www.w3.org/1999/xhtml",
     WOCKY_NODE, "body",
       WOCKY_NODE_ATTRIBUTE, "textcolor", "red",
       WOCKY_NODE_TEXT, "Telepathy rocks!",
     WOCKY_NODE_END,
   WOCKY_NODE_END,
  NULL);

produces this stanza:

1
2
3
4
5
6
7
<message from='alice@collabora.co.uk' to='bob@collabora.co.uk'>
  <html xmlns='http://www.w3.org/1999/xhtml'>
    <body textcolor='red'>
      Telepathy rocks!
    </body>
  </html>
</message>

You may optionally use mnemonic ASCII characters in place of the build tags, to better reflect the structure of the stanza in C source. For example, the above stanza could be written as:

1
2
3
4
5
6
7
8
9
wocky_stanza_build (
   WOCKY_STANZA_TYPE_MESSAGE, WOCKY_STANZA_SUB_TYPE_NONE,
   "alice@collabora.co.uk", "bob@collabora.co.uk",
   '(', "html", ':', "http://www.w3.org/1999/xhtml",
     '(', "body", '@', "textcolor", "red",
       '$', "Telepathy rocks!",
     ')',
   ')'
  NULL);

type :

The type of stanza to build

sub_type :

The stanza's subtype; valid values depend on type. (For instance, WOCKY_STANZA_TYPE_IQ can use WOCKY_STANZA_SUB_TYPE_GET, but not WOCKY_STANZA_SUB_TYPE_SUBSCRIBED.)

from :

The sender's JID, or NULL to leave it unspecified.

to :

The target's JID, or NULL to leave it unspecified.

... :

the description of the stanza to build, terminated with NULL

Returns :

a new stanza object

wocky_stanza_build_iq_error ()

WockyStanza *       wocky_stanza_build_iq_error         (WockyStanza *iq,
                                                         ...);

Builds an error reply to iq containing the given body. This function also adds the child element of iq to the reply, as recommended by RFC3920 §9.2.3 ‘IQ Semantics’.

No <error/> element is added to the reply. To add a standard stanza error, plus message, consider using wocky_stanza_error_to_node(). To add a more complicated error with an application-specific condition, specify it when calling this function. For example:

1
2
3
4
5
6
7
8
WockyStanza *reply = wocky_stanza_build_iq_error (iq,
   '(', "error",
     '@', "type", "cancel",
     '(', "feature-not-implemented", ':', WOCKY_XMPP_NS_STANZAS, ')',
     '(', "unsupported", ':', WOCKY_XMPP_NS_PUBSUB_ERRORS,
       '@', "feature", "subscribe",
     ')',
   ')', NULL);

iq :

a stanza of type WOCKY_STANZA_TYPE_IQ and sub-type either WOCKY_STANZA_SUB_TYPE_SET or WOCKY_STANZA_SUB_TYPE_GET

... :

a wocky_stanza_build() specification

Returns :

an error reply for iq

wocky_stanza_build_iq_error_va ()

WockyStanza *       wocky_stanza_build_iq_error_va      (WockyStanza *iq,
                                                         va_list ap);

wocky_stanza_build_iq_result ()

WockyStanza *       wocky_stanza_build_iq_result        (WockyStanza *iq,
                                                         ...);

wocky_stanza_build_iq_result_va ()

WockyStanza *       wocky_stanza_build_iq_result_va     (WockyStanza *iq,
                                                         va_list ap);

wocky_stanza_build_to_contact ()

WockyStanza *       wocky_stanza_build_to_contact       (WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         const gchar *from,
                                                         WockyContact *to,
                                                         ...);

wocky_stanza_build_va ()

WockyStanza *       wocky_stanza_build_va               (WockyStanzaType type,
                                                         WockyStanzaSubType sub_type,
                                                         const gchar *from,
                                                         const gchar *to,
                                                         va_list ap);

wocky_stanza_copy ()

WockyStanza *       wocky_stanza_copy                   (WockyStanza *old);

wocky_stanza_extract_errors ()

gboolean            wocky_stanza_extract_errors         (WockyStanza *stanza,
                                                         WockyXmppErrorType *type,
                                                         GError **core,
                                                         GError **specialized,
                                                         WockyNode **specialized_node);

Given a message, iq or presence stanza with type='error', breaks it down into values describing the error. type and core are guaranteed to be set; specialized and specialized_node will be set if a recognised application-specific error is found, and the latter will be set to NULL if no application-specific error is found.

Any or all of the out parameters may be NULL to ignore the value. The value stored in specialized_node is borrowed from stanza, and is only valid as long as the latter is alive.

stanza :

a message/iq/presence stanza

type :

location at which to store the error type

core :

location at which to store an error in the domain WOCKY_XMPP_ERROR

specialized :

location at which to store an error in an application-specific domain, if one is found

specialized_node :

location at which to store the node representing an application-specific error, if one is found

Returns :

TRUE if the stanza had type='error'; FALSE otherwise

wocky_stanza_extract_stream_error ()

gboolean            wocky_stanza_extract_stream_error   (WockyStanza *stanza,
                                                         GError **stream_error);

stanza :

a stanza

stream_error :

location at which to store an error in domain WOCKY_XMPP_STREAM_ERROR, if one is found.

Returns :

TRUE and sets stream_error if the stanza was indeed a stream error.

wocky_stanza_get_from ()

const gchar *       wocky_stanza_get_from               (WockyStanza *self);

self :

a stanza

Returns :

The sender of self, or NULL if no sender was specified.

wocky_stanza_get_from_contact ()

WockyContact *      wocky_stanza_get_from_contact       (WockyStanza *self);

wocky_stanza_get_to ()

const gchar *       wocky_stanza_get_to                 (WockyStanza *self);

self :

a stanza

Returns :

The recipient of self, or NULL if no recipient was specified.

wocky_stanza_get_to_contact ()

WockyContact *      wocky_stanza_get_to_contact         (WockyStanza *self);

wocky_stanza_get_top_node ()

WockyNode *         wocky_stanza_get_top_node           (WockyStanza *self);

self :

a stanza

Returns :

A pointer to the topmost node of the stanza

wocky_stanza_get_type_info ()

void                wocky_stanza_get_type_info          (WockyStanza *stanza,
                                                         WockyStanzaType *type,
                                                         WockyStanzaSubType *sub_type);

wocky_stanza_has_type ()

gboolean            wocky_stanza_has_type               (WockyStanza *stanza,
                                                         WockyStanzaType expected_type);

wocky_stanza_new ()

WockyStanza *       wocky_stanza_new                    (const gchar *name,
                                                         const gchar *ns);

wocky_stanza_set_from_contact ()

void                wocky_stanza_set_from_contact       (WockyStanza *self,
                                                         WockyContact *contact);

wocky_stanza_set_to_contact ()

void                wocky_stanza_set_to_contact         (WockyStanza *self,
                                                         WockyContact *contact);