1 /**
2  * @file request.h Request API
3  * @ingroup core
4  */
5 
6 /* purple
7  *
8  * Purple is the legal property of its developers, whose names are too numerous
9  * to list here.  Please refer to the COPYRIGHT file distributed with this
10  * source distribution.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation; either version 2 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program; if not, write to the Free Software
24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
25  */
26 #ifndef _PURPLE_REQUEST_H_
27 #define _PURPLE_REQUEST_H_
28 
29 #include <stdlib.h>
30 #include <glib-object.h>
31 #include <glib.h>
32 
33 /** @copydoc _PurpleRequestField */
34 typedef struct _PurpleRequestField PurpleRequestField;
35 
36 #include "account.h"
37 
38 #define PURPLE_DEFAULT_ACTION_NONE	-1
39 
40 /**
41  * Request types.
42  */
43 typedef enum
44 {
45 	PURPLE_REQUEST_INPUT = 0,  /**< Text input request.        */
46 	PURPLE_REQUEST_CHOICE,     /**< Multiple-choice request.   */
47 	PURPLE_REQUEST_ACTION,     /**< Action request.            */
48 	PURPLE_REQUEST_FIELDS,     /**< Multiple fields request.   */
49 	PURPLE_REQUEST_FILE,       /**< File open or save request. */
50 	PURPLE_REQUEST_FOLDER,     /**< Folder selection request.  */
51 	PURPLE_REQUEST_SCREENSHARE /**< Screenshare media request. */
52 
53 } PurpleRequestType;
54 
55 /**
56  * A type of field.
57  */
58 typedef enum
59 {
60 	PURPLE_REQUEST_FIELD_NONE,
61 	PURPLE_REQUEST_FIELD_STRING,
62 	PURPLE_REQUEST_FIELD_INTEGER,
63 	PURPLE_REQUEST_FIELD_BOOLEAN,
64 	PURPLE_REQUEST_FIELD_CHOICE,
65 	PURPLE_REQUEST_FIELD_LIST,
66 	PURPLE_REQUEST_FIELD_LABEL,
67 	PURPLE_REQUEST_FIELD_IMAGE,
68 	PURPLE_REQUEST_FIELD_ACCOUNT
69 
70 } PurpleRequestFieldType;
71 
72 /**
73  * Multiple fields request data.
74  */
75 typedef struct
76 {
77 	GList *groups;
78 
79 	GHashTable *fields;
80 
81 	GList *required_fields;
82 
83 	void *ui_data;
84 
85 } PurpleRequestFields;
86 
87 /**
88  * A group of fields with a title.
89  */
90 typedef struct
91 {
92 	PurpleRequestFields *fields_list;
93 
94 	char *title;
95 
96 	GList *fields;
97 
98 } PurpleRequestFieldGroup;
99 
100 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_REQUEST_C_)
101 /**
102  * A request field.
103  */
104 struct _PurpleRequestField
105 {
106 	PurpleRequestFieldType type;
107 	PurpleRequestFieldGroup *group;
108 
109 	char *id;
110 	char *label;
111 	char *type_hint;
112 
113 	gboolean visible;
114 	gboolean required;
115 
116 	union
117 	{
118 		struct
119 		{
120 			gboolean multiline;
121 			gboolean masked;
122 			gboolean editable;
123 			char *default_value;
124 			char *value;
125 
126 		} string;
127 
128 		struct
129 		{
130 			int default_value;
131 			int value;
132 
133 		} integer;
134 
135 		struct
136 		{
137 			gboolean default_value;
138 			gboolean value;
139 
140 		} boolean;
141 
142 		struct
143 		{
144 			int default_value;
145 			int value;
146 
147 			GList *labels;
148 
149 		} choice;
150 
151 		struct
152 		{
153 			GList *items;
154 			GList *icons;
155 			GHashTable *item_data;
156 			GList *selected;
157 			GHashTable *selected_table;
158 
159 			gboolean multiple_selection;
160 
161 		} list;
162 
163 		struct
164 		{
165 			PurpleAccount *default_account;
166 			PurpleAccount *account;
167 			gboolean show_all;
168 
169 			PurpleFilterAccountFunc filter_func;
170 
171 		} account;
172 
173 		struct
174 		{
175 			unsigned int scale_x;
176 			unsigned int scale_y;
177 			const char *buffer;
178 			gsize size;
179 		} image;
180 
181 	} u;
182 
183 	void *ui_data;
184 
185 };
186 #endif
187 
188 /**
189  * Request UI operations.
190  */
191 typedef struct
192 {
193 	/** @see purple_request_input(). */
194 	void *(*request_input)(const char *title, const char *primary,
195 	                       const char *secondary, const char *default_value,
196 	                       gboolean multiline, gboolean masked, gchar *hint,
197 	                       const char *ok_text, GCallback ok_cb,
198 	                       const char *cancel_text, GCallback cancel_cb,
199 	                       PurpleAccount *account, const char *who,
200 	                       PurpleConversation *conv, void *user_data);
201 
202 	/** @see purple_request_choice_varg(). */
203 	void *(*request_choice)(const char *title, const char *primary,
204 	                        const char *secondary, int default_value,
205 	                        const char *ok_text, GCallback ok_cb,
206 	                        const char *cancel_text, GCallback cancel_cb,
207 	                        PurpleAccount *account, const char *who,
208 	                        PurpleConversation *conv, void *user_data,
209 	                        va_list choices);
210 
211 	/** @see purple_request_action_varg(). */
212 	void *(*request_action)(const char *title, const char *primary,
213 	                        const char *secondary, int default_action,
214 	                        PurpleAccount *account, const char *who,
215 	                        PurpleConversation *conv, void *user_data,
216 	                        size_t action_count, va_list actions);
217 
218 	/** @see purple_request_fields(). */
219 	void *(*request_fields)(const char *title, const char *primary,
220 	                        const char *secondary, PurpleRequestFields *fields,
221 	                        const char *ok_text, GCallback ok_cb,
222 	                        const char *cancel_text, GCallback cancel_cb,
223 	                        PurpleAccount *account, const char *who,
224 	                        PurpleConversation *conv, void *user_data);
225 
226 	/** @see purple_request_file(). */
227 	void *(*request_file)(const char *title, const char *filename,
228 	                      gboolean savedialog, GCallback ok_cb,
229 	                      GCallback cancel_cb, PurpleAccount *account,
230 	                      const char *who, PurpleConversation *conv,
231 	                      void *user_data);
232 
233 	void (*close_request)(PurpleRequestType type, void *ui_handle);
234 
235 	/** @see purple_request_folder(). */
236 	void *(*request_folder)(const char *title, const char *dirname,
237 	                        GCallback ok_cb, GCallback cancel_cb,
238 	                        PurpleAccount *account, const char *who,
239 	                        PurpleConversation *conv, void *user_data);
240 
241 	/** @see purple_request_action_with_icon_varg(). */
242 	void *(*request_action_with_icon)(const char *title, const char *primary,
243 	                        const char *secondary, int default_action,
244 	                        PurpleAccount *account, const char *who,
245 	                        PurpleConversation *conv,
246 	                        gconstpointer icon_data, gsize icon_size,
247 	                        void *user_data,
248 	                        size_t action_count, va_list actions);
249 
250 	void *(*request_screenshare_media)(const char *title, const char *primary,
251 				const char *secondary, PurpleAccount *account,
252 				GCallback cb, void *user_data);
253 
254 	void (*_purple_reserved1)(void);
255 	void (*_purple_reserved2)(void);
256 } PurpleRequestUiOps;
257 
258 typedef void (*PurpleRequestInputCb)(void *, const char *);
259 
260 /** The type of callbacks passed to purple_request_action().  The first
261  *  argument is the @a user_data parameter; the second is the index in the list
262  *  of actions of the one chosen.
263  */
264 typedef void (*PurpleRequestActionCb)(void *, int);
265 typedef void (*PurpleRequestChoiceCb)(void *, int);
266 typedef void (*PurpleRequestFieldsCb)(void *, PurpleRequestFields *fields);
267 typedef void (*PurpleRequestFileCb)(void *, const char *filename);
268 typedef void (*PurpleRequestScreenshareCb)(void *, GObject *info);
269 
270 #ifdef __cplusplus
271 extern "C" {
272 #endif
273 
274 /**************************************************************************/
275 /** @name Field List API                                                  */
276 /**************************************************************************/
277 /*@{*/
278 
279 /**
280  * Creates a list of fields to pass to purple_request_fields().
281  *
282  * @return A PurpleRequestFields structure.
283  */
284 PurpleRequestFields *purple_request_fields_new(void);
285 
286 /**
287  * Destroys a list of fields.
288  *
289  * @param fields The list of fields to destroy.
290  */
291 void purple_request_fields_destroy(PurpleRequestFields *fields);
292 
293 /**
294  * Adds a group of fields to the list.
295  *
296  * @param fields The fields list.
297  * @param group  The group to add.
298  */
299 void purple_request_fields_add_group(PurpleRequestFields *fields,
300 								   PurpleRequestFieldGroup *group);
301 
302 /**
303  * Returns a list of all groups in a field list.
304  *
305  * @param fields The fields list.
306  *
307  * @constreturn A list of groups.
308  */
309 GList *purple_request_fields_get_groups(const PurpleRequestFields *fields);
310 
311 /**
312  * Returns whether or not the field with the specified ID exists.
313  *
314  * @param fields The fields list.
315  * @param id     The ID of the field.
316  *
317  * @return TRUE if the field exists, or FALSE.
318  */
319 gboolean purple_request_fields_exists(const PurpleRequestFields *fields,
320 									const char *id);
321 
322 /**
323  * Returns a list of all required fields.
324  *
325  * @param fields The fields list.
326  *
327  * @constreturn The list of required fields.
328  */
329 GList *purple_request_fields_get_required(const PurpleRequestFields *fields);
330 
331 /**
332  * Returns whether or not a field with the specified ID is required.
333  *
334  * @param fields The fields list.
335  * @param id     The field ID.
336  *
337  * @return TRUE if the specified field is required, or FALSE.
338  */
339 gboolean purple_request_fields_is_field_required(const PurpleRequestFields *fields,
340 											   const char *id);
341 
342 /**
343  * Returns whether or not all required fields have values.
344  *
345  * @param fields The fields list.
346  *
347  * @return TRUE if all required fields have values, or FALSE.
348  */
349 gboolean purple_request_fields_all_required_filled(
350 	const PurpleRequestFields *fields);
351 
352 /**
353  * Return the field with the specified ID.
354  *
355  * @param fields The fields list.
356  * @param id     The ID of the field.
357  *
358  * @return The field, if found.
359  */
360 PurpleRequestField *purple_request_fields_get_field(
361 		const PurpleRequestFields *fields, const char *id);
362 
363 /**
364  * Returns the string value of a field with the specified ID.
365  *
366  * @param fields The fields list.
367  * @param id     The ID of the field.
368  *
369  * @return The string value, if found, or @c NULL otherwise.
370  */
371 const char *purple_request_fields_get_string(const PurpleRequestFields *fields,
372 										   const char *id);
373 
374 /**
375  * Returns the integer value of a field with the specified ID.
376  *
377  * @param fields The fields list.
378  * @param id     The ID of the field.
379  *
380  * @return The integer value, if found, or 0 otherwise.
381  */
382 int purple_request_fields_get_integer(const PurpleRequestFields *fields,
383 									const char *id);
384 
385 /**
386  * Returns the boolean value of a field with the specified ID.
387  *
388  * @param fields The fields list.
389  * @param id     The ID of the field.
390  *
391  * @return The boolean value, if found, or @c FALSE otherwise.
392  */
393 gboolean purple_request_fields_get_bool(const PurpleRequestFields *fields,
394 									  const char *id);
395 
396 /**
397  * Returns the choice index of a field with the specified ID.
398  *
399  * @param fields The fields list.
400  * @param id     The ID of the field.
401  *
402  * @return The choice index, if found, or -1 otherwise.
403  */
404 int purple_request_fields_get_choice(const PurpleRequestFields *fields,
405 								   const char *id);
406 
407 /**
408  * Returns the account of a field with the specified ID.
409  *
410  * @param fields The fields list.
411  * @param id     The ID of the field.
412  *
413  * @return The account value, if found, or NULL otherwise.
414  */
415 PurpleAccount *purple_request_fields_get_account(const PurpleRequestFields *fields,
416 											 const char *id);
417 
418 /*@}*/
419 
420 /**************************************************************************/
421 /** @name Fields Group API                                                */
422 /**************************************************************************/
423 /*@{*/
424 
425 /**
426  * Creates a fields group with an optional title.
427  *
428  * @param title The optional title to give the group.
429  *
430  * @return A new fields group
431  */
432 PurpleRequestFieldGroup *purple_request_field_group_new(const char *title);
433 
434 /**
435  * Destroys a fields group.
436  *
437  * @param group The group to destroy.
438  */
439 void purple_request_field_group_destroy(PurpleRequestFieldGroup *group);
440 
441 /**
442  * Adds a field to the group.
443  *
444  * @param group The group to add the field to.
445  * @param field The field to add to the group.
446  */
447 void purple_request_field_group_add_field(PurpleRequestFieldGroup *group,
448 										PurpleRequestField *field);
449 
450 /**
451  * Returns the title of a fields group.
452  *
453  * @param group The group.
454  *
455  * @return The title, if set.
456  */
457 const char *purple_request_field_group_get_title(
458 		const PurpleRequestFieldGroup *group);
459 
460 /**
461  * Returns a list of all fields in a group.
462  *
463  * @param group The group.
464  *
465  * @constreturn The list of fields in the group.
466  */
467 GList *purple_request_field_group_get_fields(
468 		const PurpleRequestFieldGroup *group);
469 
470 /*@}*/
471 
472 /**************************************************************************/
473 /** @name Field API                                                       */
474 /**************************************************************************/
475 /*@{*/
476 
477 /**
478  * Creates a field of the specified type.
479  *
480  * @param id   The field ID.
481  * @param text The text label of the field.
482  * @param type The type of field.
483  *
484  * @return The new field.
485  */
486 PurpleRequestField *purple_request_field_new(const char *id, const char *text,
487 										 PurpleRequestFieldType type);
488 
489 /**
490  * Destroys a field.
491  *
492  * @param field The field to destroy.
493  */
494 void purple_request_field_destroy(PurpleRequestField *field);
495 
496 /**
497  * Sets the label text of a field.
498  *
499  * @param field The field.
500  * @param label The text label.
501  */
502 void purple_request_field_set_label(PurpleRequestField *field, const char *label);
503 
504 /**
505  * Sets whether or not a field is visible.
506  *
507  * @param field   The field.
508  * @param visible TRUE if visible, or FALSE if not.
509  */
510 void purple_request_field_set_visible(PurpleRequestField *field, gboolean visible);
511 
512 /**
513  * Sets the type hint for the field.
514  *
515  * This is optionally used by the UIs to provide such features as
516  * auto-completion for type hints like "account" and "screenname".
517  *
518  * @param field     The field.
519  * @param type_hint The type hint.
520  */
521 void purple_request_field_set_type_hint(PurpleRequestField *field,
522 									  const char *type_hint);
523 
524 /**
525  * Sets whether or not a field is required.
526  *
527  * @param field    The field.
528  * @param required TRUE if required, or FALSE.
529  */
530 void purple_request_field_set_required(PurpleRequestField *field,
531 									 gboolean required);
532 
533 /**
534  * Returns the type of a field.
535  *
536  * @param field The field.
537  *
538  * @return The field's type.
539  */
540 PurpleRequestFieldType purple_request_field_get_type(const PurpleRequestField *field);
541 
542 /**
543  * Returns the group for the field.
544  *
545  * @param field The field.
546  *
547  * @return The UI data.
548  *
549  * @since 2.6.0
550  */
551 PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field);
552 
553 /**
554  * Returns the ID of a field.
555  *
556  * @param field The field.
557  *
558  * @return The ID
559  */
560 const char *purple_request_field_get_id(const PurpleRequestField *field);
561 
562 /**
563  * Returns the label text of a field.
564  *
565  * @param field The field.
566  *
567  * @return The label text.
568  */
569 const char *purple_request_field_get_label(const PurpleRequestField *field);
570 
571 /**
572  * Returns whether or not a field is visible.
573  *
574  * @param field The field.
575  *
576  * @return TRUE if the field is visible. FALSE otherwise.
577  */
578 gboolean purple_request_field_is_visible(const PurpleRequestField *field);
579 
580 /**
581  * Returns the field's type hint.
582  *
583  * @param field The field.
584  *
585  * @return The field's type hint.
586  */
587 const char *purple_request_field_get_type_hint(const PurpleRequestField *field);
588 
589 /**
590  * Returns whether or not a field is required.
591  *
592  * @param field The field.
593  *
594  * @return TRUE if the field is required, or FALSE.
595  */
596 gboolean purple_request_field_is_required(const PurpleRequestField *field);
597 
598 /**
599  * Returns the ui_data for a field.
600  *
601  * @param field The field.
602  *
603  * @return The UI data.
604  *
605  * @since 2.6.0
606  */
607 gpointer purple_request_field_get_ui_data(const PurpleRequestField *field);
608 
609 /**
610  * Sets the ui_data for a field.
611  *
612  * @param field The field.
613  * @param ui_data The UI data.
614  *
615  * @return The UI data.
616  *
617  * @since 2.6.0
618  */
619 void purple_request_field_set_ui_data(PurpleRequestField *field,
620                                       gpointer ui_data);
621 
622 /*@}*/
623 
624 /**************************************************************************/
625 /** @name String Field API                                                */
626 /**************************************************************************/
627 /*@{*/
628 
629 /**
630  * Creates a string request field.
631  *
632  * @param id            The field ID.
633  * @param text          The text label of the field.
634  * @param default_value The optional default value.
635  * @param multiline     Whether or not this should be a multiline string.
636  *
637  * @return The new field.
638  */
639 PurpleRequestField *purple_request_field_string_new(const char *id,
640 												const char *text,
641 												const char *default_value,
642 												gboolean multiline);
643 
644 /**
645  * Sets the default value in a string field.
646  *
647  * @param field         The field.
648  * @param default_value The default value.
649  */
650 void purple_request_field_string_set_default_value(PurpleRequestField *field,
651 												 const char *default_value);
652 
653 /**
654  * Sets the value in a string field.
655  *
656  * @param field The field.
657  * @param value The value.
658  */
659 void purple_request_field_string_set_value(PurpleRequestField *field,
660 										 const char *value);
661 
662 /**
663  * Sets whether or not a string field is masked
664  * (commonly used for password fields).
665  *
666  * @param field  The field.
667  * @param masked The masked value.
668  */
669 void purple_request_field_string_set_masked(PurpleRequestField *field,
670 										  gboolean masked);
671 
672 /**
673  * Sets whether or not a string field is editable.
674  *
675  * @param field    The field.
676  * @param editable The editable value.
677  */
678 void purple_request_field_string_set_editable(PurpleRequestField *field,
679 											gboolean editable);
680 
681 /**
682  * Returns the default value in a string field.
683  *
684  * @param field The field.
685  *
686  * @return The default value.
687  */
688 const char *purple_request_field_string_get_default_value(
689 		const PurpleRequestField *field);
690 
691 /**
692  * Returns the user-entered value in a string field.
693  *
694  * @param field The field.
695  *
696  * @return The value.
697  */
698 const char *purple_request_field_string_get_value(const PurpleRequestField *field);
699 
700 /**
701  * Returns whether or not a string field is multi-line.
702  *
703  * @param field The field.
704  *
705  * @return @c TRUE if the field is mulit-line, or @c FALSE otherwise.
706  */
707 gboolean purple_request_field_string_is_multiline(const PurpleRequestField *field);
708 
709 /**
710  * Returns whether or not a string field is masked.
711  *
712  * @param field The field.
713  *
714  * @return @c TRUE if the field is masked, or @c FALSE otherwise.
715  */
716 gboolean purple_request_field_string_is_masked(const PurpleRequestField *field);
717 
718 /**
719  * Returns whether or not a string field is editable.
720  *
721  * @param field The field.
722  *
723  * @return @c TRUE if the field is editable, or @c FALSE otherwise.
724  */
725 gboolean purple_request_field_string_is_editable(const PurpleRequestField *field);
726 
727 /*@}*/
728 
729 /**************************************************************************/
730 /** @name Integer Field API                                               */
731 /**************************************************************************/
732 /*@{*/
733 
734 /**
735  * Creates an integer field.
736  *
737  * @param id            The field ID.
738  * @param text          The text label of the field.
739  * @param default_value The default value.
740  *
741  * @return The new field.
742  */
743 PurpleRequestField *purple_request_field_int_new(const char *id,
744 											 const char *text,
745 											 int default_value);
746 
747 /**
748  * Sets the default value in an integer field.
749  *
750  * @param field         The field.
751  * @param default_value The default value.
752  */
753 void purple_request_field_int_set_default_value(PurpleRequestField *field,
754 											  int default_value);
755 
756 /**
757  * Sets the value in an integer field.
758  *
759  * @param field The field.
760  * @param value The value.
761  */
762 void purple_request_field_int_set_value(PurpleRequestField *field, int value);
763 
764 /**
765  * Returns the default value in an integer field.
766  *
767  * @param field The field.
768  *
769  * @return The default value.
770  */
771 int purple_request_field_int_get_default_value(const PurpleRequestField *field);
772 
773 /**
774  * Returns the user-entered value in an integer field.
775  *
776  * @param field The field.
777  *
778  * @return The value.
779  */
780 int purple_request_field_int_get_value(const PurpleRequestField *field);
781 
782 /*@}*/
783 
784 /**************************************************************************/
785 /** @name Boolean Field API                                               */
786 /**************************************************************************/
787 /*@{*/
788 
789 /**
790  * Creates a boolean field.
791  *
792  * This is often represented as a checkbox.
793  *
794  * @param id            The field ID.
795  * @param text          The text label of the field.
796  * @param default_value The default value.
797  *
798  * @return The new field.
799  */
800 PurpleRequestField *purple_request_field_bool_new(const char *id,
801 											  const char *text,
802 											  gboolean default_value);
803 
804 /**
805  * Sets the default value in an boolean field.
806  *
807  * @param field         The field.
808  * @param default_value The default value.
809  */
810 void purple_request_field_bool_set_default_value(PurpleRequestField *field,
811 											   gboolean default_value);
812 
813 /**
814  * Sets the value in an boolean field.
815  *
816  * @param field The field.
817  * @param value The value.
818  */
819 void purple_request_field_bool_set_value(PurpleRequestField *field,
820 									   gboolean value);
821 
822 /**
823  * Returns the default value in an boolean field.
824  *
825  * @param field The field.
826  *
827  * @return The default value.
828  */
829 gboolean purple_request_field_bool_get_default_value(
830 		const PurpleRequestField *field);
831 
832 /**
833  * Returns the user-entered value in an boolean field.
834  *
835  * @param field The field.
836  *
837  * @return The value.
838  */
839 gboolean purple_request_field_bool_get_value(const PurpleRequestField *field);
840 
841 /*@}*/
842 
843 /**************************************************************************/
844 /** @name Choice Field API                                                */
845 /**************************************************************************/
846 /*@{*/
847 
848 /**
849  * Creates a multiple choice field.
850  *
851  * This is often represented as a group of radio buttons.
852  *
853  * @param id            The field ID.
854  * @param text          The optional label of the field.
855  * @param default_value The default choice.
856  *
857  * @return The new field.
858  */
859 PurpleRequestField *purple_request_field_choice_new(const char *id,
860 												const char *text,
861 												int default_value);
862 
863 /**
864  * Adds a choice to a multiple choice field.
865  *
866  * @param field The choice field.
867  * @param label The choice label.
868  */
869 void purple_request_field_choice_add(PurpleRequestField *field,
870 								   const char *label);
871 
872 /**
873  * Sets the default value in an choice field.
874  *
875  * @param field         The field.
876  * @param default_value The default value.
877  */
878 void purple_request_field_choice_set_default_value(PurpleRequestField *field,
879 												 int default_value);
880 
881 /**
882  * Sets the value in an choice field.
883  *
884  * @param field The field.
885  * @param value The value.
886  */
887 void purple_request_field_choice_set_value(PurpleRequestField *field, int value);
888 
889 /**
890  * Returns the default value in an choice field.
891  *
892  * @param field The field.
893  *
894  * @return The default value.
895  */
896 int purple_request_field_choice_get_default_value(const PurpleRequestField *field);
897 
898 /**
899  * Returns the user-entered value in an choice field.
900  *
901  * @param field The field.
902  *
903  * @return The value.
904  */
905 int purple_request_field_choice_get_value(const PurpleRequestField *field);
906 
907 /**
908  * Returns a list of labels in a choice field.
909  *
910  * @param field The field.
911  *
912  * @constreturn The list of labels.
913  */
914 GList *purple_request_field_choice_get_labels(const PurpleRequestField *field);
915 
916 /*@}*/
917 
918 /**************************************************************************/
919 /** @name List Field API                                                  */
920 /**************************************************************************/
921 /*@{*/
922 
923 /**
924  * Creates a multiple list item field.
925  *
926  * @param id   The field ID.
927  * @param text The optional label of the field.
928  *
929  * @return The new field.
930  */
931 PurpleRequestField *purple_request_field_list_new(const char *id, const char *text);
932 
933 /**
934  * Sets whether or not a list field allows multiple selection.
935  *
936  * @param field        The list field.
937  * @param multi_select TRUE if multiple selection is enabled,
938  *                     or FALSE otherwise.
939  */
940 void purple_request_field_list_set_multi_select(PurpleRequestField *field,
941 											  gboolean multi_select);
942 
943 /**
944  * Returns whether or not a list field allows multiple selection.
945  *
946  * @param field The list field.
947  *
948  * @return TRUE if multiple selection is enabled, or FALSE otherwise.
949  */
950 gboolean purple_request_field_list_get_multi_select(
951 	const PurpleRequestField *field);
952 
953 /**
954  * Returns the data for a particular item.
955  *
956  * @param field The list field.
957  * @param text  The item text.
958  *
959  * @return The data associated with the item.
960  */
961 void *purple_request_field_list_get_data(const PurpleRequestField *field,
962 									   const char *text);
963 
964 /**
965  * Adds an item to a list field.
966  *
967  * @param field The list field.
968  * @param item  The list item.
969  * @param data  The associated data.
970  *
971  * @deprecated Use purple_request_field_list_add_icon() instead.
972  */
973 void purple_request_field_list_add(PurpleRequestField *field,
974 								 const char *item, void *data);
975 
976 /**
977  * Adds an item to a list field.
978  *
979  * @param field The list field.
980  * @param item  The list item.
981  * @param icon_path The path to icon file, or @c NULL for no icon.
982  * @param data  The associated data.
983  */
984 void purple_request_field_list_add_icon(PurpleRequestField *field,
985 								 const char *item, const char* icon_path, void* data);
986 
987 /**
988  * Adds a selected item to the list field.
989  *
990  * @param field The field.
991  * @param item  The item to add.
992  */
993 void purple_request_field_list_add_selected(PurpleRequestField *field,
994 										  const char *item);
995 
996 /**
997  * Clears the list of selected items in a list field.
998  *
999  * @param field The field.
1000  */
1001 void purple_request_field_list_clear_selected(PurpleRequestField *field);
1002 
1003 /**
1004  * Sets a list of selected items in a list field.
1005  *
1006  * @param field The field.
1007  * @param items The list of selected items, which is not modified or freed.
1008  */
1009 void purple_request_field_list_set_selected(PurpleRequestField *field,
1010 										  GList *items);
1011 
1012 /**
1013  * Returns whether or not a particular item is selected in a list field.
1014  *
1015  * @param field The field.
1016  * @param item  The item.
1017  *
1018  * @return TRUE if the item is selected. FALSE otherwise.
1019  */
1020 gboolean purple_request_field_list_is_selected(const PurpleRequestField *field,
1021 											 const char *item);
1022 
1023 /**
1024  * Returns a list of selected items in a list field.
1025  *
1026  * To retrieve the data for each item, use
1027  * purple_request_field_list_get_data().
1028  *
1029  * @param field The field.
1030  *
1031  * @constreturn The list of selected items.
1032  */
1033 GList *purple_request_field_list_get_selected(
1034 	const PurpleRequestField *field);
1035 
1036 /**
1037  * Returns a list of items in a list field.
1038  *
1039  * @param field The field.
1040  *
1041  * @constreturn The list of items.
1042  */
1043 GList *purple_request_field_list_get_items(const PurpleRequestField *field);
1044 
1045 /**
1046  * Returns a list of icons in a list field.
1047  *
1048  * The icons will correspond with the items, in order.
1049  *
1050  * @param field The field.
1051  *
1052  * @constreturn The list of icons or @c NULL (i.e. the empty GList) if no
1053  *              items have icons.
1054  */
1055 GList *purple_request_field_list_get_icons(const PurpleRequestField *field);
1056 
1057 /*@}*/
1058 
1059 /**************************************************************************/
1060 /** @name Label Field API                                                 */
1061 /**************************************************************************/
1062 /*@{*/
1063 
1064 /**
1065  * Creates a label field.
1066  *
1067  * @param id   The field ID.
1068  * @param text The label of the field.
1069  *
1070  * @return The new field.
1071  */
1072 PurpleRequestField *purple_request_field_label_new(const char *id,
1073 											   const char *text);
1074 
1075 /*@}*/
1076 
1077 /**************************************************************************/
1078 /** @name Image Field API                                                 */
1079 /**************************************************************************/
1080 /*@{*/
1081 
1082 /**
1083  * Creates an image field.
1084  *
1085  * @param id   The field ID.
1086  * @param text The label of the field.
1087  * @param buf  The image data.
1088  * @param size The size of the data in @a buffer.
1089  *
1090  * @return The new field.
1091  */
1092 PurpleRequestField *purple_request_field_image_new(const char *id, const char *text,
1093 											   const char *buf, gsize size);
1094 
1095 /**
1096  * Sets the scale factors of an image field.
1097  *
1098  * @param field The image field.
1099  * @param x     The x scale factor.
1100  * @param y     The y scale factor.
1101  */
1102 void purple_request_field_image_set_scale(PurpleRequestField *field, unsigned int x, unsigned int y);
1103 
1104 /**
1105  * Returns pointer to the image.
1106  *
1107  * @param field The image field.
1108  *
1109  * @return Pointer to the image.
1110  */
1111 const char *purple_request_field_image_get_buffer(PurpleRequestField *field);
1112 
1113 /**
1114  * Returns size (in bytes) of the image.
1115  *
1116  * @param field The image field.
1117  *
1118  * @return Size of the image.
1119  */
1120 gsize purple_request_field_image_get_size(PurpleRequestField *field);
1121 
1122 /**
1123  * Returns X scale coefficient of the image.
1124  *
1125  * @param field The image field.
1126  *
1127  * @return X scale coefficient of the image.
1128  */
1129 unsigned int purple_request_field_image_get_scale_x(PurpleRequestField *field);
1130 
1131 /**
1132  * Returns Y scale coefficient of the image.
1133  *
1134  * @param field The image field.
1135  *
1136  * @return Y scale coefficient of the image.
1137  */
1138 unsigned int purple_request_field_image_get_scale_y(PurpleRequestField *field);
1139 
1140 /*@}*/
1141 
1142 /**************************************************************************/
1143 /** @name Account Field API                                               */
1144 /**************************************************************************/
1145 /*@{*/
1146 
1147 /**
1148  * Creates an account field.
1149  *
1150  * By default, this field will not show offline accounts.
1151  *
1152  * @param id      The field ID.
1153  * @param text    The text label of the field.
1154  * @param account The optional default account.
1155  *
1156  * @return The new field.
1157  */
1158 PurpleRequestField *purple_request_field_account_new(const char *id,
1159 												 const char *text,
1160 												 PurpleAccount *account);
1161 
1162 /**
1163  * Sets the default account on an account field.
1164  *
1165  * @param field         The account field.
1166  * @param default_value The default account.
1167  */
1168 void purple_request_field_account_set_default_value(PurpleRequestField *field,
1169 												  PurpleAccount *default_value);
1170 
1171 /**
1172  * Sets the account in an account field.
1173  *
1174  * @param field The account field.
1175  * @param value The account.
1176  */
1177 void purple_request_field_account_set_value(PurpleRequestField *field,
1178 										  PurpleAccount *value);
1179 
1180 /**
1181  * Sets whether or not to show all accounts in an account field.
1182  *
1183  * If TRUE, all accounts, online or offline, will be shown. If FALSE,
1184  * only online accounts will be shown.
1185  *
1186  * @param field    The account field.
1187  * @param show_all Whether or not to show all accounts.
1188  */
1189 void purple_request_field_account_set_show_all(PurpleRequestField *field,
1190 											 gboolean show_all);
1191 
1192 /**
1193  * Sets the account filter function in an account field.
1194  *
1195  * This function will determine which accounts get displayed and which
1196  * don't.
1197  *
1198  * @param field       The account field.
1199  * @param filter_func The account filter function.
1200  */
1201 void purple_request_field_account_set_filter(PurpleRequestField *field,
1202 										   PurpleFilterAccountFunc filter_func);
1203 
1204 /**
1205  * Returns the default account in an account field.
1206  *
1207  * @param field The field.
1208  *
1209  * @return The default account.
1210  */
1211 PurpleAccount *purple_request_field_account_get_default_value(
1212 		const PurpleRequestField *field);
1213 
1214 /**
1215  * Returns the user-entered account in an account field.
1216  *
1217  * @param field The field.
1218  *
1219  * @return The user-entered account.
1220  */
1221 PurpleAccount *purple_request_field_account_get_value(
1222 		const PurpleRequestField *field);
1223 
1224 /**
1225  * Returns whether or not to show all accounts in an account field.
1226  *
1227  * If TRUE, all accounts, online or offline, will be shown. If FALSE,
1228  * only online accounts will be shown.
1229  *
1230  * @param field    The account field.
1231  * @return Whether or not to show all accounts.
1232  */
1233 gboolean purple_request_field_account_get_show_all(
1234 		const PurpleRequestField *field);
1235 
1236 /**
1237  * Returns the account filter function in an account field.
1238  *
1239  * This function will determine which accounts get displayed and which
1240  * don't.
1241  *
1242  * @param field       The account field.
1243  *
1244  * @return The account filter function.
1245  */
1246 PurpleFilterAccountFunc purple_request_field_account_get_filter(
1247 		const PurpleRequestField *field);
1248 
1249 /*@}*/
1250 
1251 /**************************************************************************/
1252 /** @name Request API                                                     */
1253 /**************************************************************************/
1254 /*@{*/
1255 
1256 /**
1257  * Prompts the user for text input.
1258  *
1259  * @param handle        The plugin or connection handle.  For some
1260  *                      things this is <em>extremely</em> important.  The
1261  *                      handle is used to programmatically close the request
1262  *                      dialog when it is no longer needed.  For PRPLs this
1263  *                      is often a pointer to the #PurpleConnection
1264  *                      instance.  For plugins this should be a similar,
1265  *                      unique memory location.  This value is important
1266  *                      because it allows a request to be closed with
1267  *                      purple_request_close_with_handle() when, for
1268  *                      example, you sign offline.  If the request is
1269  *                      <em>not</em> closed it is <strong>very</strong>
1270  *                      likely to cause a crash whenever the callback
1271  *                      handler functions are triggered.
1272  * @param title         The title of the message, or @c NULL if it should have
1273  *                      no title.
1274  * @param primary       The main point of the message, or @c NULL if you're
1275  *                      feeling enigmatic.
1276  * @param secondary     Secondary information, or @c NULL if there is none.
1277  * @param default_value The default value.
1278  * @param multiline     @c TRUE if the inputted text can span multiple lines.
1279  * @param masked        @c TRUE if the inputted text should be masked in some
1280  *                      way (such as by displaying characters as stars).  This
1281  *                      might be because the input is some kind of password.
1282  * @param hint          Optionally suggest how the input box should appear.
1283  *                      Use "html", for example, to allow the user to enter
1284  *                      HTML.
1285  * @param ok_text       The text for the @c OK button, which may not be @c NULL.
1286  * @param ok_cb         The callback for the @c OK button, which may not be @c
1287  *                      NULL.
1288  * @param cancel_text   The text for the @c Cancel button, which may not be @c
1289  *                      NULL.
1290  * @param cancel_cb     The callback for the @c Cancel button, which may be
1291  *                      @c NULL.
1292  * @param account       The #PurpleAccount associated with this request, or @c
1293  *                      NULL if none is.
1294  * @param who           The username of the buddy associated with this request,
1295  *                      or @c NULL if none is.
1296  * @param conv          The #PurpleConversation associated with this request, or
1297  *                      @c NULL if none is.
1298  * @param user_data     The data to pass to the callback.
1299  *
1300  * @return A UI-specific handle.
1301  */
1302 void *purple_request_input(void *handle, const char *title, const char *primary,
1303 	const char *secondary, const char *default_value, gboolean multiline,
1304 	gboolean masked, gchar *hint,
1305 	const char *ok_text, GCallback ok_cb,
1306 	const char *cancel_text, GCallback cancel_cb,
1307 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1308 	void *user_data);
1309 
1310 /**
1311  * Prompts the user for multiple-choice input.
1312  *
1313  * @param handle        The plugin or connection handle.  For some things this
1314  *                      is <em>extremely</em> important.  See the comments on
1315  *                      purple_request_input().
1316  * @param title         The title of the message, or @c NULL if it should have
1317  *                      no title.
1318  * @param primary       The main point of the message, or @c NULL if you're
1319  *                      feeling enigmatic.
1320  * @param secondary     Secondary information, or @c NULL if there is none.
1321  * @param default_value The default choice; this should be one of the values
1322  *                      listed in the varargs.
1323  * @param ok_text       The text for the @c OK button, which may not be @c NULL.
1324  * @param ok_cb         The callback for the @c OK button, which may not be @c
1325  *                      NULL.
1326  * @param cancel_text   The text for the @c Cancel button, which may not be @c
1327  *                      NULL.
1328  * @param cancel_cb     The callback for the @c Cancel button, or @c NULL to
1329  *                      do nothing.
1330  * @param account       The #PurpleAccount associated with this request, or @c
1331  *                      NULL if none is.
1332  * @param who           The username of the buddy associated with this request,
1333  *                      or @c NULL if none is.
1334  * @param conv          The #PurpleConversation associated with this request, or
1335  *                      @c NULL if none is.
1336  * @param user_data     The data to pass to the callback.
1337  * @param ...           The choices, which should be pairs of <tt>char *</tt>
1338  *                      descriptions and <tt>int</tt> values, terminated with a
1339  *                      @c NULL parameter.
1340  *
1341  * @return A UI-specific handle.
1342  */
1343 void *purple_request_choice(void *handle, const char *title, const char *primary,
1344 	const char *secondary, int default_value,
1345 	const char *ok_text, GCallback ok_cb,
1346 	const char *cancel_text, GCallback cancel_cb,
1347 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1348 	void *user_data, ...) G_GNUC_NULL_TERMINATED;
1349 
1350 /**
1351  * <tt>va_list</tt> version of purple_request_choice(); see its documentation.
1352  */
1353 void *purple_request_choice_varg(void *handle, const char *title,
1354 	const char *primary, const char *secondary, int default_value,
1355 	const char *ok_text, GCallback ok_cb,
1356 	const char *cancel_text, GCallback cancel_cb,
1357 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1358 	void *user_data, va_list choices);
1359 
1360 /**
1361  * Prompts the user for an action.
1362  *
1363  * This is often represented as a dialog with a button for each action.
1364  *
1365  * @param handle         The plugin or connection handle.  For some things this
1366  *                       is <em>extremely</em> important.  See the comments on
1367  *                       purple_request_input().
1368  * @param title          The title of the message, or @c NULL if it should have
1369  *                       no title.
1370  * @param primary        The main point of the message, or @c NULL if you're
1371  *                       feeling enigmatic.
1372  * @param secondary      Secondary information, or @c NULL if there is none.
1373  * @param default_action The default action, zero-indexed; if the third action
1374  *                       supplied should be the default, supply <tt>2</tt>.
1375  *                       The should be the action that users are most likely
1376  *                       to select.
1377  * @param account        The #PurpleAccount associated with this request, or @c
1378  *                       NULL if none is.
1379  * @param who            The username of the buddy associated with this request,
1380  *                       or @c NULL if none is.
1381  * @param conv           The #PurpleConversation associated with this request, or
1382  *                       @c NULL if none is.
1383  * @param user_data      The data to pass to the callback.
1384  * @param action_count   The number of actions.
1385  * @param ...            A list of actions.  These are pairs of
1386  *                       arguments.  The first of each pair is the
1387  *                       <tt>char *</tt> label that appears on the button.  It
1388  *                       should have an underscore before the letter you want
1389  *                       to use as the accelerator key for the button.  The
1390  *                       second of each pair is the #PurpleRequestActionCb
1391  *                       function to use when the button is clicked.
1392  *
1393  * @return A UI-specific handle.
1394  */
1395 void *purple_request_action(void *handle, const char *title, const char *primary,
1396 	const char *secondary, int default_action, PurpleAccount *account,
1397 	const char *who, PurpleConversation *conv, void *user_data,
1398 	size_t action_count, ...);
1399 
1400 /**
1401  * <tt>va_list</tt> version of purple_request_action(); see its documentation.
1402  */
1403 void *purple_request_action_varg(void *handle, const char *title,
1404 	const char *primary, const char *secondary, int default_action,
1405 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1406 	void *user_data, size_t action_count, va_list actions);
1407 
1408 /**
1409  * Version of purple_request_action() supplying an image for the UI to
1410  * optionally display as an icon in the dialog; see its documentation
1411  * @since 2.7.0
1412  */
1413 void *purple_request_action_with_icon(void *handle, const char *title,
1414 	const char *primary, const char *secondary, int default_action,
1415 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1416 	gconstpointer icon_data, gsize icon_size, void *user_data,
1417 	size_t action_count, ...);
1418 
1419 /**
1420  * <tt>va_list</tt> version of purple_request_action_with_icon();
1421  * see its documentation.
1422  * @since 2.7.0
1423  */
1424 void *purple_request_action_with_icon_varg(void *handle, const char *title,
1425 	const char *primary, const char *secondary, int default_action,
1426 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1427 	gconstpointer icon_data, gsize icon_size,
1428 	void *user_data, size_t action_count, va_list actions);
1429 
1430 
1431 /**
1432  * Displays groups of fields for the user to fill in.
1433  *
1434  * @param handle      The plugin or connection handle.  For some things this
1435  *                    is <em>extremely</em> important.  See the comments on
1436  *                    purple_request_input().
1437  * @param title       The title of the message, or @c NULL if it should have
1438  *                    no title.
1439  * @param primary     The main point of the message, or @c NULL if you're
1440  *                    feeling enigmatic.
1441  * @param secondary   Secondary information, or @c NULL if there is none.
1442  * @param fields      The list of fields.
1443  * @param ok_text     The text for the @c OK button, which may not be @c NULL.
1444  * @param ok_cb       The callback for the @c OK button, which may not be @c
1445  *                    NULL.
1446  * @param cancel_text The text for the @c Cancel button, which may not be @c
1447  *                    NULL.
1448  * @param cancel_cb   The callback for the @c Cancel button, which may be
1449  *                    @c NULL.
1450  * @param account     The #PurpleAccount associated with this request, or @c
1451  *                    NULL if none is
1452  * @param who         The username of the buddy associated with this request,
1453  *                    or @c NULL if none is
1454  * @param conv        The #PurpleConversation associated with this request, or
1455  *                    @c NULL if none is
1456  * @param user_data   The data to pass to the callback.
1457  *
1458  * @return A UI-specific handle.
1459  */
1460 void *purple_request_fields(void *handle, const char *title, const char *primary,
1461 	const char *secondary, PurpleRequestFields *fields,
1462 	const char *ok_text, GCallback ok_cb,
1463 	const char *cancel_text, GCallback cancel_cb,
1464 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1465 	void *user_data);
1466 
1467 /**
1468  * Closes a request.
1469  *
1470  * @param type     The request type.
1471  * @param uihandle The request UI handle.
1472  */
1473 void purple_request_close(PurpleRequestType type, void *uihandle);
1474 
1475 /**
1476  * Closes all requests registered with the specified handle.
1477  *
1478  * @param handle The handle, as supplied as the @a handle parameter to one of the
1479  *               <tt>purple_request_*</tt> functions.
1480  *
1481  * @see purple_request_input().
1482  */
1483 void purple_request_close_with_handle(void *handle);
1484 
1485 /**
1486  * A wrapper for purple_request_action() that uses @c Yes and @c No buttons.
1487  */
1488 #define purple_request_yes_no(handle, title, primary, secondary, \
1489 							default_action, account, who, conv, \
1490 							user_data, yes_cb, no_cb) \
1491 	purple_request_action((handle), (title), (primary), (secondary), \
1492 						(default_action), account, who, conv, (user_data), 2, \
1493 						_("_Yes"), (yes_cb), _("_No"), (no_cb))
1494 
1495 /**
1496  * A wrapper for purple_request_action() that uses @c OK and @c Cancel buttons.
1497  */
1498 #define purple_request_ok_cancel(handle, title, primary, secondary, \
1499 							default_action, account, who, conv, \
1500 						    user_data, ok_cb, cancel_cb) \
1501 	purple_request_action((handle), (title), (primary), (secondary), \
1502 						(default_action), account, who, conv, (user_data), 2, \
1503 						_("_OK"), (ok_cb), _("_Cancel"), (cancel_cb))
1504 
1505 /**
1506  * A wrapper for purple_request_action() that uses Accept and Cancel buttons.
1507  */
1508 #define purple_request_accept_cancel(handle, title, primary, secondary, \
1509 								   default_action, account, who, conv, \
1510 								   user_data, accept_cb, cancel_cb) \
1511 	purple_request_action((handle), (title), (primary), (secondary), \
1512 						(default_action), account, who, conv, (user_data), 2, \
1513 						_("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
1514 
1515 /**
1516  * A wrapper for purple_request_action_with_icon() that uses Accept and Cancel
1517  * buttons.
1518  */
1519 #define purple_request_accept_cancel_with_icon(handle, title, primary, secondary, \
1520 								   default_action, account, who, conv, \
1521 								   icon_data, icon_size, \
1522 								   user_data, accept_cb, cancel_cb) \
1523 	purple_request_action_with_icon((handle), (title), (primary), (secondary), \
1524 						(default_action), account, who, conv, icon_data, icon_size, \
1525 						(user_data), 2, \
1526 						_("_Accept"), (accept_cb), _("_Cancel"), (cancel_cb))
1527 
1528 /**
1529  * Displays a file selector request dialog.  Returns the selected filename to
1530  * the callback.  Can be used for either opening a file or saving a file.
1531  *
1532  * @param handle      The plugin or connection handle.  For some things this
1533  *                    is <em>extremely</em> important.  See the comments on
1534  *                    purple_request_input().
1535  * @param title       The title of the message, or @c NULL if it should have
1536  *                    no title.
1537  * @param filename    The default filename (may be @c NULL)
1538  * @param savedialog  True if this dialog is being used to save a file.
1539  *                    False if it is being used to open a file.
1540  * @param ok_cb       The callback for the @c OK button.
1541  * @param cancel_cb   The callback for the @c Cancel button, which may be @c NULL.
1542  * @param account     The #PurpleAccount associated with this request, or @c
1543  *                    NULL if none is
1544  * @param who         The username of the buddy associated with this request,
1545  *                    or @c NULL if none is
1546  * @param conv        The #PurpleConversation associated with this request, or
1547  *                    @c NULL if none is
1548  * @param user_data   The data to pass to the callback.
1549  *
1550  * @return A UI-specific handle.
1551  */
1552 void *purple_request_file(void *handle, const char *title, const char *filename,
1553 	gboolean savedialog, GCallback ok_cb, GCallback cancel_cb,
1554 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1555 	void *user_data);
1556 
1557 /**
1558  * Displays a folder select dialog. Returns the selected filename to
1559  * the callback.
1560  *
1561  * @param handle      The plugin or connection handle.  For some things this
1562  *                    is <em>extremely</em> important.  See the comments on
1563  *                    purple_request_input().
1564  * @param title       The title of the message, or @c NULL if it should have
1565  *                    no title.
1566  * @param dirname     The default directory name (may be @c NULL)
1567  * @param ok_cb       The callback for the @c OK button.
1568  * @param cancel_cb   The callback for the @c Cancel button, which may be @c NULL.
1569  * @param account     The #PurpleAccount associated with this request, or @c
1570  *                    NULL if none is
1571  * @param who         The username of the buddy associated with this request,
1572  *                    or @c NULL if none is
1573  * @param conv        The #PurpleConversation associated with this request, or
1574  *                    @c NULL if none is
1575  * @param user_data   The data to pass to the callback.
1576  *
1577  * @return A UI-specific handle.
1578  */
1579 void *purple_request_folder(void *handle, const char *title, const char *dirname,
1580 	GCallback ok_cb, GCallback cancel_cb,
1581 	PurpleAccount *account, const char *who, PurpleConversation *conv,
1582 	void *user_data);
1583 
1584 
1585 /**
1586  * Displays a dialog allowing the user to select a window/monitor etc. for
1587  * screen sharing. Returns a #PurpleMediaElementInfo to the callback or @c
1588  * NULL if the request is cancelled.
1589  *
1590  * @param handle      The plugin or connection handle.  For some things this
1591  *                    is <em>extremely</em> important.  See the comments on
1592  *                    purple_request_input().
1593  * @param title       The title of the message, or @c NULL if it should have
1594  *                    no title.
1595  * @param primary     The main point of the message, or @c NULL if you're
1596  *                    feeling enigmatic.
1597  * @param secondary   Secondary information, or @c NULL if there is none.
1598  * @param cb          The callback for the @c OK button.
1599  * @param user_data   The data to pass to the callback.
1600  *
1601  * @return A UI-specific handle.
1602  */
1603 void *purple_request_screenshare_media(void *handle, const char *title,
1604 				       const char *primary, const char *secondary,
1605 				       PurpleAccount *account, GCallback cb,
1606 				       void *user_data);
1607 
1608 /*@}*/
1609 
1610 /**************************************************************************/
1611 /** @name UI Registration Functions                                       */
1612 /**************************************************************************/
1613 /*@{*/
1614 
1615 /**
1616  * Sets the UI operations structure to be used when displaying a
1617  * request.
1618  *
1619  * @param ops The UI operations structure.
1620  */
1621 void purple_request_set_ui_ops(PurpleRequestUiOps *ops);
1622 
1623 /**
1624  * Returns the UI operations structure to be used when displaying a
1625  * request.
1626  *
1627  * @return The UI operations structure.
1628  */
1629 PurpleRequestUiOps *purple_request_get_ui_ops(void);
1630 
1631 /*@}*/
1632 
1633 #ifdef __cplusplus
1634 }
1635 #endif
1636 
1637 #endif /* _PURPLE_REQUEST_H_ */
1638