request.h File Reference

Request API. More...

#include <stdlib.h>
#include <glib-object.h>
#include <glib.h>
#include "account.h"
Include dependency graph for request.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  PurpleRequestFields
 Multiple fields request data. More...
struct  PurpleRequestFieldGroup
 A group of fields with a title. More...
struct  _PurpleRequestField
 A request field. More...
struct  PurpleRequestUiOps
 Request UI operations. More...

Macros

#define PURPLE_DEFAULT_ACTION_NONE   -1

Typedefs

typedef struct _PurpleRequestField PurpleRequestField
 A request field.
typedef void(* PurpleRequestInputCb )(void *, const char *)
typedef void(* PurpleRequestActionCb )(void *, int)
 The type of callbacks passed to purple_request_action().
typedef void(* PurpleRequestChoiceCb )(void *, int)
typedef void(* PurpleRequestFieldsCb )(void *, PurpleRequestFields *fields)
typedef void(* PurpleRequestFileCb )(void *, const char *filename)

Enumerations

enum  PurpleRequestType {
  PURPLE_REQUEST_INPUT = 0, PURPLE_REQUEST_CHOICE, PURPLE_REQUEST_ACTION, PURPLE_REQUEST_FIELDS,
  PURPLE_REQUEST_FILE, PURPLE_REQUEST_FOLDER
}
 Request types. More...
enum  PurpleRequestFieldType {
  PURPLE_REQUEST_FIELD_NONE, PURPLE_REQUEST_FIELD_STRING, PURPLE_REQUEST_FIELD_INTEGER, PURPLE_REQUEST_FIELD_BOOLEAN,
  PURPLE_REQUEST_FIELD_CHOICE, PURPLE_REQUEST_FIELD_LIST, PURPLE_REQUEST_FIELD_LABEL, PURPLE_REQUEST_FIELD_IMAGE,
  PURPLE_REQUEST_FIELD_ACCOUNT
}
 A type of field.

Functions

Field List API
PurpleRequestFieldspurple_request_fields_new (void)
 Creates a list of fields to pass to purple_request_fields().
void purple_request_fields_destroy (PurpleRequestFields *fields)
 Destroys a list of fields.
void purple_request_fields_add_group (PurpleRequestFields *fields, PurpleRequestFieldGroup *group)
 Adds a group of fields to the list.
GList * purple_request_fields_get_groups (const PurpleRequestFields *fields)
 Returns a list of all groups in a field list.
gboolean purple_request_fields_exists (const PurpleRequestFields *fields, const char *id)
 Returns whether or not the field with the specified ID exists.
GList * purple_request_fields_get_required (const PurpleRequestFields *fields)
 Returns a list of all required fields.
gboolean purple_request_fields_is_field_required (const PurpleRequestFields *fields, const char *id)
 Returns whether or not a field with the specified ID is required.
gboolean purple_request_fields_all_required_filled (const PurpleRequestFields *fields)
 Returns whether or not all required fields have values.
PurpleRequestFieldpurple_request_fields_get_field (const PurpleRequestFields *fields, const char *id)
 Return the field with the specified ID.
const char * purple_request_fields_get_string (const PurpleRequestFields *fields, const char *id)
 Returns the string value of a field with the specified ID.
int purple_request_fields_get_integer (const PurpleRequestFields *fields, const char *id)
 Returns the integer value of a field with the specified ID.
gboolean purple_request_fields_get_bool (const PurpleRequestFields *fields, const char *id)
 Returns the boolean value of a field with the specified ID.
int purple_request_fields_get_choice (const PurpleRequestFields *fields, const char *id)
 Returns the choice index of a field with the specified ID.
PurpleAccountpurple_request_fields_get_account (const PurpleRequestFields *fields, const char *id)
 Returns the account of a field with the specified ID.
Fields Group API
PurpleRequestFieldGrouppurple_request_field_group_new (const char *title)
 Creates a fields group with an optional title.
void purple_request_field_group_destroy (PurpleRequestFieldGroup *group)
 Destroys a fields group.
void purple_request_field_group_add_field (PurpleRequestFieldGroup *group, PurpleRequestField *field)
 Adds a field to the group.
const char * purple_request_field_group_get_title (const PurpleRequestFieldGroup *group)
 Returns the title of a fields group.
GList * purple_request_field_group_get_fields (const PurpleRequestFieldGroup *group)
 Returns a list of all fields in a group.
Field API
PurpleRequestFieldpurple_request_field_new (const char *id, const char *text, PurpleRequestFieldType type)
 Creates a field of the specified type.
void purple_request_field_destroy (PurpleRequestField *field)
 Destroys a field.
void purple_request_field_set_label (PurpleRequestField *field, const char *label)
 Sets the label text of a field.
void purple_request_field_set_visible (PurpleRequestField *field, gboolean visible)
 Sets whether or not a field is visible.
void purple_request_field_set_type_hint (PurpleRequestField *field, const char *type_hint)
 Sets the type hint for the field.
void purple_request_field_set_required (PurpleRequestField *field, gboolean required)
 Sets whether or not a field is required.
PurpleRequestFieldType purple_request_field_get_type (const PurpleRequestField *field)
 Returns the type of a field.
PurpleRequestFieldGrouppurple_request_field_get_group (const PurpleRequestField *field)
 Returns the group for the field.
const char * purple_request_field_get_id (const PurpleRequestField *field)
 Returns the ID of a field.
const char * purple_request_field_get_label (const PurpleRequestField *field)
 Returns the label text of a field.
gboolean purple_request_field_is_visible (const PurpleRequestField *field)
 Returns whether or not a field is visible.
const char * purple_request_field_get_type_hint (const PurpleRequestField *field)
 Returns the field's type hint.
