pidgin: request.h File Reference

pidgin 2.14.4

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations
request.h File Reference
libpurple

Request API. More...

`#include <stdlib.h>`
`#include <glib-object.h>`
`#include <glib.h>`
`#include "account.h"`

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)
typedef void(* | PurpleRequestScreenshareCb) (void *, GObject *info)

## Enumerations
enum | PurpleRequestType { PURPLE_REQUEST_INPUT = 0 , PURPLE_REQUEST_CHOICE , PURPLE_REQUEST_ACTION , PURPLE_REQUEST_FIELDS , PURPLE_REQUEST_FILE , PURPLE_REQUEST_FOLDER , PURPLE_REQUEST_SCREENSHARE }
| 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. More...

## Functions
Field List API <br>
PurpleRequestFields * | purple_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.
PurpleRequestField * | purple_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.
PurpleAccount * | purple_request_fields_get_account (const PurpleRequestFields *fields, const char *id)
| Returns the account of a field with the specified ID.
Fields Group API <br>
PurpleRequestFieldGroup * | purple_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 <br>
PurpleRequestField * | purple_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.
PurpleRequestFieldGroup * | purple_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 <br>
PurpleRequestField * | purple_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 <br>
PurpleRequestField * | purple_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 <br>
PurpleRequestField * | purple_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 <br>
PurpleRequestField * | purple_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 <br>
PurpleRequestField * | purple_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 <br>
PurpleRequestField * | purple_request_field_label_new (const char *id, const char *text)
| Creates a label field.
Image Field API <br>
PurpleRequestField * | purple_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 <br>
PurpleRequestField * | purple_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.
PurpleAccount * | purple_request_field_account_get_default_value (const PurpleRequestField *field)
| Returns the default account in an account field.
PurpleAccount * | purple_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 <br>
void | purple_request_set_ui_ops (PurpleRequestUiOps *ops)
| Sets the UI operations structure to be used when displaying a request.
PurpleRequestUiOps * | purple_request_get_ui_ops (void)
| Returns the UI operations structure to be used when displaying a request.

## Request API <br>
#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.
void * | purple_request_screenshare_media (void *handle, const char *title, const char *primary, const char *secondary, PurpleAccount *account, GCallback cb, void *user_data)
| Displays a dialog allowing the user to select a window/monitor etc.

## Detailed Description

Request API.

Definition in file request.h.

## Macro Definition Documentation

## ◆ PURPLE_DEFAULT_ACTION_NONE

#define PURPLE_DEFAULT_ACTION_NONE -1

Definition at line 38 of file request.h.

## ◆ purple_request_accept_cancel

#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))
purple_request_action
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.

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

Definition at line 1508 of file request.h.

## ◆ purple_request_accept_cancel_with_icon

#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))
purple_request_action_with_icon
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 ...

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

Definition at line 1519 of file request.h.

## ◆ purple_request_ok_cancel

#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 1498 of file request.h.

## ◆ purple_request_yes_no

#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 1488 of file request.h.

## Typedef Documentation

## ◆ PurpleRequestActionCb

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 264 of file request.h.

## ◆ PurpleRequestChoiceCb

typedef void(* PurpleRequestChoiceCb) (void *, int)

Definition at line 265 of file request.h.

## ◆ PurpleRequestField

typedef struct _PurpleRequestField PurpleRequestField

A request field.

Definition at line 34 of file request.h.

## ◆ PurpleRequestFieldsCb

typedef void(* PurpleRequestFieldsCb) (void *, PurpleRequestFields *fields)

Definition at line 266 of file request.h.

## ◆ PurpleRequestFileCb

typedef void(* PurpleRequestFileCb) (void *, const char *filename)

Definition at line 267 of file request.h.

## ◆ PurpleRequestInputCb

typedef void(* PurpleRequestInputCb) (void *, const char *)

Definition at line 258 of file request.h.

## ◆ PurpleRequestScreenshareCb

typedef void(* PurpleRequestScreenshareCb) (void *, GObject *info)

Definition at line 268 of file request.h.

## Enumeration Type Documentation

## ◆ PurpleRequestFieldType

enum PurpleRequestFieldType

