libpurple/notify.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_NOTIFY_H
  23 #define PURPLE_NOTIFY_H
  24 /**
  25  * SECTION:notify
  26  * @section_id: libpurple-notify
  27  * @short_description: <filename>notify.h</filename>
  28  * @title: Notification API
  29  * @see_also: <link linkend="chapter-signals-notify">Notify signals</link>
  30  */
  31
  32 #include <stdlib.h>
  33 #include <glib-object.h>
  34 #include <glib.h>
  35
  36 typedef struct _PurpleNotifyUserInfoEntry       PurpleNotifyUserInfoEntry;
  37
  38 #define  PURPLE_TYPE_NOTIFY_USER_INFO  (purple_notify_user_info_get_type())
  39 typedef struct _PurpleNotifyUserInfo            PurpleNotifyUserInfo;
  40
  41 #define PURPLE_TYPE_NOTIFY_SEARCH_BUTTON  (purple_notify_search_button_get_type())
  42 typedef struct _PurpleNotifySearchButton        PurpleNotifySearchButton;
  43
  44 /**
  45  * PurpleNotifySearchColumn:
  46  *
  47  * Single column of a search result.
  48  */
  49 typedef struct _PurpleNotifySearchColumn        PurpleNotifySearchColumn;
  50
  51 #include "connection.h"
  52 #include "request.h"
  53
  54 typedef struct _PurpleNotifySearchResults PurpleNotifySearchResults;
  55
  56 #define PURPLE_TYPE_NOTIFY_UI_OPS  (purple_notify_ui_ops_get_type())
  57 typedef struct _PurpleNotifyUiOps       PurpleNotifyUiOps;
  58
  59 /**
  60  * PurpleNotifyCloseCallback:
  61  *
  62  * Notification close callbacks.
  63  */
  64 typedef void  (*PurpleNotifyCloseCallback) (gpointer user_data);
  65
  66
  67 /**
  68  * PurpleNotifyType:
  69  * @PURPLE_NOTIFY_MESSAGE:       Message notification.
  70  * @PURPLE_NOTIFY_EMAIL:         Single email notification.
  71  * @PURPLE_NOTIFY_EMAILS:        Multiple email notification.
  72  * @PURPLE_NOTIFY_FORMATTED:     Formatted text.
  73  * @PURPLE_NOTIFY_SEARCHRESULTS: Buddy search results.
  74  * @PURPLE_NOTIFY_USERINFO:      Formatted userinfo text.
  75  * @PURPLE_NOTIFY_URI:           URI notification or display.
  76  *
  77  * Notification types.
  78  */
  79 typedef enum
  80 {
  81         PURPLE_NOTIFY_MESSAGE = 0,
  82         PURPLE_NOTIFY_EMAIL,
  83         PURPLE_NOTIFY_EMAILS,
  84         PURPLE_NOTIFY_FORMATTED,
  85         PURPLE_NOTIFY_SEARCHRESULTS,
  86         PURPLE_NOTIFY_USERINFO,
  87         PURPLE_NOTIFY_URI
  88
  89 } PurpleNotifyType;
  90
  91
  92 /**
  93  * PurpleNotifyMessageType:
  94  * @PURPLE_NOTIFY_MSG_ERROR:   Error notification.
  95  * @PURPLE_NOTIFY_MSG_WARNING: Warning notification.
  96  * @PURPLE_NOTIFY_MSG_INFO:    Information notification.
  97  *
  98  * Notification message types.
  99  */
 100 typedef enum
 101 {
 102         PURPLE_NOTIFY_MSG_ERROR = 0,
 103         PURPLE_NOTIFY_MSG_WARNING,
 104         PURPLE_NOTIFY_MSG_INFO
 105
 106 } PurpleNotifyMessageType;
 107
 108
 109 /**
 110  * PurpleNotifySearchButtonType:
 111  * @PURPLE_NOTIFY_BUTTON_LABELED: special use, see
 112  *               purple_notify_searchresults_button_add_labeled()
 113  *
 114  * The types of buttons
 115  */
 116 typedef enum
 117 {
 118         PURPLE_NOTIFY_BUTTON_LABELED  = 0,
 119         PURPLE_NOTIFY_BUTTON_CONTINUE = 1,
 120         PURPLE_NOTIFY_BUTTON_ADD,
 121         PURPLE_NOTIFY_BUTTON_INFO,
 122         PURPLE_NOTIFY_BUTTON_IM,
 123         PURPLE_NOTIFY_BUTTON_JOIN,
 124         PURPLE_NOTIFY_BUTTON_INVITE
 125 } PurpleNotifySearchButtonType;
 126
 127
 128 /**
 129  * PurpleNotifySearchResults:
 130  * @columns: List of the search column objects.
 131  * @rows:    List of rows in the result.
 132  * @buttons: List of buttons to display.
 133  *
 134  * Search results object.
 135  */
 136 struct _PurpleNotifySearchResults
 137 {
 138         GList *columns;
 139         GList *rows;
 140         GList *buttons;
 141
 142 };
 143
 144 /**
 145  * PurpleNotifyUserInfoEntryType:
 146  *
 147  * Types of PurpleNotifyUserInfoEntry objects
 148  */
 149 typedef enum
 150 {
 151         PURPLE_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
 152         PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
 153         PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
 154 } PurpleNotifyUserInfoEntryType;
 155
 156
 157
 158 /**
 159  * PurpleNotifySearchResultsCallback:
 160  * @c:         the PurpleConnection passed to purple_notify_searchresults
 161  * @row:       the contents of the selected row
 162  * @user_data: User defined data.
 163  *
 164  * Callback for a button in a search result.
 165  */
 166 typedef void (*PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row,
 167                                                                                                 gpointer user_data);
 168
 169
 170 /**
 171  * PurpleNotifySearchButton:
 172  * @type:     The type of search button that will be used.
 173  * @callback: Function to be called when clicked.
 174  * @label:    only for PURPLE_NOTIFY_BUTTON_LABELED
 175  *
 176  * Definition of a button.
 177  */
 178 struct _PurpleNotifySearchButton
 179 {
 180         PurpleNotifySearchButtonType type;
 181         PurpleNotifySearchResultsCallback callback;
 182         char *label;
 183 };
 184
 185
 186 /**
 187  * PurpleNotifyUiOps:
 188  *
 189  * Notification UI operations.
 190  */
 191 struct _PurpleNotifyUiOps
 192 {
 193         void *(*notify_message)(PurpleNotifyMessageType type, const char *title,
 194                 const char *primary, const char *secondary,
 195                 PurpleRequestCommonParameters *cpar);
 196
 197         void *(*notify_email)(PurpleConnection *gc,
 198                               const char *subject, const char *from,
 199                               const char *to, const char *url);
 200
 201         void *(*notify_emails)(PurpleConnection *gc,
 202                                size_t count, gboolean detailed,
 203                                const char **subjects, const char **froms,
 204                                const char **tos, const char **urls);
 205
 206         void *(*notify_formatted)(const char *title, const char *primary,
 207                                   const char *secondary, const char *text);
 208
 209         void *(*notify_searchresults)(PurpleConnection *gc, const char *title,
 210                                       const char *primary, const char *secondary,
 211                                       PurpleNotifySearchResults *results, gpointer user_data);
 212
 213         void (*notify_searchresults_new_rows)(PurpleConnection *gc,
 214                                               PurpleNotifySearchResults *results,
 215                                               void *data);
 216
 217         void *(*notify_userinfo)(PurpleConnection *gc, const char *who,
 218                                  PurpleNotifyUserInfo *user_info);
 219
 220         void *(*notify_uri)(const char *uri);
 221
 222         void (*close_notify)(PurpleNotifyType type, void *ui_handle);
 223
 224         /*< private >*/
 225         void (*_purple_reserved1)(void);
 226         void (*_purple_reserved2)(void);
 227         void (*_purple_reserved3)(void);
 228         void (*_purple_reserved4)(void);
 229 };
 230
 231
 232 G_BEGIN_DECLS
 233
 234
 235 /**************************************************************************/
 236 /* Search results notification API                                        */
 237 /**************************************************************************/
 238
 239 /**
 240  * purple_notify_searchresults:
 241  * @gc:        The PurpleConnection handle associated with the information.
 242  * @title:     The title of the message.  If this is NULL, the title
 243  *             will be "Search Results."
 244  * @primary:   The main point of the message.
 245  * @secondary: The secondary information.
 246  * @results:   The PurpleNotifySearchResults instance.
 247  * @cb:        (scope call): The callback to call when the user closes
 248  *             the notification.
 249  * @user_data: The data to pass to the close callback and any other
 250  *             callback associated with a button.
 251  *
 252  * Displays results from a buddy search.  This can be, for example,
 253  * a window with a list of all found buddies, where you are given the
 254  * option of adding buddies to your buddy list.
 255  *
 256  * Returns: A UI-specific handle.
 257  */
 258 void *purple_notify_searchresults(PurpleConnection *gc, const char *title,
 259                                                                 const char *primary, const char *secondary,
 260                                                                 PurpleNotifySearchResults *results, PurpleNotifyCloseCallback cb,
 261                                                                 gpointer user_data);
 262
 263 /**
 264  * purple_notify_searchresults_free:
 265  * @results: The PurpleNotifySearchResults to free.
 266  *
 267  * Frees a PurpleNotifySearchResults object.
 268  */
 269 void purple_notify_searchresults_free(PurpleNotifySearchResults *results);
 270
 271 /**
 272  * purple_notify_searchresults_new_rows:
 273  * @gc:        The PurpleConnection structure.
 274  * @results:   The PurpleNotifySearchResults structure.
 275  * @data:      Data returned by the purple_notify_searchresults().
 276  *
 277  * Replace old rows with the new. Reuse an existing window.
 278  */
 279 void purple_notify_searchresults_new_rows(PurpleConnection *gc,
 280                                                                                 PurpleNotifySearchResults *results,
 281                                                                                 void *data);
 282
 283
 284 /**
 285  * purple_notify_searchresults_button_add:
 286  * @results: The search results object.
 287  * @type:    Type of the button. (TODO: Only one button of a given type
 288  *           can be displayed.)
 289  * @cb:      (scope call): Function that will be called on the click event.
 290  *
 291  * Adds a stock button that will be displayed in the search results dialog.
 292  */
 293 void purple_notify_searchresults_button_add(PurpleNotifySearchResults *results,
 294                                                                                   PurpleNotifySearchButtonType type,
 295                                                                                   PurpleNotifySearchResultsCallback cb);
 296
 297
 298 /**
 299  * purple_notify_searchresults_button_add_labeled:
 300  * @results: The search results object
 301  * @label:   The label to display
 302  * @cb:      (scope call): Function that will be called on the click event
 303  *
 304  * Adds a plain labelled button that will be displayed in the search results
 305  * dialog.
 306  */
 307 void purple_notify_searchresults_button_add_labeled(PurpleNotifySearchResults *results,
 308                                                   const char *label,
 309                                                   PurpleNotifySearchResultsCallback cb);
 310
 311
 312 /**
 313  * purple_notify_searchresults_new:
 314  *
 315  * Returns a newly created search results object.
 316  *
 317  * Returns: The new search results object.
 318  */
 319 PurpleNotifySearchResults *purple_notify_searchresults_new(void);
 320
 321 /**
 322  * purple_notify_searchresults_column_new:
 323  * @title: Title of the column. NOTE: Title will get g_strdup()ed.
 324  *
 325  * Returns a newly created search result column object.  The column defaults
 326  * to being visible.
 327  *
 328  * Returns: The new search column object.
 329  */
 330 PurpleNotifySearchColumn *purple_notify_searchresults_column_new(const char *title);
 331
 332 /**
 333  * purple_notify_searchresult_column_get_title:
 334  * @column: The search column object.
 335  *
 336  * Returns the title of the column
 337  *
 338  * Returns: The title of the column
 339  */
 340 const char *purple_notify_searchresult_column_get_title(const PurpleNotifySearchColumn *column);
 341
 342 /**
 343  * purple_notify_searchresult_column_set_visible:
 344  * @column:  The search column object.
 345  * @visible: TRUE if visible, or FALSE if not.
 346  *
 347  * Sets whether or not a search result column is visible.
 348  */
 349 void purple_notify_searchresult_column_set_visible(PurpleNotifySearchColumn *column, gboolean visible);
 350
 351 /**
 352  * purple_notify_searchresult_column_is_visible:
 353  * @column: The search column object.
 354  *
 355  * Returns whether or not a search result column is visible.
 356  *
 357  * Returns: TRUE if the search result column is visible. FALSE otherwise.
 358  */
 359 gboolean purple_notify_searchresult_column_is_visible(const PurpleNotifySearchColumn *column);
 360
 361 /**
 362  * purple_notify_searchresults_column_add:
 363  * @results: The result object to which the column will be added.
 364  * @column: The column that will be added to the result object.
 365  *
 366  * Adds a new column to the search result object.
 367  */
 368 void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results,
 369                                                                                   PurpleNotifySearchColumn *column);
 370
 371 /**
 372  * purple_notify_searchresults_row_add:
 373  * @results: The search results object.
 374  * @row: (element-type utf8) (transfer full): The row of the results.
 375  *
 376  * Adds a new row of the results to the search results object.
 377  */
 378 void purple_notify_searchresults_row_add(PurpleNotifySearchResults *results,
 379                                                                            GList *row);
 380
 381 /**************************************************************************/
 382 /* Notification API                                                       */
 383 /**************************************************************************/
 384
 385 /**
 386  * purple_notify_message:
 387  * @handle:    The plugin or connection handle.
 388  * @type:      The notification type.
 389  * @title:     The title of the message.
 390  * @primary:   The main point of the message.
 391  * @secondary: The secondary information.
 392  * @cpar:      The #PurpleRequestCommonParameters associated with this
 393  *             request, or %NULL if none is.
 394  * @cb:        (scope call): The callback to call when the user closes
 395  *             the notification.
 396  * @user_data: The data to pass to the callback.
 397  *
 398  * Displays a notification message to the user.
 399  *
 400  * Returns: A UI-specific handle.
 401  */
 402 void *purple_notify_message(void *handle, PurpleNotifyMessageType type,
 403         const char *title, const char *primary, const char *secondary,
 404         PurpleRequestCommonParameters *cpar, PurpleNotifyCloseCallback cb,
 405         gpointer user_data);
 406
 407 /**
 408  * purple_notify_email:
 409  * @handle:    The plugin or connection handle.
 410  * @subject:   The subject of the email.
 411  * @from:      The from address.
 412  * @to:        The destination address.
 413  * @url:       The URL where the message can be read.
 414  * @cb:        (scope call): The callback to call when the user closes
 415  *             the notification.
 416  * @user_data: The data to pass to the callback.
 417  *
 418  * Displays a single email notification to the user.
 419  *
 420  * Returns: A UI-specific handle.
 421  */
 422 void *purple_notify_email(void *handle, const char *subject,
 423                                                 const char *from, const char *to,
 424                                                 const char *url, PurpleNotifyCloseCallback cb,
 425                                                 gpointer user_data);
 426
 427 /**
 428  * purple_notify_emails:
 429  * @handle:    The plugin or connection handle.
 430  * @count:     The number of emails.  '0' can be used to signify that
 431  *             the user has no unread emails and the UI should remove
 432  *             the mail notification.
 433  * @detailed:  %TRUE if there is information for each email in the
 434  *             arrays.
 435  * @subjects:  The array of subjects.
 436  * @froms:     The array of from addresses.
 437  * @tos:       The array of destination addresses.
 438  * @urls:      The URLs where the messages can be read.
 439  * @cb:        (scope call): The callback to call when the user closes
 440  *             the notification.
 441  * @user_data: The data to pass to the callback.
 442  *
 443  * Displays a notification for multiple emails to the user.
 444  *
 445  * Returns: A UI-specific handle.
 446  */
 447 void *purple_notify_emails(void *handle, size_t count, gboolean detailed,
 448                                                  const char **subjects, const char **froms,
 449                                                  const char **tos, const char **urls,
 450                                                  PurpleNotifyCloseCallback cb, gpointer user_data);
 451
 452 /**
 453  * purple_notify_formatted:
 454  * @handle:    The plugin or connection handle.
 455  * @title:     The title of the message.
 456  * @primary:   The main point of the message.
 457  * @secondary: The secondary information.
 458  * @text:      The formatted text.
 459  * @cb:        (scope call): The callback to call when the user closes
 460  *             the notification.
 461  * @user_data: The data to pass to the callback.
 462  *
 463  * Displays a notification with formatted text.
 464  *
 465  * The text is essentially a stripped-down format of HTML, the same that
 466  * IMs may send.
 467  *
 468  * Returns: A UI-specific handle.
 469  */
 470 void *purple_notify_formatted(void *handle, const char *title,
 471                                                         const char *primary, const char *secondary,
 472                                                         const char *text, PurpleNotifyCloseCallback cb, gpointer user_data);
 473
 474 /**
 475  * purple_notify_userinfo:
 476  * @gc:         The PurpleConnection handle associated with the information.
 477  * @who:        The username associated with the information.
 478  * @user_info:  The PurpleNotifyUserInfo which contains the information
 479  * @cb:         (scope call): The callback to call when the user closes the
 480  *              notification.
 481  * @user_data:  The data to pass to the callback.
 482  *
 483  * Displays user information with formatted text, passing information giving
 484  * the connection and username from which the user information came.
 485  *
 486  * The text is essentially a stripped-down format of HTML, the same that
 487  * IMs may send.
 488  *
 489  * Returns:  A UI-specific handle.
 490  */
 491 void *purple_notify_userinfo(PurpleConnection *gc, const char *who,
 492                                                    PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb,
 493                                                    gpointer user_data);
 494
 495 /**
 496  * purple_notify_search_button_get_type:
 497  *
 498  * Returns: The #GType for #PurpleNotifiySearchButton boxed structure.
 499  */
 500 GType purple_notify_search_button_get_type(void);
 501
 502 /**
 503  * purple_notify_user_info_get_type:
 504  *
 505  * Returns: The #GType for the #PurpleNotifyUserInfo boxed structure.
 506  */
 507 GType purple_notify_user_info_get_type(void);
 508
 509 /**
 510  * purple_notify_user_info_new:
 511  *
 512  * Create a new PurpleNotifyUserInfo which is suitable for passing to
 513  * purple_notify_userinfo()
 514  *
 515  * Returns:  A new PurpleNotifyUserInfo, which the caller must destroy when done
 516  */
 517 PurpleNotifyUserInfo *purple_notify_user_info_new(void);
 518
 519 /**
 520  * purple_notify_user_info_destroy:
 521  * @user_info:  The PurpleNotifyUserInfo
 522  *
 523  * Destroy a PurpleNotifyUserInfo
 524  */
 525 void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info);
 526
 527 /**
 528  * purple_notify_user_info_get_entries:
 529  * @user_info:  The PurpleNotifyUserInfo
 530  *
 531  * Retrieve the array of PurpleNotifyUserInfoEntry objects from a
 532  * PurpleNotifyUserInfo
 533  *
 534  * This GQueue may be manipulated directly with normal GQueue functions such
 535  * as g_queue_push_tail(). Only PurpleNotifyUserInfoEntry are allowed in the
 536  * queue.  If a PurpleNotifyUserInfoEntry item is added to the queue, it
 537  * should not be freed by the caller; PurpleNotifyUserInfo will free it when
 538  * destroyed.
 539  *
 540  * To remove a PurpleNotifyUserInfoEntry, use
 541  * purple_notify_user_info_remove_entry(). Do not use the GQueue directly.
 542  *
 543  * Returns: (transfer none): A GQueue of PurpleNotifyUserInfoEntry objects.
 544  */
 545 GQueue *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info);
 546
 547 /**
 548  * purple_notify_user_info_get_text_with_newline:
 549  * @user_info:  The PurpleNotifyUserInfo
 550  * @newline:    The separation character
 551  *
 552  * Create a textual representation of a PurpleNotifyUserInfo, separating
 553  * entries with newline
 554  */
 555 char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline);
 556
 557 /**
 558  * purple_notify_user_info_add_pair_html:
 559  * @user_info:  The PurpleNotifyUserInfo
 560  * @label:      A label, which for example might be displayed by a
 561  *                   UI with a colon after it ("Status:"). Do not include
 562  *                   a colon.  If NULL, value will be displayed without a
 563  *                   label.
 564  * @value:      The value, which might be displayed by a UI after
 565  *                   the label.  This should be valid HTML.  If you want
 566  *                   to insert plaintext then use
 567  *                   purple_notify_user_info_add_pair_plaintext(), instead.
 568  *                   If this is NULL the label will still be displayed;
 569  *                   the UI should treat label as independent and not
 570  *                   include a colon if it would otherwise.
 571  *
 572  * Add a label/value pair to a PurpleNotifyUserInfo object.
 573  * PurpleNotifyUserInfo keeps track of the order in which pairs are added.
 574  */
 575 void purple_notify_user_info_add_pair_html(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
 576
 577 /**
 578  * purple_notify_user_info_add_pair_plaintext:
 579  *
 580  * Like purple_notify_user_info_add_pair_html, but value should be plaintext
 581  * and will be escaped using g_markup_escape_text().
 582  */
 583 void purple_notify_user_info_add_pair_plaintext(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
 584
 585 /**
 586  * purple_notify_user_info_prepend_pair_html:
 587  *
 588  * Like purple_notify_user_info_add_pair_html, but the pair is inserted
 589  * at the beginning of the list.
 590  */
 591 void purple_notify_user_info_prepend_pair_html(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
 592
 593 /**
 594  * purple_notify_user_info_prepend_pair_plaintext:
 595  *
 596  * Like purple_notify_user_info_prepend_pair_html, but value should be plaintext
 597  * and will be escaped using g_markup_escape_text().
 598  */
 599 void purple_notify_user_info_prepend_pair_plaintext(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
 600
 601 /**
 602  * purple_notify_user_info_remove_entry:
 603  * @user_info:        The PurpleNotifyUserInfo
 604  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 605  *
 606  * Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object
 607  * without freeing the entry.
 608  */
 609 void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry);
 610
 611 /**
 612  * purple_notify_user_info_entry_new:
 613  * @label:  A label, which for example might be displayed by a UI
 614  *               with a colon after it ("Status:"). Do not include a
 615  *               colon.  If NULL, value will be displayed without a label.
 616  * @value:  The value, which might be displayed by a UI after the
 617  *               label.  If NULL, label will still be displayed; the UI
 618  *               should then treat label as independent and not include a
 619  *               colon if it would otherwise.
 620  *
 621  * Create a new PurpleNotifyUserInfoEntry
 622  *
 623  * If added to a PurpleNotifyUserInfo object, this should not be free()'d,
 624  * as PurpleNotifyUserInfo will do so when destroyed.
 625  * purple_notify_user_info_add_pair_html(),
 626  * purple_notify_user_info_add_pair_plaintext(),
 627  * purple_notify_user_info_prepend_pair_html() and
 628  * purple_notify_user_info_prepend_pair_plaintext() are convenience
 629  * methods for creating entries and adding them to a PurpleNotifyUserInfo.
 630  *
 631  * Returns: A new PurpleNotifyUserInfoEntry
 632  */
 633 PurpleNotifyUserInfoEntry *purple_notify_user_info_entry_new(const char *label, const char *value);
 634
 635 /**
 636  * purple_notify_user_info_entry_destroy:
 637  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 638  *
 639  * Destroy a PurpleNotifyUserInfoEntry
 640  */
 641 void purple_notify_user_info_entry_destroy(PurpleNotifyUserInfoEntry *user_info_entry);
 642
 643 /**
 644  * purple_notify_user_info_add_section_break:
 645  * @user_info:  The PurpleNotifyUserInfo
 646  *
 647  * Add a section break.  A UI might display this as a horizontal line.
 648  */
 649 void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info);
 650
 651 /**
 652  * purple_notify_user_info_prepend_section_break:
 653  * @user_info:  The PurpleNotifyUserInfo
 654  *
 655  * Prepend a section break.  A UI might display this as a horizontal line.
 656  */
 657 void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info);
 658
 659 /**
 660  * purple_notify_user_info_add_section_header:
 661  * @user_info:  The PurpleNotifyUserInfo
 662  * @label:      The name of the section
 663  *
 664  * Add a section header.  A UI might display this in a different font
 665  * from other text.
 666  */
 667 void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label);
 668
 669 /**
 670  * purple_notify_user_info_prepend_section_header:
 671  * @user_info:  The PurpleNotifyUserInfo
 672  * @label:      The name of the section
 673  *
 674  * Prepend a section header.  A UI might display this in a different font
 675  * from other text.
 676  */
 677 void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label);
 678
 679 /**
 680  * purple_notify_user_info_remove_last_item:
 681  *
 682  * Remove the last item which was added to a PurpleNotifyUserInfo. This
 683  * could be used to remove a section header which is not needed.
 684  */
 685 void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info);
 686
 687 /**
 688  * purple_notify_user_info_entry_get_label:
 689  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 690  *
 691  * Get the label for a PurpleNotifyUserInfoEntry
 692  *
 693  * Returns:  The label
 694  */
 695 const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry);
 696
 697 /**
 698  * purple_notify_user_info_entry_set_label:
 699  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 700  * @label:            The label
 701  *
 702  * Set the label for a PurpleNotifyUserInfoEntry
 703  */
 704 void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label);
 705
 706 /**
 707  * purple_notify_user_info_entry_get_value:
 708  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 709  *
 710  * Get the value for a PurpleNotifyUserInfoEntry
 711  *
 712  * Returns:  The value
 713  */
 714 const gchar *purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry);
 715
 716 /**
 717  * purple_notify_user_info_entry_set_value:
 718  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 719  * @value:            The value
 720  *
 721  * Set the value for a PurpleNotifyUserInfoEntry
 722  */
 723 void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value);
 724
 725
 726 /**
 727  * purple_notify_user_info_entry_get_entry_type:
 728  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 729  *
 730  * Get the type of a PurpleNotifyUserInfoEntry
 731  *
 732  * Returns:  The PurpleNotifyUserInfoEntryType
 733  */
 734 PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_entry_type(
 735                 PurpleNotifyUserInfoEntry *user_info_entry);
 736
 737 /**
 738  * purple_notify_user_info_entry_set_entry_type:
 739  * @user_info_entry:  The PurpleNotifyUserInfoEntry
 740  * @type:             The PurpleNotifyUserInfoEntryType
 741  *
 742  * Set the type of a PurpleNotifyUserInfoEntry
 743  */
 744 void purple_notify_user_info_entry_set_entry_type(
 745                 PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type);
 746
 747 /**
 748  * purple_notify_uri:
 749  * @handle: The plugin or connection handle.
 750  * @uri:    The URI to display or go to.
 751  *
 752  * Opens a URI or somehow presents it to the user.
 753  *
 754  * Returns: A UI-specific handle, if any. This may only be presented if
 755  *         the UI code displays a dialog instead of a webpage, or something
 756  *         similar.
 757  */
 758 void *purple_notify_uri(void *handle, const char *uri);
 759
 760 /**
 761  * purple_notify_is_valid_ui_handle:
 762  * @ui_handle: The UI handle.
 763  * @type:      The pointer to variable, where request type may be stored
 764  *                  (may be %NULL).
 765  *
 766  * Checks, if passed UI handle is valid.
 767  *
 768  * Returns: TRUE, if handle is valid, FALSE otherwise.
 769  */
 770 gboolean
 771 purple_notify_is_valid_ui_handle(void *ui_handle, PurpleNotifyType *type);
 772
 773 /**
 774  * purple_notify_close:
 775  * @type:      The notification type.
 776  * @ui_handle: The notification UI handle.
 777  *
 778  * Closes a notification.
 779  *
 780  * This should be used only by the UI operation functions and part of the
 781  * core.
 782  */
 783 void purple_notify_close(PurpleNotifyType type, void *ui_handle);
 784
 785 /**
 786  * purple_notify_close_with_handle:
 787  * @handle: The handle.
 788  *
 789  * Closes all notifications registered with the specified handle.
 790  */
 791 void purple_notify_close_with_handle(void *handle);
 792
 793 /**
 794  * purple_notify_info:
 795  *
 796  * A wrapper for purple_notify_message that displays an information message.
 797  */
 798 #define purple_notify_info(handle, title, primary, secondary, cpar) \
 799         purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
 800                 (primary), (secondary), (cpar), NULL, NULL)
 801
 802 /**
 803  * purple_notify_warning:
 804  *
 805  * A wrapper for purple_notify_message that displays a warning message.
 806  */
 807 #define purple_notify_warning(handle, title, primary, secondary, cpar) \
 808         purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
 809                 (primary), (secondary), (cpar), NULL, NULL)
 810
 811 /**
 812  * purple_notify_error:
 813  *
 814  * A wrapper for purple_notify_message that displays an error message.
 815  */
 816 #define purple_notify_error(handle, title, primary, secondary, cpar) \
 817         purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
 818                 (primary), (secondary), (cpar), NULL, NULL)
 819
 820 /**************************************************************************/
 821 /* UI Registration Functions                                              */
 822 /**************************************************************************/
 823
 824 /**
 825  * purple_notify_ui_ops_get_type:
 826  *
 827  * Returns: The #GType for the #PurpleNotifyUiOps boxed structure.
 828  */
 829 GType purple_notify_ui_ops_get_type(void);
 830
 831 /**
 832  * purple_notify_set_ui_ops:
 833  * @ops: The UI operations structure.
 834  *
 835  * Sets the UI operations structure to be used when displaying a
 836  * notification.
 837  */
 838 void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops);
 839
 840 /**
 841  * purple_notify_get_ui_ops:
 842  *
 843  * Returns the UI operations structure to be used when displaying a
 844  * notification.
 845  *
 846  * Returns: The UI operations structure.
 847  */
 848 PurpleNotifyUiOps *purple_notify_get_ui_ops(void);
 849
 850 /**************************************************************************/
 851 /* Notify Subsystem                                                       */
 852 /**************************************************************************/
 853
 854 /**
 855  * purple_notify_get_handle:
 856  *
 857  * Returns the notify subsystem handle.
 858  *
 859  * Returns: The notify subsystem handle.
 860  */
 861 void *purple_notify_get_handle(void);
 862
 863 /**
 864  * purple_notify_init:
 865  *
 866  * Initializes the notify subsystem.
 867  */
 868 void purple_notify_init(void);
 869
 870 /**
 871  * purple_notify_uninit:
 872  *
 873  * Uninitializes the notify subsystem.
 874  */
 875 void purple_notify_uninit(void);
 876
 877
 878 G_END_DECLS
 879
 880 #endif /* PURPLE_NOTIFY_H */