gboolean purple_request_field_is_required (const PurpleRequestField *field)
 Returns whether or not a field is required.
gpointer purple_request_field_get_ui_data (const PurpleRequestField *field)
 Returns the ui_data for a field.
void purple_request_field_set_ui_data (PurpleRequestField *field, gpointer ui_data)
 Sets the ui_data for a field.
String Field API
PurpleRequestFieldpurple_request_field_string_new (const char *id, const char *text, const char *default_value, gboolean multiline)
 Creates a string request field.
void purple_request_field_string_set_default_value (PurpleRequestField *field, const char *default_value)
 Sets the default value in a string field.
void purple_request_field_string_set_value (PurpleRequestField *field, const char *value)
 Sets the value in a string field.
void purple_request_field_string_set_masked (PurpleRequestField *field, gboolean masked)
 Sets whether or not a string field is masked (commonly used for password fields).
void purple_request_field_string_set_editable (PurpleRequestField *field, gboolean editable)
 Sets whether or not a string field is editable.
const char * purple_request_field_string_get_default_value (const PurpleRequestField *field)
 Returns the default value in a string field.
const char * purple_request_field_string_get_value (const PurpleRequestField *field)
 Returns the user-entered value in a string field.
gboolean purple_request_field_string_is_multiline (const PurpleRequestField *field)
 Returns whether or not a string field is multi-line.
gboolean purple_request_field_string_is_masked (const PurpleRequestField *field)
 Returns whether or not a string field is masked.
gboolean purple_request_field_string_is_editable (const PurpleRequestField *field)
 Returns whether or not a string field is editable.
Integer Field API
PurpleRequestFieldpurple_request_field_int_new (const char *id, const char *text, int default_value)
 Creates an integer field.
void purple_request_field_int_set_default_value (PurpleRequestField *field, int default_value)
 Sets the default value in an integer field.
void purple_request_field_int_set_value (PurpleRequestField *field, int value)
 Sets the value in an integer field.
int purple_request_field_int_get_default_value (const PurpleRequestField *field)
 Returns the default value in an integer field.
int purple_request_field_int_get_value (const PurpleRequestField *field)
 Returns the user-entered value in an integer field.
Boolean Field API
PurpleRequestFieldpurple_request_field_bool_new (const char *id, const char *text, gboolean default_value)
 Creates a boolean field.
void purple_request_field_bool_set_default_value (PurpleRequestField *field, gboolean default_value)
 Sets the default value in an boolean field.
void purple_request_field_bool_set_value (PurpleRequestField *field, gboolean value)
 Sets the value in an boolean field.
gboolean purple_request_field_bool_get_default_value (const PurpleRequestField *field)
 Returns the default value in an boolean field.
gboolean purple_request_field_bool_get_value (const PurpleRequestField *field)
 Returns the user-entered value in an boolean field.
Choice Field API
PurpleRequestFieldpurple_request_field_choice_new (const char *id, const char *text, int default_value)
 Creates a multiple choice field.
void purple_request_field_choice_add (PurpleRequestField *field, const char *label)
 Adds a choice to a multiple choice field.
void purple_request_field_choice_set_default_value (PurpleRequestField *field, int default_value)
 Sets the default value in an choice field.
void purple_request_field_choice_set_value (PurpleRequestField *field, int value)
 Sets the value in an choice field.
int purple_request_field_choice_get_default_value (const PurpleRequestField *field)
 Returns the default value in an choice field.
int purple_request_field_choice_get_value (const PurpleRequestField *field)
 Returns the user-entered value in an choice field.
GList * purple_request_field_choice_get_labels (const PurpleRequestField *field)
 Returns a list of labels in a choice field.
List Field API
PurpleRequestFieldpurple_request_field_list_new (const char *id, const char *text)
 Creates a multiple list item field.
void purple_request_field_list_set_multi_select (PurpleRequestField *field, gboolean multi_select)
 Sets whether or not a list field allows multiple selection.
gboolean purple_request_field_list_get_multi_select (const PurpleRequestField *field)
 Returns whether or not a list field allows multiple selection.
void * purple_request_field_list_get_data (const PurpleRequestField *field, const char *text)
 Returns the data for a particular item.
void purple_request_field_list_add (PurpleRequestField *field, const char *item, void *data)
 Adds an item to a list field.
void purple_request_field_list_add_icon (PurpleRequestField *field, const char *item, const char *icon_path, void *data)
 Adds an item to a list field.
void purple_request_field_list_add_selected (PurpleRequestField *field, const char *item)
 Adds a selected item to the list field.
void purple_request_field_list_clear_selected (PurpleRequestField *field)
 Clears the list of selected items in a list field.
void purple_request_field_list_set_selected (PurpleRequestField *field, GList *items)
 Sets a list of selected items in a list field.
gboolean purple_request_field_list_is_selected (const PurpleRequestField *field, const char *item)
 Returns whether or not a particular item is selected in a list field.
GList * purple_request_field_list_get_selected (const PurpleRequestField *field)
 Returns a list of selected items in a list field.
GList * purple_request_field_list_get_items (const PurpleRequestField *field)
 Returns a list of items in a list field.
GList * purple_request_field_list_get_icons (const PurpleRequestField *field)
 Returns a list of icons in a list field.
Label Field API
PurpleRequestFieldpurple_request_field_label_new (const char *id, const char *text)
 Creates a label field.
Image Field API
PurpleRequestFieldpurple_request_field_image_new (const char *id, const char *text, const char *buf, gsize size)
 Creates an image field.
void purple_request_field_image_set_scale (PurpleRequestField *field, unsigned int x, unsigned int y)
 Sets the scale factors of an image field.
const char * purple_request_field_image_get_buffer (PurpleRequestField *field)
 Returns pointer to the image.