A type of field.

Definition at line 58 of file request.h.

## ◆ PurpleRequestType

enum PurpleRequestType

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.
PURPLE_REQUEST_SCREENSHARE | Screenshare media request.

Definition at line 43 of file request.h.

## Function Documentation

## ◆ purple_request_action()

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

  handle | The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
  title | The title of the message, or `NULL` if it should have no title.
  primary | The main point of the message, or `NULL` if you're feeling enigmatic.
  secondary | Secondary information, or `NULL` if there is none.
  default_action | The 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.
  account | The PurpleAccount associated with this request, or `NULL` if none is.
  who | The username of the buddy associated with this request, or `NULL` if none is.
  conv | The PurpleConversation associated with this request, or `NULL` if none is.
  user_data | The data to pass to the callback.
  action_count | The 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.

## ◆ purple_request_action_with_icon()

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

## ◆ purple_request_action_with_icon_varg()

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

## ◆ purple_request_choice()

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

  handle | The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
  title | The title of the message, or `NULL` if it should have no title.
  primary | The main point of the message, or `NULL` if you're feeling enigmatic.
  secondary | Secondary information, or `NULL` if there is none.
  default_value | The default choice; this should be one of the values listed in the varargs.
  ok_text | The text for the `OK` button, which may not be `NULL`.
  ok_cb | The callback for the `OK` button, which may not be `NULL`.
  cancel_text | The text for the `Cancel` button, which may not be `NULL`.
  cancel_cb | The callback for the `Cancel` button, or `NULL` to do nothing.
  account | The PurpleAccount associated with this request, or `NULL` if none is.
  who | The username of the buddy associated with this request, or `NULL` if none is.
  conv | The PurpleConversation associated with this request, or `NULL` if none is.
  user_data | The 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.

## ◆ purple_request_close()

void purple_request_close | ( | PurpleRequestType | type,
|  | void * | uihandle
| ) |  |

Closes a request.

Parameters

  type | The request type.
  uihandle | The request UI handle.

## ◆ purple_request_close_with_handle()

void purple_request_close_with_handle | ( | void * | handle | ) |

Closes all requests registered with the specified handle.

Parameters

  handle | The handle, as supplied as the handle parameter to one of the `purple_request_*` functions.

See also
  purple_request_input().

## ◆ purple_request_field_account_get_default_value()

PurpleAccount * purple_request_field_account_get_default_value | ( | const PurpleRequestField * | field | ) |

Returns the default account in an account field.

Parameters

  field | The field.

Returns
  The default account.

## ◆ purple_request_field_account_get_filter()

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

  field | The account field.

Returns
  The account filter function.

## ◆ purple_request_field_account_get_show_all()

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

  field | The account field.

Returns
  Whether or not to show all accounts.

## ◆ purple_request_field_account_get_value()

PurpleAccount * purple_request_field_account_get_value | ( | const PurpleRequestField * | field | ) |

Returns the user-entered account in an account field.

Parameters

  field | The field.

Returns
  The user-entered account.

## ◆ purple_request_field_account_new()

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

  id | The field ID.
  text | The text label of the field.
  account | The optional default account.

Returns
  The new field.

## ◆ purple_request_field_account_set_default_value()

void purple_request_field_account_set_default_value | ( | PurpleRequestField * | field,
|  | PurpleAccount * | default_value
| ) |  |

Sets the default account on an account field.

Parameters

  field | The account field.
  default_value | The default account.

## ◆ purple_request_field_account_set_filter()

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

  field | The account field.
  filter_func | The account filter function.

## ◆ purple_request_field_account_set_show_all()

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

  field | The account field.
  show_all | Whether or not to show all accounts.

## ◆ purple_request_field_account_set_value()

void purple_request_field_account_set_value | ( | PurpleRequestField * | field,
|  | PurpleAccount * | value
| ) |  |

Sets the account in an account field.

Parameters

  field | The account field.
  value | The account.

## ◆ purple_request_field_bool_get_default_value()

gboolean purple_request_field_bool_get_default_value | ( | const PurpleRequestField * | field | ) |

Returns the default value in an boolean field.

