comparison libpurple/request.h @ 21876:2ca7a3d28186

merge of '0bab002372d4ff0eac85fc22d99e014cd044b900' and 'f60024a049490db3b4b14922c237f7bc7c140045'

21835:567b77c90a1b

/**
 * Request UI operations.
 */
typedef struct
{
	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);
	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);
	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);
	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);
	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);
	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);

/**
 * Prompts the user for text input.
 *
 * @param 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, say, when
 *                      you sign offline.  If the request is NOT
 *                      closed it is VERY likely to cause a crash
 *                      whenever the callback handler functions are
 *                      triggered.
 * @param title         The title of the message.
 * @param primary       The main point of the message.
 * @param secondary     The secondary information.
 * @param default_value The default value.
 * @param multiline     TRUE if the inputted text can span multiple lines.
 * @param masked        TRUE if the inputted text should be masked in some way.
 * @param hint          Optionally suggest how the input box should appear.
 *                      Use "html," for example, to allow the user to enter
 *                      HTML.
 * @param ok_text       The text for the @c OK button.
 * @param ok_cb         The callback for the @c OK button.
 * @param cancel_text   The text for the @c Cancel button.
 * @param cancel_cb     The callback for the @c Cancel button.
 * @param account		The PurpleAccount associated with this request, or NULL if none is
 * @param who			The username of the buddy assocaited with this request, or NULL if none is
 * @param conv			The PurpleConversation associated with this request, or NULL if none is
 * @param user_data     The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
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 multiple-choice input.
 *
 * @param handle        The plugin or connection handle.  For some
 *                      things this is EXTREMELY important.  See
 *                      the comments on purple_request_input.
 * @param title         The title of the message.
 * @param primary       The main point of the message.
 * @param secondary     The secondary information.
 * @param default_value The default value.
 * @param ok_text       The text for the @c OK button.
 * @param ok_cb         The callback for the @c OK button.
 * @param cancel_text   The text for the @c Cancel button.
 * @param cancel_cb     The callback for the @c Cancel button.
 * @param account		The PurpleAccount associated with this request, or NULL if none is
 * @param who			The username of the buddy assocaited with this request, or NULL if none is
 * @param conv			The PurpleConversation associated with this request, or NULL if none is
 * @param user_data     The data to pass to the callback.
 * @param ...           The choices.  This argument list should be
 *                      terminated with a NULL parameter.
 *
 * @return A UI-specific handle.
 */
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.
 *
 * @param handle        The plugin or connection handle.  For some
 *                      things this is EXTREMELY important.  See
 *                      the comments on purple_request_input.
 * @param title         The title of the message.
 * @param primary       The main point of the message.
 * @param secondary     The secondary information.
 * @param default_value The default value.
 * @param ok_text       The text for the @c OK button.
 * @param ok_cb         The callback for the @c OK button.
 * @param cancel_text   The text for the @c Cancel button.
 * @param cancel_cb     The callback for the @c Cancel button.
 * @param account		The PurpleAccount associated with this request, or NULL if none is
 * @param who			The username of the buddy assocaited with this request, or NULL if none is
 * @param conv			The PurpleConversation associated with this request, or NULL if none is
 * @param user_data     The data to pass to the callback.
 * @param choices       The choices.  This argument list should be
 *                      terminated with a @c NULL parameter.
 *
 * @return A UI-specific handle.
 */
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);

/**
 * Prompts the user for an action.
 *
 * This is often represented as a dialog with a button for each action.
 *
 * @param handle         The plugin or connection handle.  For some
 *                       things this is EXTREMELY important.  See
 *                       the comments on purple_request_input.
 * @param title          The title of the message.
 * @param primary        The main point of the message.
 * @param secondary      The secondary information.
 * @param default_action The default value.
 * @param account		 The PurpleAccount associated with this request, or NULL if none is
 * @param who			 The username of the buddy assocaited with this request, or NULL if none is
 * @param conv			 The PurpleConversation associated with this request, or NULL if none is
 * @param user_data      The data to pass to the callback.
 * @param action_count   The number of actions.
 * @param ...            A list of actions.  These are pairs of
 *                       arguments.  The first of each pair is the
 *                       string 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 callback
 *                       function to use when the button is clicked.
 *
 * @return A UI-specific handle.
 */
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.
 *
 * @param handle         The plugin or connection handle.  For some
 *                       things this is EXTREMELY important.  See
 *                       the comments on purple_request_input.
 * @param title          The title of the message.
 * @param primary        The main point of the message.
 * @param secondary      The secondary information.
 * @param default_action The default value.
 * @param account		 The PurpleAccount associated with this request, or NULL if none is
 * @param who			 The username of the buddy assocaited with this request, or NULL if none is
 * @param conv			 The PurpleConversation associated with this request, or NULL if none is
 * @param user_data      The data to pass to the callback.
 * @param action_count   The number of actions.
 * @param actions        A list of actions and callbacks.
 *
 * @return A UI-specific handle.
 */
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);