gsize purple_request_field_image_get_size (PurpleRequestField *field)
 Returns size (in bytes) of the image.
unsigned int purple_request_field_image_get_scale_x (PurpleRequestField *field)
 Returns X scale coefficient of the image.
unsigned int purple_request_field_image_get_scale_y (PurpleRequestField *field)
 Returns Y scale coefficient of the image.
Account Field API
PurpleRequestFieldpurple_request_field_account_new (const char *id, const char *text, PurpleAccount *account)
 Creates an account field.
void purple_request_field_account_set_default_value (PurpleRequestField *field, PurpleAccount *default_value)
 Sets the default account on an account field.
void purple_request_field_account_set_value (PurpleRequestField *field, PurpleAccount *value)
 Sets the account in an account field.
void purple_request_field_account_set_show_all (PurpleRequestField *field, gboolean show_all)
 Sets whether or not to show all accounts in an account field.
void purple_request_field_account_set_filter (PurpleRequestField *field, PurpleFilterAccountFunc filter_func)
 Sets the account filter function in an account field.
PurpleAccountpurple_request_field_account_get_default_value (const PurpleRequestField *field)
 Returns the default account in an account field.
PurpleAccountpurple_request_field_account_get_value (const PurpleRequestField *field)
 Returns the user-entered account in an account field.
gboolean purple_request_field_account_get_show_all (const PurpleRequestField *field)
 Returns whether or not to show all accounts in an account field.
PurpleFilterAccountFunc purple_request_field_account_get_filter (const PurpleRequestField *field)
 Returns the account filter function in an account field.
UI Registration Functions
void purple_request_set_ui_ops (PurpleRequestUiOps *ops)
 Sets the UI operations structure to be used when displaying a request.
PurpleRequestUiOpspurple_request_get_ui_ops (void)
 Returns the UI operations structure to be used when displaying a request.

Request API

#define purple_request_yes_no(handle, title, primary, secondary, default_action, account, who, conv, user_data, yes_cb, no_cb)
 A wrapper for purple_request_action() that uses Yes and No buttons.
#define purple_request_ok_cancel(handle, title, primary, secondary, default_action, account, who, conv, user_data, ok_cb, cancel_cb)
 A wrapper for purple_request_action() that uses OK and Cancel buttons.
#define purple_request_accept_cancel(handle, title, primary, secondary, default_action, account, who, conv, user_data, accept_cb, cancel_cb)
 A wrapper for purple_request_action() that uses Accept and Cancel buttons.
#define purple_request_accept_cancel_with_icon(handle, title, primary, secondary, default_action, account, who, conv, icon_data, icon_size, user_data, accept_cb, cancel_cb)
 A wrapper for purple_request_action_with_icon() that uses Accept and Cancel buttons.
