WockyDataForm

WockyDataForm — An object to represent an XMPP data form

Functions

Properties

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

Types and Values

Object Hierarchy

    GEnum
    ├── WockyDataFormError
    ╰── WockyDataFormFieldType
    GObject
    ╰── WockyDataForm

Includes

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

Description

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

Functions

wocky_data_form_error_quark ()

GQuark
wocky_data_form_error_quark (void);

wocky_data_form_new_from_form ()

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

wocky_data_form_new_from_node ()

WockyDataForm *
wocky_data_form_new_from_node (WockyNode *x,
                               GError **error);

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.

Parameters

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

Parameters

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

Parameters

self

a data form

 

field_name

the name of a string 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 string


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

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.

Parameters

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

wocky_data_form_get_title ()

const gchar *
wocky_data_form_get_title (WockyDataForm *self);

wocky_data_form_get_instructions ()

const gchar *
wocky_data_form_get_instructions (WockyDataForm *self);

wocky_data_form_field_cmp ()

gint
wocky_data_form_field_cmp (const WockyDataFormField *left,
                           const WockyDataFormField *right);

wocky_data_form_add_to_node ()

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.

Parameters

self

the WockyDataForm object

 

node

a node to which to add the form

 

Types and Values

enum WockyDataFormFieldType

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

Members

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

 

struct WockyDataFormFieldOption

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

A single data form field option.

Members

gchar *label;

the option label

 

gchar *value;

the option value

 

struct WockyDataFormField

struct WockyDataFormField {
  WockyDataFormFieldType type;
  gchar *var;
  gchar *label;
  gchar *desc;
  gboolean required;
  GValue *default_value;
  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.

Members

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

 

gchar **raw_value_contents;

a NULL-terminated array holding the literal value(s) as specified in the original XML. For example, this might be something like

{ "1", NULL }

or

{ "false", NULL }

for a WOCKY_DATA_FORM_FIELD_TYPE_BOOLEAN field, or

{ "hi", "there", NULL }

for a WOCKY_DATA_FORM_FIELD_TYPE_TEXT_MULTI 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

 

enum WockyDataFormError

WockyDataForm specific errors.

Members

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

#define WOCKY_DATA_FORM_ERROR (wocky_data_form_error_quark ())

struct WockyDataFormClass

struct WockyDataFormClass {
};

The class of a WockyDataForm.


struct WockyDataForm

struct WockyDataForm {
  /* (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;
};

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

Members

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.

 

Property Details

The “instructions” property

  “instructions”             gchar *

Instructions.

Flags: Read / Write / Construct Only

Default value: NULL


The “title” property

  “title”                    gchar *

Title.

Flags: Read / Write / Construct Only

Default value: NULL