WockyStanza

## WockyStanza WockyStanza |

## Synopsis

                        WockyStanza;
                        WockyStanzaClass;
                        WockyStanzaPrivate;
    enum                WockyStanzaType;
    enum                WockyStanzaSubType;
    WockyStanza *       wocky_stanza_new                    (const gchar *name,
                                                             const gchar *ns);
    WockyStanza *       wocky_stanza_copy                   (WockyStanza *old);
    WockyNode *         wocky_stanza_get_top_node           (WockyStanza *self);
    WockyStanza *       wocky_stanza_build                  (WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             const gchar *to,
                                                             ...);
    WockyStanza *       wocky_stanza_build_to_contact       (WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             WockyContact *to,
                                                             ...);
    void                wocky_stanza_get_type_info          (WockyStanza *stanza,
                                                             WockyStanzaType *type,
                                                             WockyStanzaSubType *sub_type);
    const gchar *       wocky_stanza_get_from               (WockyStanza *self);
    const gchar *       wocky_stanza_get_to                 (WockyStanza *self);
    WockyStanza *       wocky_stanza_build_va               (WockyStanzaType type,
                                                             WockyStanzaSubType sub_type,
                                                             const gchar *from,
                                                             const gchar *to,
                                                             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_iq_error         (WockyStanza *iq,
                                                             ...);
    WockyStanza *       wocky_stanza_build_iq_error_va      (WockyStanza *iq,
                                                             va_list ap);
    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);
    WockyContact *      wocky_stanza_get_to_contact         (WockyStanza *self);
    WockyContact *      wocky_stanza_get_from_contact       (WockyStanza *self);
    void                wocky_stanza_set_to_contact         (WockyStanza *self,
                                                             WockyContact *contact);
    void                wocky_stanza_set_from_contact       (WockyStanza *self,
                                                             WockyContact *contact);

## Object Hierarchy

      GObject
       +----WockyNodeTree
             +----WockyStanza

## Description

## Details

### WockyStanza

    typedef struct _WockyStanza WockyStanza;

### WockyStanzaClass

    typedef struct {
    } WockyStanzaClass;

The class of a WockyStanza.

### WockyStanzaPrivate

    typedef struct _WockyStanzaPrivate WockyStanzaPrivate;

### 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,
      /*< private >*/
      NUM_WOCKY_STANZA_TYPE
    } 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

### 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,
      /*< private >*/
      NUM_WOCKY_STANZA_SUB_TYPE
    } 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

### wocky_stanza_new ()

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

`name` : |
`ns` : |
Returns : |

### wocky_stanza_copy ()

    WockyStanza *       wocky_stanza_copy                   (WockyStanza *old);

`old` : |
Returns : |

### 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_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. Example:

Example 3.

    1

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

`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,
                                                             ...);

`type` : |
`sub_type` : |
`from` : |
`to` : |
`...` : |
Returns : |

### wocky_stanza_get_type_info ()

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

`stanza` : |
`type` : |
`sub_type` : |

### 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_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_build_va ()

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

`type` : |
`sub_type` : |
`from` : |
`to` : |
`ap` : |
Returns : |

### wocky_stanza_build_iq_result ()

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

`iq` : |
`...` : |
Returns : |

### wocky_stanza_build_iq_result_va ()

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

`iq` : |
`ap` : |
Returns : |

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

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

`iq` : |
`ap` : |
Returns : |

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

    WockyContact *      wocky_stanza_get_to_contact         (WockyStanza *self);

`self` : |
Returns : |

### wocky_stanza_get_from_contact ()

    WockyContact *      wocky_stanza_get_from_contact       (WockyStanza *self);

`self` : |
Returns : |

### wocky_stanza_set_to_contact ()

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

`self` : |
`contact` : |

### wocky_stanza_set_from_contact ()

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

`self` : |
`contact` : |