void * purple_request_input (void *handle, const char *title, const char *primary, const char *secondary, const char *default_value, gboolean multiline, gboolean masked, gchar *hint, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Prompts the user for text input.
void * purple_request_choice (void *handle, const char *title, const char *primary, const char *secondary, int default_value, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data,...) G_GNUC_NULL_TERMINATED
 Prompts the user for multiple-choice input.
void * purple_request_choice_varg (void *handle, const char *title, const char *primary, const char *secondary, int default_value, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data, va_list choices)
 va_list version of purple_request_choice(); see its documentation.
void * purple_request_action (void *handle, const char *title, const char *primary, const char *secondary, int default_action, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data, size_t action_count,...)
 Prompts the user for an action.
void * purple_request_action_varg (void *handle, const char *title, const char *primary, const char *secondary, int default_action, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data, size_t action_count, va_list actions)
 va_list version of purple_request_action(); see its documentation.
void * purple_request_action_with_icon (void *handle, const char *title, const char *primary, const char *secondary, int default_action, PurpleAccount *account, const char *who, PurpleConversation *conv, gconstpointer icon_data, gsize icon_size, void *user_data, size_t action_count,...)
 Version of purple_request_action() supplying an image for the UI to optionally display as an icon in the dialog; see its documentation.
void * purple_request_action_with_icon_varg (void *handle, const char *title, const char *primary, const char *secondary, int default_action, PurpleAccount *account, const char *who, PurpleConversation *conv, gconstpointer icon_data, gsize icon_size, void *user_data, size_t action_count, va_list actions)
 va_list version of purple_request_action_with_icon(); see its documentation.
void * purple_request_fields (void *handle, const char *title, const char *primary, const char *secondary, PurpleRequestFields *fields, const char *ok_text, GCallback ok_cb, const char *cancel_text, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Displays groups of fields for the user to fill in.
void purple_request_close (PurpleRequestType type, void *uihandle)
 Closes a request.
void purple_request_close_with_handle (void *handle)
 Closes all requests registered with the specified handle.
void * purple_request_file (void *handle, const char *title, const char *filename, gboolean savedialog, GCallback ok_cb, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Displays a file selector request dialog.
void * purple_request_folder (void *handle, const char *title, const char *dirname, GCallback ok_cb, GCallback cancel_cb, PurpleAccount *account, const char *who, PurpleConversation *conv, void *user_data)
 Displays a folder select dialog.

Detailed Description

Request API.

Definition in file request.h.

Macro Definition Documentation

#define purple_request_accept_cancel (   handle,
  title,
  primary,
  secondary,
  default_action,
  account,
  who,
  conv,
  user_data,
  accept_cb,
  cancel_cb 
)
Value:
purple_request_action((handle), (title), (primary), (secondary), \
(default_action), account, who, conv, (user_data), 2, \
_("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))

A wrapper for purple_request_action() that uses Accept and Cancel buttons.

Definition at line 1503 of file request.h.

#define purple_request_accept_cancel_with_icon (   handle,
  title,
  primary,
  secondary,
  default_action,
  account,
  who,
  conv,
  icon_data,
  icon_size,
  user_data,
  accept_cb,
  cancel_cb 
)
Value:
purple_request_action_with_icon((handle), (title), (primary), (secondary), \
(default_action), account, who, conv, icon_data, icon_size, \
(user_data), 2, \
_("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))

A wrapper for purple_request_action_with_icon() that uses Accept and Cancel buttons.

Definition at line 1514 of file request.h.

#define purple_request_ok_cancel (   handle,
  title,
  primary,
  secondary,
  default_action,
  account,
  who,
  conv,
  user_data,
  ok_cb,
  cancel_cb 
)
Value:
purple_request_action((handle), (title), (primary), (secondary), \
(default_action), account, who, conv, (user_data), 2, \
_("_OK"), (ok_cb), _("_Cancel"), (cancel_cb))

A wrapper for purple_request_action() that uses OK and Cancel buttons.

Definition at line 1493 of file request.h.

#define purple_request_yes_no (   handle,
  title,
  primary,
  secondary,
  default_action,
  account,
  who,
  conv,
  user_data,
  yes_cb,
  no_cb 
)
Value:
purple_request_action((handle), (title), (primary), (secondary), \
(default_action), account, who, conv, (user_data), 2, \
_("_Yes"), (yes_cb), _("_No"), (no_cb))

A wrapper for purple_request_action() that uses Yes and No buttons.

Definition at line 1483 of file request.h.

Typedef Documentation

typedef void(* PurpleRequestActionCb)(void *, int)

The type of callbacks passed to purple_request_action().

The first argument is the user_data parameter; the second is the index in the list of actions of the one chosen.

Definition at line 260 of file request.h.

A request field.

Definition at line 34 of file request.h.

Enumeration Type Documentation

Request types.

Enumerator:
PURPLE_REQUEST_INPUT 

Text input request.

PURPLE_REQUEST_CHOICE 

Multiple-choice request.

PURPLE_REQUEST_ACTION 

Action request.

PURPLE_REQUEST_FIELDS 

Multiple fields request.

PURPLE_REQUEST_FILE 

File open or save request.

PURPLE_REQUEST_FOLDER 

Folder selection request.

Definition at line 43 of file request.h.

Function Documentation

void* purple_request_action ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
int  default_action,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
void *  user_data,
size_t  action_count,
  ... 
)

Prompts the user for an action.

This is often represented as a dialog with a button for each action.

Parameters
handleThe plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
titleThe title of the message, or NULL if it should have no title.
primaryThe main point of the message, or NULL if you're feeling enigmatic.
secondarySecondary information, or NULL if there is none.
default_actionThe default action, zero-indexed; if the third action supplied should be the default, supply 2. The should be the action that users are most likely to select.
accountThe PurpleAccount associated with this request, or NULL if none is.
whoThe username of the buddy associated with this request, or NULL if none is.
convThe PurpleConversation associated with this request, or NULL if none is.
user_dataThe data to pass to the callback.
action_countThe number of actions.
...A list of actions. These are pairs of arguments. The first of each pair is the char * label that appears on the button. It should have an underscore before the letter you want to use as the accelerator key for the button. The second of each pair is the PurpleRequestActionCb function to use when the button is clicked.
Returns
A UI-specific handle.
void* purple_request_action_with_icon ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
int  default_action,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
gconstpointer  icon_data,
gsize  icon_size,
void *  user_data,
size_t  action_count,
  ... 
)

Version of purple_request_action() supplying an image for the UI to optionally display as an icon in the dialog; see its documentation.

Since
2.7.0
void* purple_request_action_with_icon_varg ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
int  default_action,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
gconstpointer  icon_data,
gsize  icon_size,
void *  user_data,
size_t  action_count,
va_list  actions 
)

va_list version of purple_request_action_with_icon(); see its documentation.

Since
2.7.0
void* purple_request_choice ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
int  default_value,
const char *  ok_text,
GCallback  ok_cb,
const char *  cancel_text,
GCallback  cancel_cb,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
void *  user_data,
  ... 
)

Prompts the user for multiple-choice input.

Parameters
handleThe plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
titleThe title of the message, or NULL if it should have no title.
primaryThe main point of the message, or NULL if you're feeling enigmatic.
secondarySecondary information, or NULL if there is none.
default_valueThe default choice; this should be one of the values listed in the varargs.
ok_textThe text for the OK button, which may not be NULL.
ok_cbThe callback for the OK button, which may not be NULL.
cancel_textThe text for the Cancel button, which may not be NULL.
cancel_cbThe callback for the Cancel button, or NULL to do nothing.
accountThe PurpleAccount associated with this request, or NULL if none is.
whoThe username of the buddy associated with this request, or NULL if none is.
convThe PurpleConversation associated with this request, or NULL if none is.
user_dataThe data to pass to the callback.
...The choices, which should be pairs of char * descriptions and int values, terminated with a NULL parameter.
Returns
A UI-specific handle.
void purple_request_close ( PurpleRequestType  type,
void *  uihandle 
)

Closes a request.

Parameters
typeThe request type.
uihandleThe request UI handle.
void purple_request_close_with_handle ( void *  handle)

Closes all requests registered with the specified handle.

Parameters
handleThe handle, as supplied as the handle parameter to one of the purple_request_* functions.
See Also
purple_request_input().
PurpleAccount* purple_request_field_account_get_default_value ( const PurpleRequestField field)

Returns the default account in an account field.

Parameters
fieldThe field.
Returns
The default account.
PurpleFilterAccountFunc purple_request_field_account_get_filter ( const PurpleRequestField field)

Returns the account filter function in an account field.

This function will determine which accounts get displayed and which don't.

Parameters
fieldThe account field.
Returns
The account filter function.
gboolean purple_request_field_account_get_show_all ( const PurpleRequestField field)

