libpurple/request.h

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