Parameters

  field | The field.

Returns
  The default value.

## ◆ purple_request_field_bool_get_value()

gboolean purple_request_field_bool_get_value | ( | const PurpleRequestField * | field | ) |

Returns the user-entered value in an boolean field.

Parameters

  field | The field.

Returns
  The value.

## ◆ purple_request_field_bool_new()

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

  id | The field ID.
  text | The text label of the field.
  default_value | The default value.

Returns
  The new field.

## ◆ purple_request_field_bool_set_default_value()

void purple_request_field_bool_set_default_value | ( | PurpleRequestField * | field,
|  | gboolean | default_value
| ) |  |

Sets the default value in an boolean field.

Parameters

  field | The field.
  default_value | The default value.

## ◆ purple_request_field_bool_set_value()

void purple_request_field_bool_set_value | ( | PurpleRequestField * | field,
|  | gboolean | value
| ) |  |

Sets the value in an boolean field.

Parameters

  field | The field.
  value | The value.

## ◆ purple_request_field_choice_add()

void purple_request_field_choice_add | ( | PurpleRequestField * | field,
|  | const char * | label
| ) |  |

Adds a choice to a multiple choice field.

Parameters

  field | The choice field.
  label | The choice label.

## ◆ purple_request_field_choice_get_default_value()

int purple_request_field_choice_get_default_value | ( | const PurpleRequestField * | field | ) |

Returns the default value in an choice field.

Parameters

  field | The field.

Returns
  The default value.

## ◆ purple_request_field_choice_get_labels()

GList * purple_request_field_choice_get_labels | ( | const PurpleRequestField * | field | ) |

Returns a list of labels in a choice field.

Parameters

  field | The field.

Note
  The return value of this function must not be modified or freed.

Returns
  The list of labels.

## ◆ purple_request_field_choice_get_value()

int purple_request_field_choice_get_value | ( | const PurpleRequestField * | field | ) |

Returns the user-entered value in an choice field.

Parameters

  field | The field.

Returns
  The value.

## ◆ purple_request_field_choice_new()

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

  id | The field ID.
  text | The optional label of the field.
  default_value | The default choice.

Returns
  The new field.

## ◆ purple_request_field_choice_set_default_value()

void purple_request_field_choice_set_default_value | ( | PurpleRequestField * | field,
|  | int | default_value
| ) |  |

Sets the default value in an choice field.

Parameters

  field | The field.
  default_value | The default value.

## ◆ purple_request_field_choice_set_value()

void purple_request_field_choice_set_value | ( | PurpleRequestField * | field,
|  | int | value
| ) |  |

Sets the value in an choice field.

Parameters

  field | The field.
  value | The value.

## ◆ purple_request_field_destroy()

void purple_request_field_destroy | ( | PurpleRequestField * | field | ) |

Destroys a field.

Parameters

  field | The field to destroy.

## ◆ purple_request_field_get_group()

PurpleRequestFieldGroup * purple_request_field_get_group | ( | const PurpleRequestField * | field | ) |

Returns the group for the field.

Parameters

  field | The field.

Returns
  The UI data.

Since
  2.6.0

## ◆ purple_request_field_get_id()

const char * purple_request_field_get_id | ( | const PurpleRequestField * | field | ) |

Returns the ID of a field.

Parameters

  field | The field.

Returns
  The ID

## ◆ purple_request_field_get_label()

const char * purple_request_field_get_label | ( | const PurpleRequestField * | field | ) |

Returns the label text of a field.

Parameters

  field | The field.

Returns
  The label text.

## ◆ purple_request_field_get_type()

PurpleRequestFieldType purple_request_field_get_type | ( | const PurpleRequestField * | field | ) |

Returns the type of a field.

Parameters

  field | The field.

Returns
  The field's type.

## ◆ purple_request_field_get_type_hint()

const char * purple_request_field_get_type_hint | ( | const PurpleRequestField * | field | ) |

Returns the field's type hint.

Parameters

  field | The field.

Returns
  The field's type hint.

## ◆ purple_request_field_get_ui_data()

gpointer purple_request_field_get_ui_data | ( | const PurpleRequestField * | field | ) |