Returns whether or not to show all accounts in an account field.

If TRUE, all accounts, online or offline, will be shown. If FALSE, only online accounts will be shown.

Parameters
fieldThe account field.
Returns
Whether or not to show all accounts.
PurpleAccount* purple_request_field_account_get_value ( const PurpleRequestField field)

Returns the user-entered account in an account field.

Parameters
fieldThe field.
Returns
The user-entered account.
PurpleRequestField* purple_request_field_account_new ( const char *  id,
const char *  text,
PurpleAccount account 
)

Creates an account field.

By default, this field will not show offline accounts.

Parameters
idThe field ID.
textThe text label of the field.
accountThe optional default account.
Returns
The new field.
void purple_request_field_account_set_default_value ( PurpleRequestField field,
PurpleAccount default_value 
)

Sets the default account on an account field.

Parameters
fieldThe account field.
default_valueThe default account.
void purple_request_field_account_set_filter ( PurpleRequestField field,
PurpleFilterAccountFunc  filter_func 
)

Sets the account filter function in an account field.

This function will determine which accounts get displayed and which don't.

Parameters
fieldThe account field.
filter_funcThe account filter function.
void purple_request_field_account_set_show_all ( PurpleRequestField field,
gboolean  show_all 
)

Sets whether or not to show all accounts in an account field.

If TRUE, all accounts, online or offline, will be shown. If FALSE, only online accounts will be shown.

Parameters
fieldThe account field.
show_allWhether or not to show all accounts.
void purple_request_field_account_set_value ( PurpleRequestField field,
PurpleAccount value 
)

Sets the account in an account field.

Parameters
fieldThe account field.
valueThe account.
gboolean purple_request_field_bool_get_default_value ( const PurpleRequestField field)

Returns the default value in an boolean field.

Parameters
fieldThe field.
Returns
The default value.
gboolean purple_request_field_bool_get_value ( const PurpleRequestField field)

Returns the user-entered value in an boolean field.

Parameters
fieldThe field.
Returns
The value.
PurpleRequestField* purple_request_field_bool_new ( const char *  id,
const char *  text,
gboolean  default_value 
)

Creates a boolean field.

This is often represented as a checkbox.

Parameters
idThe field ID.
textThe text label of the field.
default_valueThe default value.
Returns
The new field.
void purple_request_field_bool_set_default_value ( PurpleRequestField field,
gboolean  default_value 
)

Sets the default value in an boolean field.

Parameters
fieldThe field.
default_valueThe default value.
void purple_request_field_bool_set_value ( PurpleRequestField field,
gboolean  value 
)

Sets the value in an boolean field.

Parameters
fieldThe field.
valueThe value.
void purple_request_field_choice_add ( PurpleRequestField field,
const char *  label 
)

Adds a choice to a multiple choice field.

Parameters
fieldThe choice field.
labelThe choice label.
int purple_request_field_choice_get_default_value ( const PurpleRequestField field)

Returns the default value in an choice field.

Parameters
fieldThe field.
Returns
The default value.
GList* purple_request_field_choice_get_labels ( const PurpleRequestField field)

Returns a list of labels in a choice field.

Parameters
fieldThe field.
Note
The return value of this function must not be modified or freed.
Returns
The list of labels.
int purple_request_field_choice_get_value ( const PurpleRequestField field)

Returns the user-entered value in an choice field.

Parameters
fieldThe field.
Returns
The value.
PurpleRequestField* purple_request_field_choice_new ( const char *  id,
const char *  text,
int  default_value 
)

Creates a multiple choice field.

This is often represented as a group of radio buttons.

Parameters
idThe field ID.
textThe optional label of the field.
default_valueThe default choice.
Returns
The new field.
void purple_request_field_choice_set_default_value ( PurpleRequestField field,
int  default_value 
)

Sets the default value in an choice field.

Parameters
fieldThe field.
default_valueThe default value.
void purple_request_field_choice_set_value ( PurpleRequestField field,
int  value 
)

Sets the value in an choice field.

Parameters
fieldThe field.
valueThe value.
void purple_request_field_destroy ( PurpleRequestField field)

Destroys a field.

Parameters
fieldThe field to destroy.
PurpleRequestFieldGroup* purple_request_field_get_group ( const PurpleRequestField field)

Returns the group for the field.

Parameters
fieldThe field.
Returns
The UI data.
Since
2.6.0
const char* purple_request_field_get_id ( const PurpleRequestField field)

Returns the ID of a field.

Parameters
fieldThe field.
Returns
The ID
const char* purple_request_field_get_label ( const PurpleRequestField field)

Returns the label text of a field.

Parameters
fieldThe field.
Returns
The label text.
PurpleRequestFieldType purple_request_field_get_type ( const PurpleRequestField field)

Returns the type of a field.

Parameters
fieldThe field.
Returns
The field's type.
const char* purple_request_field_get_type_hint ( const PurpleRequestField field)

Returns the field's type hint.

Parameters
fieldThe field.
Returns
The field's type hint.
gpointer purple_request_field_get_ui_data ( const PurpleRequestField field)

Returns the ui_data for a field.

Parameters
fieldThe field.
Returns
The UI data.
Since
2.6.0
void purple_request_field_group_add_field ( PurpleRequestFieldGroup group,
PurpleRequestField field 
)

Adds a field to the group.

Parameters
groupThe group to add the field to.
fieldThe field to add to the group.
void purple_request_field_group_destroy ( PurpleRequestFieldGroup group)

Destroys a fields group.

Parameters
groupThe group to destroy.
GList* purple_request_field_group_get_fields ( const PurpleRequestFieldGroup group)

Returns a list of all fields in a group.

