|  |  |  | Wocky Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | ||||
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); 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);
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.
| no sub type | |
| "available" stanza sub type | |
| "normal" stanza sub type | |
| "chat" stanza sub type | |
| "groupchat" stanza sub type | |
| "headline" stanza sub type | |
| "unavailable" stanza sub type | |
| "probe" stanza sub type | |
| "subscribe" stanza sub type | |
| "unsubscribe" stanza sub type | |
| "subscribed" stanza sub type | |
| "unsubscribed" stanza sub type | |
| "get" stanza sub type | |
| "set" stanza sub type | |
| "result" stanza sub type | |
| "error" stanza sub type | |
| unknown stanza sub type | 
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.
| no stanza type | |
| <message/>stanza | |
| <presence/>stanza | |
| <iq/>stanza | |
| <stream/>stanza | |
| <stream:features/>stanza | |
| <auth/>stanza | |
| <challenge/>stanza | |
| <response/>stanza | |
| <success/>stanza | |
| <failure/>stanza | |
| <stream:error/>stanza | |
| unknown stanza type | 
WockyStanza * wocky_stanza_build (WockyStanzaType type,WockyStanzaSubType sub_type,const gchar *from,const gchar *to,...);
Build a XMPP stanza from a list of arguments. Example:
Example 3.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | 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 <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:
Example 4.
| 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); | 
| 
 | The type of stanza to build | 
| 
 | 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.) | 
| 
 | The sender's JID, or NULLto leave it unspecified. | 
| 
 | The target's JID, or NULLto leave it unspecified. | 
| 
 | the description of the stanza to build,
terminated with NULL | 
| Returns : | a new stanza object | 
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); | 
| 
 | 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 | 
WockyStanza * wocky_stanza_build_iq_error_va (WockyStanza *iq,va_list ap);
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);
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.
| 
 | a message/iq/presence stanza | 
| 
 | location at which to store the error type | 
| 
 | location at which to store an error in the domain WOCKY_XMPP_ERROR | 
| 
 | location at which to store an error in an application-specific domain, if one is found | 
| 
 | location at which to store the node representing an application-specific error, if one is found | 
| Returns : | TRUEif the stanza had type='error';FALSEotherwise | 
gboolean wocky_stanza_extract_stream_error (WockyStanza *stanza,GError **stream_error);
| 
 | a stanza | 
| 
 | location at which to store an error in domain WOCKY_XMPP_STREAM_ERROR, if one is found. | 
| Returns : | TRUEand setsstream_errorif the stanza was indeed a stream
error. | 
const gchar *       wocky_stanza_get_from               (WockyStanza *self);
| 
 | a stanza | 
| Returns : | The sender of self, orNULLif no sender was specified. | 
const gchar *       wocky_stanza_get_to                 (WockyStanza *self);
| 
 | a stanza | 
| Returns : | The recipient of self, orNULLif no recipient was specified. | 
WockyNode *         wocky_stanza_get_top_node           (WockyStanza *self);
| 
 | a stanza | 
| Returns : | A pointer to the topmost node of the stanza | 
void wocky_stanza_get_type_info (WockyStanza *stanza,WockyStanzaType *type,WockyStanzaSubType *sub_type);
void wocky_stanza_set_from_contact (WockyStanza *self,WockyContact *contact);
void wocky_stanza_set_to_contact (WockyStanza *self,WockyContact *contact);