Returns the ui_data for a field.

Parameters

  field | The field.

Returns
  The UI data.

Since
  2.6.0

## ◆ purple_request_field_group_add_field()

void purple_request_field_group_add_field | ( | PurpleRequestFieldGroup * | group,
|  | PurpleRequestField * | field
| ) |  |

Adds a field to the group.

Parameters

  group | The group to add the field to.
  field | The field to add to the group.

## ◆ purple_request_field_group_destroy()

void purple_request_field_group_destroy | ( | PurpleRequestFieldGroup * | group | ) |

Destroys a fields group.

Parameters

  group | The group to destroy.

## ◆ purple_request_field_group_get_fields()

GList * purple_request_field_group_get_fields | ( | const PurpleRequestFieldGroup * | group | ) |

Returns a list of all fields in a group.

Parameters

  group | The group.

Note
  The return value of this function must not be modified or freed.

Returns
  The list of fields in the group.

## ◆ purple_request_field_group_get_title()

const char * purple_request_field_group_get_title | ( | const PurpleRequestFieldGroup * | group | ) |

Returns the title of a fields group.

Parameters

  group | The group.

Returns
  The title, if set.

## ◆ purple_request_field_group_new()

PurpleRequestFieldGroup * purple_request_field_group_new | ( | const char * | title | ) |

Creates a fields group with an optional title.

Parameters

  title | The optional title to give the group.

Returns
  A new fields group

## ◆ purple_request_field_image_get_buffer()

const char * purple_request_field_image_get_buffer | ( | PurpleRequestField * | field | ) |

Returns pointer to the image.

Parameters

  field | The image field.

Returns
  Pointer to the image.

## ◆ purple_request_field_image_get_scale_x()

unsigned int purple_request_field_image_get_scale_x | ( | PurpleRequestField * | field | ) |

Returns X scale coefficient of the image.

Parameters

  field | The image field.

Returns
  X scale coefficient of the image.

## ◆ purple_request_field_image_get_scale_y()

unsigned int purple_request_field_image_get_scale_y | ( | PurpleRequestField * | field | ) |

Returns Y scale coefficient of the image.

Parameters

  field | The image field.

Returns
  Y scale coefficient of the image.

## ◆ purple_request_field_image_get_size()

gsize purple_request_field_image_get_size | ( | PurpleRequestField * | field | ) |

Returns size (in bytes) of the image.

Parameters

  field | The image field.

Returns
  Size of the image.

## ◆ purple_request_field_image_new()

PurpleRequestField * purple_request_field_image_new | ( | const char * | id,
|  | const char * | text,
|  | const char * | buf,
|  | gsize | size
| ) |  |

Creates an image field.

Parameters

  id | The field ID.
  text | The label of the field.
  buf | The image data.
  size | The size of the data in buffer.

Returns
  The new field.

## ◆ purple_request_field_image_set_scale()

void purple_request_field_image_set_scale | ( | PurpleRequestField * | field,
|  | unsigned int | x,
|  | unsigned int | y
| ) |  |

Sets the scale factors of an image field.

Parameters

  field | The image field.
  x | The x scale factor.
  y | The y scale factor.

## ◆ purple_request_field_int_get_default_value()

int purple_request_field_int_get_default_value | ( | const PurpleRequestField * | field | ) |

Returns the default value in an integer field.

Parameters

  field | The field.

Returns
  The default value.

## ◆ purple_request_field_int_get_value()

int purple_request_field_int_get_value | ( | const PurpleRequestField * | field | ) |

Returns the user-entered value in an integer field.

Parameters

  field | The field.

Returns
  The value.

## ◆ purple_request_field_int_new()

PurpleRequestField * purple_request_field_int_new | ( | const char * | id,
|  | const char * | text,
|  | int | default_value
| ) |  |

Creates an integer field.

Parameters

  id | The field ID.
  text | The text label of the field.
  default_value | The default value.

Returns
  The new field.

## ◆ purple_request_field_int_set_default_value()

void purple_request_field_int_set_default_value | ( | PurpleRequestField * | field,
|  | int | default_value
| ) |  |

Sets the default value in an integer field.