Parameters
groupThe group.
Note
The return value of this function must not be modified or freed.
Returns
The list of fields in the group.
const char* purple_request_field_group_get_title ( const PurpleRequestFieldGroup group)

Returns the title of a fields group.

Parameters
groupThe group.
Returns
The title, if set.
PurpleRequestFieldGroup* purple_request_field_group_new ( const char *  title)

Creates a fields group with an optional title.

Parameters
titleThe optional title to give the group.
Returns
A new fields group
const char* purple_request_field_image_get_buffer ( PurpleRequestField field)

Returns pointer to the image.

Parameters
fieldThe image field.
Returns
Pointer to the image.
unsigned int purple_request_field_image_get_scale_x ( PurpleRequestField field)

Returns X scale coefficient of the image.

Parameters
fieldThe image field.
Returns
X scale coefficient of the image.
unsigned int purple_request_field_image_get_scale_y ( PurpleRequestField field)

Returns Y scale coefficient of the image.

Parameters
fieldThe image field.
Returns
Y scale coefficient of the image.
gsize purple_request_field_image_get_size ( PurpleRequestField field)

Returns size (in bytes) of the image.

Parameters
fieldThe image field.
Returns
Size of the image.
PurpleRequestField* purple_request_field_image_new ( const char *  id,
const char *  text,
const char *  buf,
gsize  size 
)

Creates an image field.

Parameters
idThe field ID.
textThe label of the field.
bufThe image data.
sizeThe size of the data in buffer.
Returns
The new field.
void purple_request_field_image_set_scale ( PurpleRequestField field,
unsigned int  x,
unsigned int  y 
)

Sets the scale factors of an image field.

Parameters
fieldThe image field.
xThe x scale factor.
yThe y scale factor.
int purple_request_field_int_get_default_value ( const PurpleRequestField field)

Returns the default value in an integer field.

Parameters
fieldThe field.
Returns
The default value.
int purple_request_field_int_get_value ( const PurpleRequestField field)

Returns the user-entered value in an integer field.

Parameters
fieldThe field.
Returns
The value.
PurpleRequestField* purple_request_field_int_new ( const char *  id,
const char *  text,
int  default_value 
)

Creates an integer field.

Parameters
idThe field ID.
textThe text label of the field.
default_valueThe default value.
Returns
The new field.
void purple_request_field_int_set_default_value ( PurpleRequestField field,
int  default_value 
)

Sets the default value in an integer field.

Parameters
fieldThe field.
default_valueThe default value.
void purple_request_field_int_set_value ( PurpleRequestField field,
int  value 
)

Sets the value in an integer field.

Parameters
fieldThe field.
valueThe value.
gboolean purple_request_field_is_required ( const PurpleRequestField field)

Returns whether or not a field is required.

Parameters
fieldThe field.
Returns
TRUE if the field is required, or FALSE.
gboolean purple_request_field_is_visible ( const PurpleRequestField field)

Returns whether or not a field is visible.

Parameters
fieldThe field.
Returns
TRUE if the field is visible. FALSE otherwise.
PurpleRequestField* purple_request_field_label_new ( const char *  id,
const char *  text 
)

Creates a label field.

Parameters
idThe field ID.
textThe label of the field.
Returns
The new field.
void purple_request_field_list_add ( PurpleRequestField field,
const char *  item,
void *  data 
)

Adds an item to a list field.

Parameters
fieldThe list field.
itemThe list item.
dataThe associated data.
Deprecated:
Use purple_request_field_list_add_icon() instead.
void purple_request_field_list_add_icon ( PurpleRequestField field,
const char *  item,
const char *  icon_path,
void *  data 
)

Adds an item to a list field.

Parameters
fieldThe list field.
itemThe list item.
icon_pathThe path to icon file, or NULL for no icon.
dataThe associated data.
void purple_request_field_list_add_selected ( PurpleRequestField field,
const char *  item 
)

Adds a selected item to the list field.

Parameters
fieldThe field.
itemThe item to add.
void purple_request_field_list_clear_selected ( PurpleRequestField field)

Clears the list of selected items in a list field.

Parameters
fieldThe field.
void* purple_request_field_list_get_data ( const PurpleRequestField field,
const char *  text 
)

Returns the data for a particular item.

Parameters
fieldThe list field.
textThe item text.
Returns
The data associated with the item.
GList* purple_request_field_list_get_icons ( const PurpleRequestField field)

Returns a list of icons in a list field.

The icons will correspond with the items, in order.

Parameters
fieldThe field.
Note
The return value of this function must not be modified or freed.
Returns
The list of icons or NULL (i.e. the empty GList) if no items have icons.
GList* purple_request_field_list_get_items ( const PurpleRequestField field)

Returns a list of items in a list field.

Parameters
fieldThe field.
Note
The return value of this function must not be modified or freed.
Returns
The list of items.
gboolean purple_request_field_list_get_multi_select ( const PurpleRequestField field)

Returns whether or not a list field allows multiple selection.

Parameters
fieldThe list field.
Returns
TRUE if multiple selection is enabled, or FALSE otherwise.
GList* purple_request_field_list_get_selected ( const PurpleRequestField field)

Returns a list of selected items in a list field.

To retrieve the data for each item, use purple_request_field_list_get_data().

Parameters
fieldThe field.
Note
The return value of this function must not be modified or freed.
Returns
The list of selected items.
gboolean purple_request_field_list_is_selected ( const PurpleRequestField field,
const char *  item 
)

Returns whether or not a particular item is selected in a list field.

Parameters
fieldThe field.
itemThe item.
Returns
TRUE if the item is selected. FALSE otherwise.
PurpleRequestField* purple_request_field_list_new ( const char *  id,
const char *  text 
)

Creates a multiple list item field.