/**
 * Displays groups of fields for the user to fill in.
 *
 * @param handle      The plugin or connection handle.  For some
 *                    things this is EXTREMELY important.  See
 *                    the comments on purple_request_input.
 * @param title       The title of the message.
 * @param primary     The main point of the message.
 * @param secondary   The secondary information.
 * @param fields      The list of fields.
 * @param ok_text     The text for the @c OK button.
 * @param ok_cb       The callback for the @c OK button.
 * @param cancel_text The text for the @c Cancel button.
 * @param cancel_cb   The callback for the @c Cancel button.
 * @param account	  The PurpleAccount associated with this request, or NULL if none is
 * @param who		  The username of the buddy associated with this request, or NULL if none is
 * @param conv		  The PurpleConversation associated with this request, or NULL if none is
 * @param user_data   The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
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);

/**
 * Closes a request.
 *
 * @param type     The request type.

void purple_request_close(PurpleRequestType type, void *uihandle);

/**
 * Closes all requests registered with the specified handle.
 *
 * @param handle The handle.
 */
void purple_request_close_with_handle(void *handle);

/**
 * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.

/**
 * 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.
 *
 * @param handle      The plugin or connection handle.  For some
 *                    things this is EXTREMELY important.  See
 *                    the comments on purple_request_input.
 * @param title       The title for the dialog (may be @c NULL)
 * @param filename    The default filename (may be @c NULL)
 * @param savedialog  True if this dialog is being used to save a file.
 *                    False if it is being used to open a file.
 * @param ok_cb       The callback for the @c OK button.
 * @param cancel_cb   The callback for the @c Cancel button.
 * @param account	  The PurpleAccount associated with this request, or NULL if none is
 * @param who		  The username of the buddy assocaited with this request, or NULL if none is
 * @param conv		  The PurpleConversation associated with this request, or NULL if none is
 * @param user_data   The data to pass to the callback.
 *
 * @return A UI-specific 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 folder select dialog. Returns the selected filename to
 * the callback.
 *
 * @param handle      The plugin or connection handle.  For some
 *                    things this is EXTREMELY important.  See
 *                    the comments on purple_request_input.
 * @param title       The title for the dialog (may be @c NULL)
 * @param dirname     The default directory name (may be @c NULL)
 * @param ok_cb       The callback for the @c OK button.
 * @param cancel_cb   The callback for the @c Cancel button.
 * @param account	  The PurpleAccount associated with this request, or NULL if none is
 * @param who		  The username of the buddy assocaited with this request, or NULL if none is
 * @param conv		  The PurpleConversation associated with this request, or NULL if none is
 * @param user_data   The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *purple_request_folder(void *handle, const char *title, const char *dirname,
						GCallback ok_cb, GCallback cancel_cb,
						PurpleAccount *account, const char *who, PurpleConversation *conv,
						void *user_data);

/*@}*/

/**************************************************************************/
/** @name UI Registration Functions                                       */

21876:2ca7a3d28186