Parameters

  field | The field.
  default_value | The default value.

## ◆ purple_request_field_int_set_value()

void purple_request_field_int_set_value | ( | PurpleRequestField * | field,
|  | int | value
| ) |  |

Sets the value in an integer field.

Parameters

  field | The field.
  value | The value.

## ◆ purple_request_field_is_required()

gboolean purple_request_field_is_required | ( | const PurpleRequestField * | field | ) |

Returns whether or not a field is required.

Parameters

  field | The field.

Returns
  TRUE if the field is required, or FALSE.

## ◆ purple_request_field_is_visible()

gboolean purple_request_field_is_visible | ( | const PurpleRequestField * | field | ) |

Returns whether or not a field is visible.

Parameters

  field | The field.

Returns
  TRUE if the field is visible. FALSE otherwise.

## ◆ purple_request_field_label_new()

PurpleRequestField * purple_request_field_label_new | ( | const char * | id,
|  | const char * | text
| ) |  |

Creates a label field.

Parameters

  id | The field ID.
  text | The label of the field.

Returns
  The new field.

## ◆ purple_request_field_list_add()

void purple_request_field_list_add | ( | PurpleRequestField * | field,
|  | const char * | item,
|  | void * | data
| ) |  |

Adds an item to a list field.

Parameters

  field | The list field.
  item | The list item.
  data | The associated data.

Deprecated:
  Use purple_request_field_list_add_icon() instead.

## ◆ purple_request_field_list_add_icon()

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

  field | The list field.
  item | The list item.
  icon_path | The path to icon file, or `NULL` for no icon.
  data | The associated data.

## ◆ purple_request_field_list_add_selected()

void purple_request_field_list_add_selected | ( | PurpleRequestField * | field,
|  | const char * | item
| ) |  |

Adds a selected item to the list field.

Parameters

  field | The field.
  item | The item to add.

## ◆ purple_request_field_list_clear_selected()

void purple_request_field_list_clear_selected | ( | PurpleRequestField * | field | ) |

Clears the list of selected items in a list field.

Parameters

  field | The field.

## ◆ purple_request_field_list_get_data()

void * purple_request_field_list_get_data | ( | const PurpleRequestField * | field,
|  | const char * | text
| ) |  |

Returns the data for a particular item.

Parameters

  field | The list field.
  text | The item text.

Returns
  The data associated with the item.

## ◆ purple_request_field_list_get_icons()

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

  field | The 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.

## ◆ purple_request_field_list_get_items()

GList * purple_request_field_list_get_items | ( | const PurpleRequestField * | field | ) |

Returns a list of items in a list field.

Parameters

  field | The field.

Note
  The return value of this function must not be modified or freed.

Returns
  The list of items.

## ◆ purple_request_field_list_get_multi_select()

gboolean purple_request_field_list_get_multi_select | ( | const PurpleRequestField * | field | ) |

Returns whether or not a list field allows multiple selection.

Parameters

  field | The list field.

Returns
  TRUE if multiple selection is enabled, or FALSE otherwise.

## ◆ purple_request_field_list_get_selected()

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

  field | The field.

Note
  The return value of this function must not be modified or freed.

Returns
  The list of selected items.

## ◆ purple_request_field_list_is_selected()

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

  field | The field.
  item | The item.

Returns
  TRUE if the item is selected. FALSE otherwise.

## ◆ purple_request_field_list_new()

PurpleRequestField * purple_request_field_list_new | ( | const char * | id,
|  | const char * | text
| ) |  |

Creates a multiple list item field.

Parameters

  id | The field ID.
  text | The optional label of the field.

Returns
  The new field.

## ◆ purple_request_field_list_set_multi_select()

void purple_request_field_list_set_multi_select | ( | PurpleRequestField * | field,
|  | gboolean | multi_select
| ) |  |

Sets whether or not a list field allows multiple selection.

Parameters

  field | The list field.
  multi_select | TRUE if multiple selection is enabled, or FALSE otherwise.

## ◆ purple_request_field_list_set_selected()

void purple_request_field_list_set_selected | ( | PurpleRequestField * | field,
|  | GList * | items
| ) |  |