Parameters
idThe field ID.
textThe optional label of the field.
Returns
The new field.
void purple_request_field_list_set_multi_select ( PurpleRequestField field,
gboolean  multi_select 
)

Sets whether or not a list field allows multiple selection.

Parameters
fieldThe list field.
multi_selectTRUE if multiple selection is enabled, or FALSE otherwise.
void purple_request_field_list_set_selected ( PurpleRequestField field,
GList *  items 
)

Sets a list of selected items in a list field.

Parameters
fieldThe field.
itemsThe list of selected items, which is not modified or freed.
PurpleRequestField* purple_request_field_new ( const char *  id,
const char *  text,
PurpleRequestFieldType  type 
)

Creates a field of the specified type.

Parameters
idThe field ID.
textThe text label of the field.
typeThe type of field.
Returns
The new field.
void purple_request_field_set_label ( PurpleRequestField field,
const char *  label 
)

Sets the label text of a field.

Parameters
fieldThe field.
labelThe text label.
void purple_request_field_set_required ( PurpleRequestField field,
gboolean  required 
)

Sets whether or not a field is required.

Parameters
fieldThe field.
requiredTRUE if required, or FALSE.
void purple_request_field_set_type_hint ( PurpleRequestField field,
const char *  type_hint 
)

Sets the type hint for the field.

This is optionally used by the UIs to provide such features as auto-completion for type hints like "account" and "screenname".

Parameters
fieldThe field.
type_hintThe type hint.
void purple_request_field_set_ui_data ( PurpleRequestField field,
gpointer  ui_data 
)

Sets the ui_data for a field.

Parameters
fieldThe field.
ui_dataThe UI data.
Returns
The UI data.
Since
2.6.0
void purple_request_field_set_visible ( PurpleRequestField field,
gboolean  visible 
)

Sets whether or not a field is visible.

Parameters
fieldThe field.
visibleTRUE if visible, or FALSE if not.
const char* purple_request_field_string_get_default_value ( const PurpleRequestField field)

Returns the default value in a string field.

Parameters
fieldThe field.
Returns
The default value.
const char* purple_request_field_string_get_value ( const PurpleRequestField field)

Returns the user-entered value in a string field.

Parameters
fieldThe field.
Returns
The value.
gboolean purple_request_field_string_is_editable ( const PurpleRequestField field)

Returns whether or not a string field is editable.

Parameters
fieldThe field.
Returns
TRUE if the field is editable, or FALSE otherwise.
gboolean purple_request_field_string_is_masked ( const PurpleRequestField field)

Returns whether or not a string field is masked.

Parameters
fieldThe field.
Returns
TRUE if the field is masked, or FALSE otherwise.
gboolean purple_request_field_string_is_multiline ( const PurpleRequestField field)

Returns whether or not a string field is multi-line.

Parameters
fieldThe field.
Returns
TRUE if the field is mulit-line, or FALSE otherwise.
PurpleRequestField* purple_request_field_string_new ( const char *  id,
const char *  text,
const char *  default_value,
gboolean  multiline 
)

Creates a string request field.

Parameters
idThe field ID.
textThe text label of the field.
default_valueThe optional default value.
multilineWhether or not this should be a multiline string.
Returns
The new field.
void purple_request_field_string_set_default_value ( PurpleRequestField field,
const char *  default_value 
)

Sets the default value in a string field.

Parameters
fieldThe field.
default_valueThe default value.
void purple_request_field_string_set_editable ( PurpleRequestField field,
gboolean  editable 
)

Sets whether or not a string field is editable.

Parameters
fieldThe field.
editableThe editable value.
void purple_request_field_string_set_masked ( PurpleRequestField field,
gboolean  masked 
)

Sets whether or not a string field is masked (commonly used for password fields).

Parameters
fieldThe field.
maskedThe masked value.
void purple_request_field_string_set_value ( PurpleRequestField field,
const char *  value 
)

Sets the value in a string field.

Parameters
fieldThe field.
valueThe value.
void* purple_request_fields ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
PurpleRequestFields fields,
const char *  ok_text,
GCallback  ok_cb,
const char *  cancel_text,
GCallback  cancel_cb,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
void *  user_data 
)

Displays groups of fields for the user to fill in.

Parameters
handleThe plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
titleThe title of the message, or NULL if it should have no title.
primaryThe main point of the message, or NULL if you're feeling enigmatic.
secondarySecondary information, or NULL if there is none.
fieldsThe list of fields.
ok_textThe text for the OK button, which may not be NULL.
ok_cbThe callback for the OK button, which may not be NULL.
cancel_textThe text for the Cancel button, which may not be NULL.
cancel_cbThe callback for the Cancel button, which may be NULL.
accountThe PurpleAccount associated with this request, or NULL if none is
whoThe username of the buddy associated with this request, or NULL if none is
convThe PurpleConversation associated with this request, or NULL if none is
user_dataThe data to pass to the callback.
Returns
A UI-specific handle.
void purple_request_fields_add_group ( PurpleRequestFields fields,
PurpleRequestFieldGroup group 
)

Adds a group of fields to the list.

Parameters
fieldsThe fields list.
groupThe group to add.
gboolean purple_request_fields_all_required_filled ( const PurpleRequestFields fields)

Returns whether or not all required fields have values.

Parameters
fieldsThe fields list.
Returns
TRUE if all required fields have values, or FALSE.
void purple_request_fields_destroy ( PurpleRequestFields fields)

Destroys a list of fields.

Parameters
fieldsThe list of fields to destroy.
gboolean purple_request_fields_exists ( const PurpleRequestFields fields,
const char *  id 
)

Returns whether or not the field with the specified ID exists.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
TRUE if the field exists, or FALSE.
PurpleAccount* purple_request_fields_get_account ( const PurpleRequestFields fields,
const char *  id 
)

