/**

 * @file request.h Request API

 * @ingroup core

 */

/* purple

 *

 * Purple is the legal property of its developers, whose names are too numerous

 * to list here.  Please refer to the COPYRIGHT file distributed with this

 * source distribution.

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA

 */

#ifndef _PURPLE_REQUEST_H_

#define _PURPLE_REQUEST_H_

#include <stdlib.h>

#include <glib-object.h>

#include <glib.h>

/** @copydoc _PurpleRequestField */

typedef struct _PurpleRequestField PurpleRequestField;

#include "account.h"

#define PURPLE_DEFAULT_ACTION_NONE	-1

/**

 * Request types.

 */

typedef enum

{

	PURPLE_REQUEST_INPUT = 0,  /**< 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.  */

} PurpleRequestType;

/**

 * A type of field.

 */

typedef enum

{

	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

} PurpleRequestFieldType;

/**

 * Multiple fields request data.

 */

typedef struct

{

	GList *groups;

	GHashTable *fields;

	GList *required_fields;

	void *ui_data;

} PurpleRequestFields;

/**

 * A group of fields with a title.

 */

typedef struct

{

	PurpleRequestFields *fields_list;

	char *title;

	GList *fields;

} PurpleRequestFieldGroup;

#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_REQUEST_C_)

/**

 * A request field.

 */

struct _PurpleRequestField

{

	PurpleRequestFieldType type;

	PurpleRequestFieldGroup *group;

	char *id;

	char *label;

	char *type_hint;

	gboolean visible;

	gboolean required;

	union

	{

		struct

		{

			gboolean multiline;

			gboolean masked;

			gboolean editable;

			char *default_value;

			char *value;

		} string;

		struct

		{

			int default_value;

			int value;

		} integer;

		struct

		{

			gboolean default_value;

			gboolean value;

		} boolean;

		struct

		{

			int default_value;

			int value;

			GList *labels;

		} choice;

		struct

		{

			GList *items;

			GHashTable *item_data;

			GList *selected;

			GHashTable *selected_table;

			gboolean multiple_selection;

		} list;

		struct

		{

			PurpleAccount *default_account;

			PurpleAccount *account;

			gboolean show_all;

			PurpleFilterAccountFunc filter_func;

		} account;

		struct

		{

			unsigned int scale_x;

			unsigned int scale_y;

			const char *buffer;

			gsize size;

		} image;

	} u;

	void *ui_data;

};

#endif

/**

 * Request UI operations.

 */

typedef struct

{

	/** @see purple_request_input(). */

	void *(*request_input)(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);

	/** @see purple_request_choice_varg(). */

	void *(*request_choice)(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);

	/** @see purple_request_action_varg(). */

	void *(*request_action)(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);

	/** @see purple_request_fields(). */

	void *(*request_fields)(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);

	/** @see purple_request_file(). */

	void *(*request_file)(const char *title, const char *filename,

	                      gboolean savedialog, GCallback ok_cb,

	                      GCallback cancel_cb, PurpleAccount *account,

	                      const char *who, PurpleConversation *conv,

	                      void *user_data);

	void (*close_request)(PurpleRequestType type, void *ui_handle);

	/** @see purple_request_folder(). */

	void *(*request_folder)(const char *title, const char *dirname,

	                        GCallback ok_cb, GCallback cancel_cb,

	                        PurpleAccount *account, const char *who,

	                        PurpleConversation *conv, void *user_data);

	void (*_purple_reserved1)(void);

	void (*_purple_reserved2)(void);

	void (*_purple_reserved3)(void);

	void (*_purple_reserved4)(void);

} PurpleRequestUiOps;

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

/** The type of callbacks passed to purple_request_action().  The first

 *  argument is the @a user_data parameter; the second is the index in the list

 *  of actions of the one chosen.

 */

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

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

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

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

#ifdef __cplusplus