Sets a list of selected items in a list field.

Parameters

  field | The field.
  items | The list of selected items, which is not modified or freed.

## ◆ purple_request_field_new()

PurpleRequestField * purple_request_field_new | ( | const char * | id,
|  | const char * | text,
|  | PurpleRequestFieldType | type
| ) |  |

Creates a field of the specified type.

Parameters

  id | The field ID.
  text | The text label of the field.
  type | The type of field.

Returns
  The new field.

## ◆ purple_request_field_set_label()

void purple_request_field_set_label | ( | PurpleRequestField * | field,
|  | const char * | label
| ) |  |

Sets the label text of a field.

Parameters

  field | The field.
  label | The text label.

## ◆ purple_request_field_set_required()

void purple_request_field_set_required | ( | PurpleRequestField * | field,
|  | gboolean | required
| ) |  |

Sets whether or not a field is required.

Parameters

  field | The field.
  required | TRUE if required, or FALSE.

## ◆ purple_request_field_set_type_hint()

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

  field | The field.
  type_hint | The type hint.

## ◆ purple_request_field_set_ui_data()

void purple_request_field_set_ui_data | ( | PurpleRequestField * | field,
|  | gpointer | ui_data
| ) |  |

Sets the ui_data for a field.

Parameters

  field | The field.
  ui_data | The UI data.

Returns
  The UI data.

Since
  2.6.0

## ◆ purple_request_field_set_visible()

void purple_request_field_set_visible | ( | PurpleRequestField * | field,
|  | gboolean | visible
| ) |  |

Sets whether or not a field is visible.

Parameters

  field | The field.
  visible | TRUE if visible, or FALSE if not.

## ◆ purple_request_field_string_get_default_value()

const char * purple_request_field_string_get_default_value | ( | const PurpleRequestField * | field | ) |

Returns the default value in a string field.

Parameters

  field | The field.

Returns
  The default value.

## ◆ purple_request_field_string_get_value()

const char * purple_request_field_string_get_value | ( | const PurpleRequestField * | field | ) |

Returns the user-entered value in a string field.

Parameters

  field | The field.

Returns
  The value.

## ◆ purple_request_field_string_is_editable()

gboolean purple_request_field_string_is_editable | ( | const PurpleRequestField * | field | ) |

Returns whether or not a string field is editable.

Parameters

  field | The field.

Returns
  `TRUE` if the field is editable, or `FALSE` otherwise.

## ◆ purple_request_field_string_is_masked()

gboolean purple_request_field_string_is_masked | ( | const PurpleRequestField * | field | ) |

Returns whether or not a string field is masked.

Parameters

  field | The field.

Returns
  `TRUE` if the field is masked, or `FALSE` otherwise.

## ◆ purple_request_field_string_is_multiline()

gboolean purple_request_field_string_is_multiline | ( | const PurpleRequestField * | field | ) |

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

Parameters

  field | The field.

Returns
  `TRUE` if the field is mulit-line, or `FALSE` otherwise.

## ◆ purple_request_field_string_new()

PurpleRequestField * purple_request_field_string_new | ( | const char * | id,
|  | const char * | text,
|  | const char * | default_value,
|  | gboolean | multiline
| ) |  |

Creates a string request field.

Parameters

  id | The field ID.
  text | The text label of the field.
  default_value | The optional default value.
  multiline | Whether or not this should be a multiline string.

Returns
  The new field.

## ◆ purple_request_field_string_set_default_value()

void purple_request_field_string_set_default_value | ( | PurpleRequestField * | field,
|  | const char * | default_value
| ) |  |

Sets the default value in a string field.

Parameters

  field | The field.
  default_value | The default value.

## ◆ purple_request_field_string_set_editable()

void purple_request_field_string_set_editable | ( | PurpleRequestField * | field,
|  | gboolean | editable
| ) |  |

Sets whether or not a string field is editable.

Parameters

  field | The field.
  editable | The editable value.

## ◆ purple_request_field_string_set_masked()

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

  field | The field.
  masked | The masked value.

## ◆ purple_request_field_string_set_value()

void purple_request_field_string_set_value | ( | PurpleRequestField * | field,
|  | const char * | value
| ) |  |

