WockyDataForm

## WockyDataForm WockyDataForm — An object to represent an XMPP data form |

## Synopsis

    #include <wocky/wocky-data-form.h>

    enum                WockyDataFormFieldType;
                        WockyDataFormFieldOption;
                        WockyDataFormField;
                        WockyDataForm;
                        WockyDataFormClass;
                        WockyDataFormPrivate;
    enum                WockyDataFormError;
    GQuark              wocky_data_form_error_quark         (void);
    #define             WOCKY_DATA_FORM_ERROR
    WockyDataForm *     wocky_data_form_new_from_form       (WockyNode *node,
                                                             GError **error);
    gboolean            wocky_data_form_set_type            (WockyDataForm *self,
                                                             const gchar *form_type);
    gboolean            wocky_data_form_set_boolean         (WockyDataForm *self,
                                                             const gchar *field_name,
                                                             gboolean field_value,
                                                             gboolean create_if_missing);
    gboolean            wocky_data_form_set_string          (WockyDataForm *self,
                                                             const gchar *field_name,
                                                             const gchar *field_value,
                                                             gboolean create_if_missing);
    gboolean            wocky_data_form_set_strv            (WockyDataForm *self,
                                                             const gchar *field_name,
                                                             const gchar * const *field_values,
                                                             gboolean create_if_missing);
    void                wocky_data_form_submit              (WockyDataForm *self,
                                                             WockyNode *node);
    gboolean            wocky_data_form_parse_result        (WockyDataForm *self,
                                                             WockyNode *node,
                                                             GError **error);
    const gchar *       wocky_data_form_get_title           (WockyDataForm *self);
    const gchar *       wocky_data_form_get_instructions    (WockyDataForm *self);

## Object Hierarchy

      GObject
       +----WockyDataForm

## Properties

      "instructions"             gchar*                : Read / Write / Construct Only
      "title"                    gchar*                : Read / Write / Construct Only

## Description

An object that represents an XMPP data form as described in XEP-0004.

## Details

### enum WockyDataFormFieldType

    typedef enum
    {
      WOCKY_DATA_FORM_FIELD_TYPE_UNSPECIFIED, /*< skip >*/
      WOCKY_DATA_FORM_FIELD_TYPE_BOOLEAN,
      WOCKY_DATA_FORM_FIELD_TYPE_FIXED,
      WOCKY_DATA_FORM_FIELD_TYPE_HIDDEN,
      WOCKY_DATA_FORM_FIELD_TYPE_JID_MULTI,
      WOCKY_DATA_FORM_FIELD_TYPE_JID_SINGLE,
      WOCKY_DATA_FORM_FIELD_TYPE_LIST_MULTI,
      WOCKY_DATA_FORM_FIELD_TYPE_LIST_SINGLE,
      WOCKY_DATA_FORM_FIELD_TYPE_TEXT_MULTI,
      WOCKY_DATA_FORM_FIELD_TYPE_TEXT_PRIVATE,
      WOCKY_DATA_FORM_FIELD_TYPE_TEXT_SINGLE
    } WockyDataFormFieldType;

Data form field types, as documented in XEP-0004 §3.3.

`WOCKY_DATA_FORM_FIELD_TYPE_UNSPECIFIED` | Unspecified field type
`WOCKY_DATA_FORM_FIELD_TYPE_BOOLEAN` | Boolean field type
`WOCKY_DATA_FORM_FIELD_TYPE_FIXED` | Fixed description field type
`WOCKY_DATA_FORM_FIELD_TYPE_HIDDEN` | Hidden field type
`WOCKY_DATA_FORM_FIELD_TYPE_JID_MULTI` | A list of multiple JIDs
`WOCKY_DATA_FORM_FIELD_TYPE_JID_SINGLE` | A single JID
`WOCKY_DATA_FORM_FIELD_TYPE_LIST_MULTI` | Many options to choose one or more from
`WOCKY_DATA_FORM_FIELD_TYPE_LIST_SINGLE` | Many options to choose one from
`WOCKY_DATA_FORM_FIELD_TYPE_TEXT_MULTI` | Multiple lines of text
`WOCKY_DATA_FORM_FIELD_TYPE_TEXT_PRIVATE` | A single line of text that should be obscured (by, say, asterisks)
`WOCKY_DATA_FORM_FIELD_TYPE_TEXT_SINGLE` | A single line of text

### WockyDataFormFieldOption

    typedef struct {
      gchar *label;
      gchar *value;
    } WockyDataFormFieldOption;

A single data form field option.

gchar *`label`; | the option label
gchar *`value`; | the option value

### WockyDataFormField

    typedef struct {
      WockyDataFormFieldType type;
      gchar *var;
      gchar *label;
      gchar *desc;
      gboolean required;
      GValue *default_value;
      GValue *value;
      /* for LIST_MULTI and LIST_SINGLE only.
       * List of (WockyDataFormFieldOption *)*/
      GSList *options;
    } WockyDataFormField;

Details about a single data form field in a WockyDataForm.