extern "C" {

#endif

/**************************************************************************/

/** @name Field List API                                                  */

/**************************************************************************/

/*@{*/

/**

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

 *

 * @return A PurpleRequestFields structure.

 */

PurpleRequestFields *purple_request_fields_new(void);

/**

 * Destroys a list of fields.

 *

 * @param fields The list of fields to destroy.

 */

void purple_request_fields_destroy(PurpleRequestFields *fields);

/**

 * Adds a group of fields to the list.

 *

 * @param fields The fields list.

 * @param group  The group to add.

 */

void purple_request_fields_add_group(PurpleRequestFields *fields,

								   PurpleRequestFieldGroup *group);

/**

 * Returns a list of all groups in a field list.

 *

 * @param fields The fields list.

 *

 * @constreturn A list of groups.

 */

GList *purple_request_fields_get_groups(const PurpleRequestFields *fields);

/**

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

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return TRUE if the field exists, or FALSE.

 */

gboolean purple_request_fields_exists(const PurpleRequestFields *fields,

									const char *id);

/**

 * Returns a list of all required fields.

 *

 * @param fields The fields list.

 *

 * @constreturn The list of required fields.

 */

GList *purple_request_fields_get_required(const PurpleRequestFields *fields);

/**

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

 *

 * @param fields The fields list.

 * @param id     The field ID.

 *

 * @return TRUE if the specified field is required, or FALSE.

 */

gboolean purple_request_fields_is_field_required(const PurpleRequestFields *fields,

											   const char *id);

/**

 * Returns whether or not all required fields have values.

 *

 * @param fields The fields list.

 *

 * @return TRUE if all required fields have values, or FALSE.

 */

gboolean purple_request_fields_all_required_filled(

	const PurpleRequestFields *fields);

/**

 * Return the field with the specified ID.

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return The field, if found.

 */

PurpleRequestField *purple_request_fields_get_field(

		const PurpleRequestFields *fields, const char *id);

/**

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

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return The string value, if found, or @c NULL otherwise.

 */

const char *purple_request_fields_get_string(const PurpleRequestFields *fields,

										   const char *id);

/**

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

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return The integer value, if found, or 0 otherwise.

 */

int purple_request_fields_get_integer(const PurpleRequestFields *fields,

									const char *id);

/**

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

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return The boolean value, if found, or @c FALSE otherwise.

 */

gboolean purple_request_fields_get_bool(const PurpleRequestFields *fields,

									  const char *id);

/**

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

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return The choice index, if found, or -1 otherwise.

 */

int purple_request_fields_get_choice(const PurpleRequestFields *fields,

								   const char *id);

/**

 * Returns the account of a field with the specified ID.

 *

 * @param fields The fields list.

 * @param id     The ID of the field.

 *

 * @return The account value, if found, or NULL otherwise.

 */

PurpleAccount *purple_request_fields_get_account(const PurpleRequestFields *fields,

											 const char *id);

/*@}*/

/**************************************************************************/

/** @name Fields Group API                                                */

/**************************************************************************/

/*@{*/

/**

 * Creates a fields group with an optional title.

 *

 * @param title The optional title to give the group.

 *

 * @return A new fields group

 */

PurpleRequestFieldGroup *purple_request_field_group_new(const char *title);

/**

 * Destroys a fields group.

 *

 * @param group The group to destroy.

 */

void purple_request_field_group_destroy(PurpleRequestFieldGroup *group);

/**

 * Adds a field to the group.

 *

 * @param group The group to add the field to.

 * @param field The field to add to the group.

 */

void purple_request_field_group_add_field(PurpleRequestFieldGroup *group,

										PurpleRequestField *field);

/**

 * Returns the title of a fields group.

 *

 * @param group The group.

 *

 * @return The title, if set.

 */

const char *purple_request_field_group_get_title(

		const PurpleRequestFieldGroup *group);

/**

 * Returns a list of all fields in a group.

 *

 * @param group The group.

 *

 * @constreturn The list of fields in the group.

 */

GList *purple_request_field_group_get_fields(

		const PurpleRequestFieldGroup *group);

/*@}*/

/**************************************************************************/

/** @name Field API                                                       */

/**************************************************************************/

/*@{*/

/**

 * Creates a field of the specified type.

 *

 * @param id   The field ID.

 * @param text The text label of the field.

 * @param type The type of field.

 *

 * @return The new field.

 */

PurpleRequestField *purple_request_field_new(const char *id, const char *text,

										 PurpleRequestFieldType type);

/**

 * Destroys a field.

 *

 * @param field The field to destroy.

 */

void purple_request_field_destroy(PurpleRequestField *field);

/**

 * Sets the label text of a field.

 *

 * @param field The field.

 * @param label The text label.

 */

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

/**

 * Sets whether or not a field is visible.

 *

 * @param field   The field.

 * @param visible TRUE if visible, or FALSE if not.

 */

void purple_request_field_set_visible(PurpleRequestField *field, gboolean visible);

/**

 * 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".

 *

 * @param field     The field.

 * @param type_hint The type hint.

 */

void purple_request_field_set_type_hint(PurpleRequestField *field,

									  const char *type_hint);

/**

 * Sets whether or not a field is required.

 *

 * @param field    The field.

 * @param required TRUE if required, or FALSE.

 */

void purple_request_field_set_required(PurpleRequestField *field,

									 gboolean required);

/**

 * Returns the type of a field.

 *

 * @param field The field.

 *

 * @return The field's type.

 */

PurpleRequestFieldType purple_request_field_get_type(const PurpleRequestField *field);

/**

 * Returns the group for the field.

 *

 * @param field The field.

 *

 * @return The UI data.

 *

 * @since 2.6.0

 */

PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field);

/**

 * Returns the ID of a field.

 *

 * @param field The field.

 *

 * @return The ID

 */

const char *purple_request_field_get_id(const PurpleRequestField *field);

/**

 * Returns the label text of a field.

 *

 * @param field The field.

 *

 * @return The label text.

 */

const char *purple_request_field_get_label(const PurpleRequestField *field);

/**

 * Returns whether or not a field is visible.

 *

 * @param field The field.

 *

 * @return TRUE if the field is visible. FALSE otherwise.

 */