Sets the value in a string field.

Parameters

  field | The field.
  value | The value.

## ◆ purple_request_fields()

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

  handle | The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
  title | The title of the message, or `NULL` if it should have no title.
  primary | The main point of the message, or `NULL` if you're feeling enigmatic.
  secondary | Secondary information, or `NULL` if there is none.
  fields | The list of fields.
  ok_text | The text for the `OK` button, which may not be `NULL`.
  ok_cb | The callback for the `OK` button, which may not be `NULL`.
  cancel_text | The text for the `Cancel` button, which may not be `NULL`.
  cancel_cb | The callback for the `Cancel` button, which may be `NULL`.
  account | The PurpleAccount associated with this request, or `NULL` if none is
  who | The username of the buddy associated with this request, or `NULL` if none is
  conv | The PurpleConversation associated with this request, or `NULL` if none is
  user_data | The data to pass to the callback.

Returns
  A UI-specific handle.

## ◆ purple_request_fields_add_group()

void purple_request_fields_add_group | ( | PurpleRequestFields * | fields,
|  | PurpleRequestFieldGroup * | group
| ) |  |

Adds a group of fields to the list.

Parameters

  fields | The fields list.
  group | The group to add.

## ◆ purple_request_fields_all_required_filled()

gboolean purple_request_fields_all_required_filled | ( | const PurpleRequestFields * | fields | ) |

Returns whether or not all required fields have values.

Parameters

  fields | The fields list.

Returns
  TRUE if all required fields have values, or FALSE.

## ◆ purple_request_fields_destroy()

void purple_request_fields_destroy | ( | PurpleRequestFields * | fields | ) |

Destroys a list of fields.

Parameters

  fields | The list of fields to destroy.

## ◆ purple_request_fields_exists()

gboolean purple_request_fields_exists | ( | const PurpleRequestFields * | fields,
|  | const char * | id
| ) |  |

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

Parameters

  fields | The fields list.
  id | The ID of the field.

Returns
  TRUE if the field exists, or FALSE.

## ◆ purple_request_fields_get_account()

PurpleAccount * purple_request_fields_get_account | ( | const PurpleRequestFields * | fields,
|  | const char * | id
| ) |  |

Returns the account of a field with the specified ID.

Parameters

  fields | The fields list.
  id | The ID of the field.

Returns
  The account value, if found, or NULL otherwise.

## ◆ purple_request_fields_get_bool()

gboolean purple_request_fields_get_bool | ( | const PurpleRequestFields * | fields,
|  | const char * | id
| ) |  |

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

Parameters

  fields | The fields list.
  id | The ID of the field.

Returns
  The boolean value, if found, or `FALSE` otherwise.

## ◆ purple_request_fields_get_choice()

int purple_request_fields_get_choice | ( | const PurpleRequestFields * | fields,
|  | const char * | id
| ) |  |

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

Parameters

  fields | The fields list.
  id | The ID of the field.

Returns
  The choice index, if found, or -1 otherwise.

## ◆ purple_request_fields_get_field()

PurpleRequestField * purple_request_fields_get_field | ( | const PurpleRequestFields * | fields,
|  | const char * | id
| ) |  |

Return the field with the specified ID.

Parameters

  fields | The fields list.
  id | The ID of the field.

Returns
  The field, if found.

## ◆ purple_request_fields_get_groups()

GList * purple_request_fields_get_groups | ( | const PurpleRequestFields * | fields | ) |

Returns a list of all groups in a field list.

Parameters

  fields | The fields list.

Note
  The return value of this function must not be modified or freed.

Returns
  A list of groups.

## ◆ purple_request_fields_get_integer()

int purple_request_fields_get_integer | ( | const PurpleRequestFields * | fields,
|  | const char * | id
| ) |  |

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

Parameters

  fields | The fields list.
  id | The ID of the field.

Returns
  The integer value, if found, or 0 otherwise.

## ◆ purple_request_fields_get_required()

GList * purple_request_fields_get_required | ( | const PurpleRequestFields * | fields | ) |

Returns a list of all required fields.

Parameters

  fields | The fields list.

