WockyDataForm

WockyDataForm — An object to represent an XMPP data form

Synopsis

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

Object Hierarchy

  GEnum
   +----WockyDataFormError
  GEnum
   +----WockyDataFormFieldType

Description

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

Details

WOCKY_DATA_FORM_ERROR

#define WOCKY_DATA_FORM_ERROR (wocky_data_form_error_quark ())


struct WockyDataFormClass

struct WockyDataFormClass {
};

The class of a WockyDataForm.


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

struct WockyDataFormField

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

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

struct WockyDataFormFieldOption

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

A single data form field option.

gchar *label;

the option label

gchar *value;

the option value

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

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.

self :

the WockyDataForm object

node :

a node to which to add the form

wocky_data_form_error_quark ()

GQuark              wocky_data_form_error_quark         (void);


wocky_data_form_field_cmp ()

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


wocky_data_form_get_instructions ()

const gchar *       wocky_data_form_get_instructions    (WockyDataForm *self);


wocky_data_form_get_title ()

const gchar *       wocky_data_form_get_title           (WockyDataForm *self);


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_parse_result ()

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


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 :

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