Returns the account of a field with the specified ID.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
The account value, if found, or NULL otherwise.
gboolean purple_request_fields_get_bool ( const PurpleRequestFields fields,
const char *  id 
)

Returns the boolean value of a field with the specified ID.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
The boolean value, if found, or FALSE otherwise.
int purple_request_fields_get_choice ( const PurpleRequestFields fields,
const char *  id 
)

Returns the choice index of a field with the specified ID.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
The choice index, if found, or -1 otherwise.
PurpleRequestField* purple_request_fields_get_field ( const PurpleRequestFields fields,
const char *  id 
)

Return the field with the specified ID.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
The field, if found.
GList* purple_request_fields_get_groups ( const PurpleRequestFields fields)

Returns a list of all groups in a field list.

Parameters
fieldsThe fields list.
Note
The return value of this function must not be modified or freed.
Returns
A list of groups.
int purple_request_fields_get_integer ( const PurpleRequestFields fields,
const char *  id 
)

Returns the integer value of a field with the specified ID.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
The integer value, if found, or 0 otherwise.
GList* purple_request_fields_get_required ( const PurpleRequestFields fields)

Returns a list of all required fields.

Parameters
fieldsThe fields list.
Note
The return value of this function must not be modified or freed.
Returns
The list of required fields.
const char* purple_request_fields_get_string ( const PurpleRequestFields fields,
const char *  id 
)

Returns the string value of a field with the specified ID.

Parameters
fieldsThe fields list.
idThe ID of the field.
Returns
The string value, if found, or NULL otherwise.
gboolean purple_request_fields_is_field_required ( const PurpleRequestFields fields,
const char *  id 
)

Returns whether or not a field with the specified ID is required.

Parameters
fieldsThe fields list.
idThe field ID.
Returns
TRUE if the specified field is required, or FALSE.
PurpleRequestFields* purple_request_fields_new ( void  )

Creates a list of fields to pass to purple_request_fields().

Returns
A PurpleRequestFields structure.
void* purple_request_file ( void *  handle,
const char *  title,
const char *  filename,
gboolean  savedialog,
GCallback  ok_cb,
GCallback  cancel_cb,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
void *  user_data 
)

Displays a file selector request dialog.

Returns the selected filename to the callback. Can be used for either opening a file or saving a file.

Parameters
handleThe plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
titleThe title of the message, or NULL if it should have no title.
filenameThe default filename (may be NULL)
savedialogTrue if this dialog is being used to save a file. False if it is being used to open a file.
ok_cbThe callback for the OK button.
cancel_cbThe callback for the Cancel button, which may be NULL.
accountThe PurpleAccount associated with this request, or NULL if none is
whoThe username of the buddy associated with this request, or NULL if none is
convThe PurpleConversation associated with this request, or NULL if none is
user_dataThe data to pass to the callback.
Returns
A UI-specific handle.
void* purple_request_folder ( void *  handle,
const char *  title,
const char *  dirname,
GCallback  ok_cb,
GCallback  cancel_cb,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
void *  user_data 
)

Displays a folder select dialog.

Returns the selected filename to the callback.

Parameters
handleThe plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
titleThe title of the message, or NULL if it should have no title.
dirnameThe default directory name (may be NULL)
ok_cbThe callback for the OK button.
cancel_cbThe callback for the Cancel button, which may be NULL.
accountThe PurpleAccount associated with this request, or NULL if none is
whoThe username of the buddy associated with this request, or NULL if none is
convThe PurpleConversation associated with this request, or NULL if none is
user_dataThe data to pass to the callback.
Returns
A UI-specific handle.
PurpleRequestUiOps* purple_request_get_ui_ops ( void  )

Returns the UI operations structure to be used when displaying a request.

Returns
The UI operations structure.
void* purple_request_input ( void *  handle,
const char *  title,
const char *  primary,
const char *  secondary,
const char *  default_value,
gboolean  multiline,
gboolean  masked,
gchar *  hint,
const char *  ok_text,
GCallback  ok_cb,
const char *  cancel_text,
GCallback  cancel_cb,
PurpleAccount account,
const char *  who,
PurpleConversation conv,
void *  user_data 
)

Prompts the user for text input.

Parameters
handleThe plugin or connection handle. For some things this is extremely important. The handle is used to programmatically close the request dialog when it is no longer needed. For PRPLs this is often a pointer to the PurpleConnection instance. For plugins this should be a similar, unique memory location. This value is important because it allows a request to be closed with purple_request_close_with_handle() when, for example, you sign offline. If the request is not closed it is very likely to cause a crash whenever the callback handler functions are triggered.
titleThe title of the message, or NULL if it should have no title.
primaryThe main point of the message, or NULL if you're feeling enigmatic.
secondarySecondary information, or NULL if there is none.
default_valueThe default value.
multilineTRUE if the inputted text can span multiple lines.
maskedTRUE if the inputted text should be masked in some way (such as by displaying characters as stars). This might be because the input is some kind of password.
hintOptionally suggest how the input box should appear. Use "html", for example, to allow the user to enter HTML.
ok_textThe text for the OK button, which may not be NULL.
ok_cbThe callback for the OK button, which may not be NULL.
cancel_textThe text for the Cancel button, which may not be NULL.
cancel_cbThe callback for the Cancel button, which may be NULL.
accountThe PurpleAccount associated with this request, or NULL if none is.
whoThe username of the buddy associated with this request, or NULL if none is.
convThe PurpleConversation associated with this request, or NULL if none is.
user_dataThe data to pass to the callback.
Returns
A UI-specific handle.
void purple_request_set_ui_ops ( PurpleRequestUiOps ops)

Sets the UI operations structure to be used when displaying a request.

Parameters
opsThe UI operations structure.
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!