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:

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

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

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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Request API <br>

Detailed Description

Macro Definition Documentation

◆ PURPLE_DEFAULT_ACTION_NONE

◆ purple_request_accept_cancel

◆ purple_request_accept_cancel_with_icon

◆ purple_request_ok_cancel

◆ purple_request_yes_no

Typedef Documentation

◆ PurpleRequestActionCb

◆ PurpleRequestChoiceCb

◆ PurpleRequestField

◆ PurpleRequestFieldsCb

◆ PurpleRequestFileCb

◆ PurpleRequestInputCb

◆ PurpleRequestScreenshareCb

Enumeration Type Documentation

◆ PurpleRequestFieldType

◆ PurpleRequestType

Function Documentation

◆ purple_request_action()

◆ purple_request_action_with_icon()

◆ purple_request_action_with_icon_varg()

◆ purple_request_choice()

◆ purple_request_close()

◆ purple_request_close_with_handle()

◆ purple_request_field_account_get_default_value()

◆ purple_request_field_account_get_filter()

◆ purple_request_field_account_get_show_all()

◆ purple_request_field_account_get_value()

◆ purple_request_field_account_new()

◆ purple_request_field_account_set_default_value()

◆ purple_request_field_account_set_filter()

◆ purple_request_field_account_set_show_all()

◆ purple_request_field_account_set_value()

◆ purple_request_field_bool_get_default_value()

◆ purple_request_field_bool_get_value()

◆ purple_request_field_bool_new()

◆ purple_request_field_bool_set_default_value()

◆ purple_request_field_bool_set_value()

◆ purple_request_field_choice_add()

◆ purple_request_field_choice_get_default_value()

◆ purple_request_field_choice_get_labels()

◆ purple_request_field_choice_get_value()

◆ purple_request_field_choice_new()

◆ purple_request_field_choice_set_default_value()

◆ purple_request_field_choice_set_value()

◆ purple_request_field_destroy()

◆ purple_request_field_get_group()

◆ purple_request_field_get_id()

◆ purple_request_field_get_label()

◆ purple_request_field_get_type()

◆ purple_request_field_get_type_hint()

◆ purple_request_field_get_ui_data()

◆ purple_request_field_group_add_field()

◆ purple_request_field_group_destroy()

◆ purple_request_field_group_get_fields()

◆ purple_request_field_group_get_title()

◆ purple_request_field_group_new()

◆ purple_request_field_image_get_buffer()

◆ purple_request_field_image_get_scale_x()

◆ purple_request_field_image_get_scale_y()

◆ purple_request_field_image_get_size()

◆ purple_request_field_image_new()

◆ purple_request_field_image_set_scale()

◆ purple_request_field_int_get_default_value()

◆ purple_request_field_int_get_value()

◆ purple_request_field_int_new()

◆ purple_request_field_int_set_default_value()

◆ purple_request_field_int_set_value()

◆ purple_request_field_is_required()

◆ purple_request_field_is_visible()

◆ purple_request_field_label_new()

◆ purple_request_field_list_add()

◆ purple_request_field_list_add_icon()