gboolean purple_request_field_is_visible(const PurpleRequestField *field);

/**

 * Returns the field's type hint.

 *

 * @param field The field.

 *

 * @return The field's type hint.

 */

const char *purple_request_field_get_type_hint(const PurpleRequestField *field);

/**

 * Returns whether or not a field is required.

 *

 * @param field The field.

 *

 * @return TRUE if the field is required, or FALSE.

 */

gboolean purple_request_field_is_required(const PurpleRequestField *field);

/**

 * Returns the ui_data for a field.

 *

 * @param field The field.

 *

 * @return The UI data.

 *

 * @since 2.6.0

 */

gpointer purple_request_field_get_ui_data(const PurpleRequestField *field);

/**

 * Sets the ui_data for a field.

 *

 * @param field The field.

 * @param ui_data The UI data.

 *

 * @return The UI data.

 *

 * @since 2.6.0

 */

void purple_request_field_set_ui_data(PurpleRequestField *field,

                                      gpointer ui_data);

/*@}*/

/**************************************************************************/

/** @name String Field API                                                */

/**************************************************************************/

/*@{*/

/**

 * Creates a string request field.

 *

 * @param id            The field ID.

 * @param text          The text label of the field.

 * @param default_value The optional default value.

 * @param multiline     Whether or not this should be a multiline string.

 *

 * @return The new field.

 */

PurpleRequestField *purple_request_field_string_new(const char *id,

												const char *text,

												const char *default_value,

												gboolean multiline);

/**

 * Sets the default value in a string field.

 *

 * @param field         The field.

 * @param default_value The default value.

 */

void purple_request_field_string_set_default_value(PurpleRequestField *field,

												 const char *default_value);

/**

 * Sets the value in a string field.

 *

 * @param field The field.

 * @param value The value.

 */

void purple_request_field_string_set_value(PurpleRequestField *field,

										 const char *value);

/**

 * Sets whether or not a string field is masked

 * (commonly used for password fields).

 *

 * @param field  The field.

 * @param masked The masked value.

 */

void purple_request_field_string_set_masked(PurpleRequestField *field,

										  gboolean masked);

/**

 * Sets whether or not a string field is editable.

 *

 * @param field    The field.

 * @param editable The editable value.

 */

void purple_request_field_string_set_editable(PurpleRequestField *field,

											gboolean editable);

/**

 * Returns the default value in a string field.

 *

 * @param field The field.

 *

 * @return The default value.

 */

const char *purple_request_field_string_get_default_value(

		const PurpleRequestField *field);

/**

 * Returns the user-entered value in a string field.

 *

 * @param field The field.

 *

 * @return The value.

 */

const char *purple_request_field_string_get_value(const PurpleRequestField *field);

/**

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

 *

 * @param field The field.

 *

 * @return @c TRUE if the field is mulit-line, or @c FALSE otherwise.

 */

gboolean purple_request_field_string_is_multiline(const PurpleRequestField *field);

/**

 * Returns whether or not a string field is masked.

 *

 * @param field The field.

 *

 * @return @c TRUE if the field is masked, or @c FALSE otherwise.

 */

gboolean purple_request_field_string_is_masked(const PurpleRequestField *field);

/**

 * Returns whether or not a string field is editable.

 *

 * @param field The field.

 *

 * @return @c TRUE if the field is editable, or @c FALSE otherwise.

 */

gboolean purple_request_field_string_is_editable(const PurpleRequestField *field);

/*@}*/

/**************************************************************************/

/** @name Integer Field API                                               */

/**************************************************************************/

/*@{*/

/**

 * Creates an integer field.

 *

 * @param id            The field ID.

 * @param text          The text label of the field.

 * @param default_value The default value.

 *

 * @return The new field.

 */

PurpleRequestField *purple_request_field_int_new(const char *id,

											 const char *text,

											 int default_value);

/**

 * Sets the default value in an integer field.

 *

 * @param field         The field.

 * @param default_value The default value.

 */

void purple_request_field_int_set_default_value(PurpleRequestField *field,

											  int default_value);

/**

 * Sets the value in an integer field.

 *

 * @param field The field.

 * @param value The value.

 */

void purple_request_field_int_set_value(PurpleRequestField *field, int value);

/**

 * Returns the default value in an integer field.

 *

 * @param field The field.

 *

 * @return The default value.

 */

int purple_request_field_int_get_default_value(const PurpleRequestField *field);

/**

 * Returns the user-entered value in an integer field.

 *

 * @param field The field.

 *

 * @return The value.

 */

int purple_request_field_int_get_value(const PurpleRequestField *field);

/*@}*/

/**************************************************************************/

/** @name Boolean Field API                                               */

/**************************************************************************/

/*@{*/

/**

 * Creates a boolean field.

 *

 * This is often represented as a checkbox.

 *

 * @param id            The field ID.

 * @param text          The text label of the field.

 * @param default_value The default value.

 *

 * @return The new field.

 */

PurpleRequestField *purple_request_field_bool_new(const char *id,

											  const char *text,