libpurple/notify.h

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