WockyStanza

WockyStanza

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── WockyNodeTree
        ╰── WockyStanza

Description

Functions

wocky_stanza_new ()

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

wocky_stanza_copy ()

WockyStanza *
wocky_stanza_copy (WockyStanza *old);

wocky_stanza_get_top_node ()

WockyNode *
wocky_stanza_get_top_node (WockyStanza *self);

Parameters

self

a stanza

 

Returns

A pointer to the topmost node of the stanza


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

Parameters

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

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

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

const gchar *
wocky_stanza_get_from (WockyStanza *self);

Parameters

self

a stanza

 

Returns

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


wocky_stanza_get_to ()

const gchar *
wocky_stanza_get_to (WockyStanza *self);

Parameters

self

a stanza

 

Returns

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


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

Parameters

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_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.

Parameters

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

Parameters

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

WockyContact *
wocky_stanza_get_to_contact (WockyStanza *self);

wocky_stanza_get_from_contact ()

WockyContact *
wocky_stanza_get_from_contact (WockyStanza *self);

wocky_stanza_set_to_contact ()

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

wocky_stanza_set_from_contact ()

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

Types and Values

struct WockyStanzaClass

struct WockyStanzaClass {
};

The class of a WockyStanza.


enum WockyStanzaType

XMPP stanza types.

Members

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

 

enum WockyStanzaSubType

XMPP stanza sub types.

Members

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