Note
  The return value of this function must not be modified or freed.

Returns
  The list of required fields.

## ◆ purple_request_fields_get_string()

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

  fields | The fields list.
  id | The ID of the field.

Returns
  The string value, if found, or `NULL` otherwise.

## ◆ purple_request_fields_is_field_required()

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

  fields | The fields list.
  id | The field ID.

Returns
  TRUE if the specified field is required, or FALSE.

## ◆ purple_request_fields_new()

PurpleRequestFields * purple_request_fields_new | ( | void |  | ) |

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

Returns
  A PurpleRequestFields structure.

## ◆ purple_request_file()

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

  handle | The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
  title | The title of the message, or `NULL` if it should have no title.
  filename | The default filename (may be `NULL`)
  savedialog | True if this dialog is being used to save a file. False if it is being used to open a file.
  ok_cb | The callback for the `OK` button.
  cancel_cb | The callback for the `Cancel` button, which may be `NULL`.
  account | The PurpleAccount associated with this request, or `NULL` if none is
  who | The username of the buddy associated with this request, or `NULL` if none is
  conv | The PurpleConversation associated with this request, or `NULL` if none is
  user_data | The data to pass to the callback.

Returns
  A UI-specific handle.

## ◆ purple_request_folder()

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

  handle | The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
  title | The title of the message, or `NULL` if it should have no title.
  dirname | The default directory name (may be `NULL`)
  ok_cb | The callback for the `OK` button.
  cancel_cb | The callback for the `Cancel` button, which may be `NULL`.
  account | The PurpleAccount associated with this request, or `NULL` if none is
  who | The username of the buddy associated with this request, or `NULL` if none is
  conv | The PurpleConversation associated with this request, or `NULL` if none is
  user_data | The data to pass to the callback.

Returns
  A UI-specific handle.

## ◆ purple_request_get_ui_ops()

PurpleRequestUiOps * purple_request_get_ui_ops | ( | void |  | ) |

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

Returns
  The UI operations structure.

## ◆ purple_request_input()

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

  handle | The 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.
  title | The title of the message, or `NULL` if it should have no title.
  primary | The main point of the message, or `NULL` if you're feeling enigmatic.
  secondary | Secondary information, or `NULL` if there is none.
  default_value | The default value.
  multiline | `TRUE` if the inputted text can span multiple lines.
  masked | `TRUE` 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.
  hint | Optionally suggest how the input box should appear. Use "html", for example, to allow the user to enter HTML.
  ok_text | The text for the `OK` button, which may not be `NULL`.
  ok_cb | The callback for the `OK` button, which may not be `NULL`.
  cancel_text | The text for the `Cancel` button, which may not be `NULL`.
  cancel_cb | The callback for the `Cancel` button, which may be `NULL`.
  account | The PurpleAccount associated with this request, or `NULL` if none is.
  who | The username of the buddy associated with this request, or `NULL` if none is.
  conv | The PurpleConversation associated with this request, or `NULL` if none is.
  user_data | The data to pass to the callback.

Returns
  A UI-specific handle.

## ◆ purple_request_screenshare_media()

void * purple_request_screenshare_media | ( | void * | handle,
|  | const char * | title,
|  | const char * | primary,
|  | const char * | secondary,
|  | PurpleAccount * | account,
|  | GCallback | cb,
|  | void * | user_data
| ) |  |

Displays a dialog allowing the user to select a window/monitor etc.

for screen sharing. Returns a PurpleMediaElementInfo to the callback or `NULL` if the request is cancelled.

Parameters

  handle | The plugin or connection handle. For some things this is extremely important. See the comments on purple_request_input().
  title | The title of the message, or `NULL` if it should have no title.
  primary | The main point of the message, or `NULL` if you're feeling enigmatic.
  secondary | Secondary information, or `NULL` if there is none.
  cb | The callback for the `OK` button.
  user_data | The data to pass to the callback.

Returns
  A UI-specific handle.

## ◆ purple_request_set_ui_ops()

void purple_request_set_ui_ops | ( | PurpleRequestUiOps * | ops | ) |

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

Parameters

  ops | The UI operations structure.