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