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