/**
 * 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);

/**
 * Prompts the user for text input.
 *
 * @param handle        The plugin or connection handle.  For some
 *                      things this is <em>extremely</em> 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
 *                      <em>not</em> closed it is <strong>very</strong>
 *                      likely to cause a crash whenever the callback
 *                      handler functions are triggered.
 * @param title         The title of the message, or @c NULL if it should have
 *                      no title.
 * @param primary       The main point of the message, or @c NULL if you're
 *                      feeling enigmatic.
 * @param secondary     Secondary information, or @c NULL if there is none.
 * @param default_value The default value.
 * @param multiline     @c TRUE if the inputted text can span multiple lines.
 * @param masked        @c 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.
 * @param hint          Optionally suggest how the input box should appear.
 *                      Use "html", for example, to allow the user to enter
 *                      HTML.
 * @param ok_text       The text for the @c OK button, which may not be @c NULL.
 * @param ok_cb         The callback for the @c OK button, which may not be @c
 *                      NULL.
 * @param cancel_text   The text for the @c Cancel button, which may not be @c
 *                      NULL.
 * @param cancel_cb     The callback for the @c Cancel button, which may not be
 *                      @c NULL.
 * @param account       The #PurpleAccount associated with this request, or @c
 *                      NULL if none is.
 * @param who           The username of the buddy assonciated with this request,
 *                      or @c NULL if none is.
 * @param conv          The #PurpleConversation associated with this request, or
 *                      @c NULL if none is.
 * @param user_data     The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
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 multiple-choice input.
 *
 * @param handle        The plugin or connection handle.  For some things this
 *                      is <em>extremely</em> important.  See the comments on
 *                      purple_request_input().
 * @param title         The title of the message, or @c NULL if it should have
 *                      no title.
 * @param primary       The main point of the message, or @c NULL if you're
 *                      feeling enigmatic.
 * @param secondary     Secondary information, or @c NULL if there is none.
 * @param default_value The default choice; this should be one of the values
 *                      listed in the varargs.
 * @param ok_text       The text for the @c OK button, which may not be @c NULL.
 * @param ok_cb         The callback for the @c OK button, which may not be @c
 *                      NULL.
 * @param cancel_text   The text for the @c Cancel button, which may not be @c
 *                      NULL.
 * @param cancel_cb     The callback for the @c Cancel button, which may not be
 *                      @c NULL.
 * @param account       The #PurpleAccount associated with this request, or @c
 *                      NULL if none is.
 * @param who           The username of the buddy assonciated with this request,
 *                      or @c NULL if none is.
 * @param conv          The #PurpleConversation associated with this request, or
 *                      @c NULL if none is.
 * @param user_data     The data to pass to the callback.
 * @param ...           The choices, which should be pairs of <tt>char *</tt>
 *                      descriptions and <tt>int</tt> values, terminated with a
 *                      @c NULL parameter.
 *
 * @return A UI-specific handle.
 */
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.
 *
 * @param handle        The plugin or connection handle.  For some things this
 *                      is <em>extremely</em> important.  See the comments on
 *                      purple_request_input().
 * @param title         The title of the message, or @c NULL if it should have
 *                      no title.
 * @param primary       The main point of the message, or @c NULL if you're
 *                      feeling enigmatic.
 * @param secondary     Secondary information, or @c NULL if there is none.
 * @param default_value The default choice; this should be one of the values
 *                      listed in the varargs.
 * @param ok_text       The text for the @c OK button, which may not be @c NULL.
 * @param ok_cb         The callback for the @c OK button, which may not be @c
 *                      NULL.
 * @param cancel_text   The text for the @c Cancel button, which may not be @c
 *                      NULL.
 * @param cancel_cb     The callback for the @c Cancel button, which may not be
 *                      @c NULL.
 * @param account       The #PurpleAccount associated with this request, or @c
 *                      NULL if none is
 * @param who           The username of the buddy assonciated with this request,
 *                      or @c NULL if none is
 * @param conv          The #PurpleConversation associated with this request, or
 *                      @c NULL if none is
 * @param user_data     The data to pass to the callback.
 * @param choices       The choices, which should be pairs of <tt>char *</tt>
 *                      descriptions and <tt>int</tt> values, terminated with a
 *                      @c NULL parameter.
 *
 * @return A UI-specific handle.
 */
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);

/**
 * Prompts the user for an action.
 *
 * This is often represented as a dialog with a button for each action.
 *
 * @param handle         The plugin or connection handle.  For some things this
 *                       is <em>extremely</em> important.  See the comments on
 *                       purple_request_input().
 * @param title          The title of the message, or @c NULL if it should have
 *                       no title.
 * @param primary        The main point of the message, or @c NULL if you're
 *                       feeling enigmatic.
 * @param secondary      Secondary information, or @c NULL if there is none.
 * @param default_action The default action, zero-indexed; if the third action
 *                       supplied should be the default, supply <tt>2</tt>.
 * @param account        The #PurpleAccount associated with this request, or @c
 *                       NULL if none is.
 * @param who            The username of the buddy assonciated with this request,
 *                       or @c NULL if none is.
 * @param conv           The #PurpleConversation associated with this request, or
 *                       @c NULL if none is.
 * @param user_data      The data to pass to the callback.
 * @param action_count   The number of actions.
 * @param ...            A list of actions.  These are pairs of
 *                       arguments.  The first of each pair is the
 *                       <tt>char *</tt> 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 <tt>GCallback</tt>
 *                       function to use when the button is clicked.
 *
 * @return A UI-specific handle.
 */
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.
 *
 * @param handle         The plugin or connection handle.  For some things this
 *                       is <em>extremely</em> important.  See the comments on
 *                       purple_request_input().
 * @param title          The title of the message, or @c NULL if it should have
 *                       no title.
 * @param primary        The main point of the message, or @c NULL if you're
 *                       feeling enigmatic.
 * @param secondary      Secondary information, or @c NULL if there is none.
 * @param default_action The default action, zero-indexed; if the third action
 *                       supplied should be the default, supply <tt>2</tt>.
 * @param account        The #PurpleAccount associated with this request, or @c
 *                       NULL if none is.
 * @param who            The username of the buddy assonciated with this request,
 *                       or @c NULL if none is.
 * @param conv           The #PurpleConversation associated with this request, or
 *                       @c NULL if none is.
 * @param user_data      The data to pass to the callback.
 * @param action_count   The number of actions.
 * @param actions        A list of actions.  These are pairs of
 *                       arguments.  The first of each pair is the
 *                       <tt>char *</tt> 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 <tt>GCallback</tt>
 *                       function to use when the button is clicked.
 *
 * @return A UI-specific handle.
 */
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);

