|  |  |  | Wocky Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
#include <wocky/wocky-data-form.h> #define WOCKY_DATA_FORM_ERROR struct WockyDataFormClass; enum WockyDataFormError; struct WockyDataFormField; struct WockyDataFormFieldOption; enum WockyDataFormFieldType; void wocky_data_form_add_to_node (WockyDataForm *self,WockyNode *node); GQuark wocky_data_form_error_quark (void); gint wocky_data_form_field_cmp (const WockyDataFormField *left,const WockyDataFormField *right); const gchar * wocky_data_form_get_instructions (WockyDataForm *self); const gchar * wocky_data_form_get_title (WockyDataForm *self); WockyDataForm * wocky_data_form_new_from_form (WockyNode *node,GError **error); WockyDataForm * wocky_data_form_new_from_node (WockyNode *x,GError **error); gboolean wocky_data_form_parse_result (WockyDataForm *self,WockyNode *node,GError **error); 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); gboolean wocky_data_form_set_type (WockyDataForm *self,const gchar *form_type); void wocky_data_form_submit (WockyDataForm *self,WockyNode *node);
typedef enum {
  WOCKY_DATA_FORM_ERROR_NOT_FORM,
  WOCKY_DATA_FORM_ERROR_WRONG_TYPE,
} WockyDataFormError;
WockyDataForm specific errors.
struct WockyDataFormField {
  WockyDataFormFieldType type;
  gchar *var;
  gchar *label;
  gchar *desc;
  gboolean required;
  GValue *default_value;
  /* a GStrv of actual values so can be {"1", NULL} or {"false", NULL}
   * for BOOLEAN or {"hi", "there", NULL} TEXT_MULTI, for example. */
  gchar **raw_value_contents;
  GValue *value;
  /* for LIST_MULTI and LIST_SINGLE only.
   * List of (WockyDataFormFieldOption *)*/
  GSList *options;
};
Details about a single data form field in a WockyDataForm.
| WockyDataFormFieldType  | the type of the field | 
| gchar * | the field name | 
| gchar * | the label of the field | 
| gchar * | the description of the field | 
| gboolean  | TRUEif the field is required, otherwiseFALSE | 
| GValue * | the default of the field | 
| gchar ** | |
| GValue * | the field value | 
| GSList * | a GSList of WockyDataFormFieldOptions if typeifWOCKY_DATA_FORM_FIELD_TYPE_LIST_MULTIorWOCKY_DATA_FORM_FIELD_TYPE_LIST_SINGLE | 
struct WockyDataFormFieldOption {
  gchar *label;
  gchar *value;
};
A single data form field option.
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.
| Unspecified field type | |
| Boolean field type | |
| Fixed description field type | |
| Hidden field type | |
| A list of multiple JIDs | |
| A single JID | |
| Many options to choose one or more from | |
| Many options to choose one from | |
| Multiple lines of text | |
| A single line of text that should be obscured (by, say, asterisks) | |
| A single line of text | 
void wocky_data_form_add_to_node (WockyDataForm *self,WockyNode *node);
Adds a node tree with default values of self based on the defaults
set on each field when first created.
This function is for adding a data form to an existing node, like
the query node of a disco response. wocky_data_form_submit(), in
contrast, is for adding a node tree which submits the data form
based on the current values set on its fields.
| 
 | the WockyDataForm object | 
| 
 | a node to which to add the form | 
gint wocky_data_form_field_cmp (const WockyDataFormField *left,const WockyDataFormField *right);
const gchar *       wocky_data_form_get_instructions    (WockyDataForm *self);
WockyDataForm * wocky_data_form_new_from_form (WockyNode *node,GError **error);
WockyDataForm * wocky_data_form_new_from_node (WockyNode *x,GError **error);
gboolean wocky_data_form_parse_result (WockyDataForm *self,WockyNode *node,GError **error);
gboolean wocky_data_form_set_boolean (WockyDataForm *self,const gchar *field_name,gboolean field_value,gboolean create_if_missing);
| 
 | a data form | 
| 
 | the name of a boolean field of self | 
| 
 | the value to fill in for field_name | 
| 
 | if no field named field_nameexists, create it | 
| Returns : | TRUEif the field was successfully filled in;FALSEif the field
did not exist or does not accept a boolean | 
gboolean wocky_data_form_set_string (WockyDataForm *self,const gchar *field_name,const gchar *field_value,gboolean create_if_missing);
| 
 | a data form | 
| 
 | the name of a string field of self | 
| 
 | the value to fill in for field_name | 
| 
 | if no field named field_nameexists, create it | 
| Returns : | TRUEif the field was successfully filled in;FALSEif the field
did not exist or does not accept a string | 
gboolean wocky_data_form_set_strv (WockyDataForm *self,const gchar *field_name,const gchar * const *field_values,gboolean create_if_missing);
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.
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.
| 
 | a data form | 
| 
 | a node to which to add a form submission |