WockyDataFormFieldType `type`; | the type of the field
gchar *`var`; | the field name
gchar *`label`; | the label of the field
gchar *`desc`; | the description of the field
gboolean `required`; | `TRUE` if the field is required, otherwise `FALSE`
GValue *`default_value`; | the default of the field
GValue *`value`; | the field value
GSList *`options`; | a GSList of WockyDataFormFieldOptions if `type` if `WOCKY_DATA_FORM_FIELD_TYPE_LIST_MULTI` or `WOCKY_DATA_FORM_FIELD_TYPE_LIST_SINGLE`

### WockyDataForm

    typedef struct {
      /* (gchar *) owned by the WockyDataFormField =>
       * borrowed (WockyDataFormField *) */
      GHashTable *fields;
      /* list containing owned (WockyDataFormField *) in the order they
       * have been presented in the form */
      GSList *fields_list;

      /* list of GSList * of (WockyDataFormField *), representing one or more sets
       * of results */
      GSList *results;
    } WockyDataForm;

An object that represents an XMPP data form as described in XEP-0004.

GHashTable *`fields`; | a GHashTable of strings to WockyDataFormFields
GSList *`fields_list`; | a list of WockyDataFormFields in the order they have been presented in the form
GSList *`results`; | a list of GSLists of WockyDataFormFields representing one or more sets of result.

### WockyDataFormClass

    typedef struct {
    } WockyDataFormClass;

The class of a WockyDataForm.

### WockyDataFormPrivate

    typedef struct _WockyDataFormPrivate WockyDataFormPrivate;

### enum WockyDataFormError

    typedef enum {
      WOCKY_DATA_FORM_ERROR_NOT_FORM,
      WOCKY_DATA_FORM_ERROR_WRONG_TYPE,
    } WockyDataFormError;

WockyDataForm specific errors.

`WOCKY_DATA_FORM_ERROR_NOT_FORM` | Node is not a data form
`WOCKY_DATA_FORM_ERROR_WRONG_TYPE` | Data form is of the wrong type

### wocky_data_form_error_quark ()

    GQuark              wocky_data_form_error_quark         (void);

Returns : |

### WOCKY_DATA_FORM_ERROR

    #define WOCKY_DATA_FORM_ERROR (wocky_data_form_error_quark ())

### wocky_data_form_new_from_form ()

    WockyDataForm *     wocky_data_form_new_from_form       (WockyNode *node,
                                                             GError **error);

`node` : |
`error` : |
Returns : |

### wocky_data_form_set_type ()

    gboolean            wocky_data_form_set_type            (WockyDataForm *self,
                                                             const gchar *form_type);

Creates a hidden FORM_TYPE field in `self` and sets its value to `form_type`. This is intended only to be used on empty forms created for blind submission.

`self` : | a WockyDataForm
`form_type` : | the URI to use as the FORM_TYPE field; may not be `NULL`
Returns : | `TRUE` if the form's type was set; `FALSE` if the form already had a type.

### wocky_data_form_set_boolean ()

    gboolean            wocky_data_form_set_boolean         (WockyDataForm *self,
                                                             const gchar *field_name,
                                                             gboolean field_value,
                                                             gboolean create_if_missing);

`self` : | a data form
`field_name` : | the name of a boolean field of `self`
`field_value` : | the value to fill in for `field_name`
`create_if_missing` : | if no field named `field_name` exists, create it
Returns : | `TRUE` if the field was successfully filled in; `FALSE` if the field did not exist or does not accept a boolean

### wocky_data_form_set_string ()

    gboolean            wocky_data_form_set_string          (WockyDataForm *self,
                                                             const gchar *field_name,
                                                             const gchar *field_value,
                                                             gboolean create_if_missing);

`self` : |
`field_name` : |
`field_value` : |
`create_if_missing` : |
Returns : |

### wocky_data_form_set_strv ()

    gboolean            wocky_data_form_set_strv            (WockyDataForm *self,
                                                             const gchar *field_name,
                                                             const gchar * const *field_values,
                                                             gboolean create_if_missing);

`self` : |
`field_name` : |
`field_values` : |
`create_if_missing` : |
Returns : |

### wocky_data_form_submit ()

    void                wocky_data_form_submit              (WockyDataForm *self,
                                                             WockyNode *node);

Adds a node tree which submits `self` based on the current values set on `self`'s fields.

`self` : | a data form
`node` : | a node to which to add a form submission

### wocky_data_form_parse_result ()

    gboolean            wocky_data_form_parse_result        (WockyDataForm *self,
                                                             WockyNode *node,
                                                             GError **error);

`self` : |
`node` : |
`error` : |
Returns : |

### wocky_data_form_get_title ()

    const gchar *       wocky_data_form_get_title           (WockyDataForm *self);

`self` : |
Returns : |

### wocky_data_form_get_instructions ()

    const gchar *       wocky_data_form_get_instructions    (WockyDataForm *self);

`self` : |
Returns : |

## Property Details

### The `"instructions"` property

      "instructions"             gchar*                : Read / Write / Construct Only

Instructions.

Default value: NULL

### The `"title"` property

      "title"                    gchar*                : Read / Write / Construct Only

Title.

Default value: NULL