/**
 * Displays groups of fields for the user to fill in.
 *
 * @param handle      The plugin or connection handle.  For some things this
 *                    is <em>extremely</em> important.  See the comments on
 *                    purple_request_input().
 * @param title       The title of the message, or @c NULL if it should have
 *                    no title.
 * @param primary     The main point of the message, or @c NULL if you're
 *                    feeling enigmatic.
 * @param secondary   Secondary information, or @c NULL if there is none.
 * @param fields      The list of fields.
 * @param ok_text     The text for the @c OK button, which may not be @c NULL.
 * @param ok_cb       The callback for the @c OK button, which may not be @c
 *                    NULL.
 * @param cancel_text The text for the @c Cancel button, which may not be @c
 *                    NULL.
 * @param cancel_cb   The callback for the @c Cancel button, which may not be
 *                    @c NULL.
 * @param account     The #PurpleAccount associated with this request, or @c
 *                    NULL if none is
 * @param who         The username of the buddy assonciated with this request,
 *                    or @c NULL if none is
 * @param conv        The #PurpleConversation associated with this request, or
 *                    @c NULL if none is
 * @param user_data   The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
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);

/**
 * Closes a request.
 *
 * @param type     The request type.

void purple_request_close(PurpleRequestType type, void *uihandle);

/**
 * Closes all requests registered with the specified handle.
 *
 * @param handle The handle, as supplied as the @a handle parameter to one of the
 *               <tt>purple_request_*</tt> functions.
 *
 * @see purple_request_input().
 */
void purple_request_close_with_handle(void *handle);

/**
 * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.

/**
 * 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.
 *
 * @param handle      The plugin or connection handle.  For some things this
 *                    is <em>extremely</em> important.  See the comments on
 *                    purple_request_input().
 * @param title       The title of the message, or @c NULL if it should have
 *                    no title.
 * @param filename    The default filename (may be @c NULL)
 * @param savedialog  True if this dialog is being used to save a file.
 *                    False if it is being used to open a file.
 * @param ok_cb       The callback for the @c OK button.
 * @param cancel_cb   The callback for the @c Cancel button.
 * @param account     The #PurpleAccount associated with this request, or @c
 *                    NULL if none is
 * @param who         The username of the buddy assonciated with this request,
 *                    or @c NULL if none is
 * @param conv        The #PurpleConversation associated with this request, or
 *                    @c NULL if none is
 * @param user_data   The data to pass to the callback.
 *
 * @return A UI-specific 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 folder select dialog. Returns the selected filename to
 * the callback.
 *
 * @param handle      The plugin or connection handle.  For some things this
 *                    is <em>extremely</em> important.  See the comments on
 *                    purple_request_input().
 * @param title       The title of the message, or @c NULL if it should have
 *                    no title.
 * @param dirname     The default directory name (may be @c NULL)
 * @param ok_cb       The callback for the @c OK button.
 * @param cancel_cb   The callback for the @c Cancel button.
 * @param account     The #PurpleAccount associated with this request, or @c
 *                    NULL if none is
 * @param who         The username of the buddy assonciated with this request,
 *                    or @c NULL if none is
 * @param conv        The #PurpleConversation associated with this request, or
 *                    @c NULL if none is
 * @param user_data   The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *purple_request_folder(void *handle, const char *title, const char *dirname,
	GCallback ok_cb, GCallback cancel_cb,
	PurpleAccount *account, const char *who, PurpleConversation *conv,
	void *user_data);

/*@}*/

/**************************************************************************/
/** @name UI Registration Functions                                       */