1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/notify.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,799 @@
1.4 +/**
1.5 + * @file notify.h Notification API
1.6 + * @ingroup core
1.7 + * @see @ref notify-signals
1.8 + */
1.9 +
1.10 +/* purple
1.11 + *
1.12 + * Purple is the legal property of its developers, whose names are too numerous
1.13 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 + * source distribution.
1.15 + *
1.16 + * This program is free software; you can redistribute it and/or modify
1.17 + * it under the terms of the GNU General Public License as published by
1.18 + * the Free Software Foundation; either version 2 of the License, or
1.19 + * (at your option) any later version.
1.20 + *
1.21 + * This program is distributed in the hope that it will be useful,
1.22 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 + * GNU General Public License for more details.
1.25 + *
1.26 + * You should have received a copy of the GNU General Public License
1.27 + * along with this program; if not, write to the Free Software
1.28 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 + */
1.30 +#ifndef _PURPLE_NOTIFY_H_
1.31 +#define _PURPLE_NOTIFY_H_
1.32 +
1.33 +#include <stdlib.h>
1.34 +#include <glib-object.h>
1.35 +#include <glib.h>
1.36 +
1.37 +typedef struct _PurpleNotifyUserInfoEntry PurpleNotifyUserInfoEntry;
1.38 +typedef struct _PurpleNotifyUserInfo PurpleNotifyUserInfo;
1.39 +
1.40 +#include "connection.h"
1.41 +
1.42 +/**
1.43 + * Notification close callbacks.
1.44 + */
1.45 +typedef void (*PurpleNotifyCloseCallback) (gpointer user_data);
1.46 +
1.47 +
1.48 +/**
1.49 + * Notification types.
1.50 + */
1.51 +typedef enum
1.52 +{
1.53 + PURPLE_NOTIFY_MESSAGE = 0, /**< Message notification. */
1.54 + PURPLE_NOTIFY_EMAIL, /**< Single email notification. */
1.55 + PURPLE_NOTIFY_EMAILS, /**< Multiple email notification. */
1.56 + PURPLE_NOTIFY_FORMATTED, /**< Formatted text. */
1.57 + PURPLE_NOTIFY_SEARCHRESULTS, /**< Buddy search results. */
1.58 + PURPLE_NOTIFY_USERINFO, /**< Formatted userinfo text. */
1.59 + PURPLE_NOTIFY_URI /**< URI notification or display. */
1.60 +
1.61 +} PurpleNotifyType;
1.62 +
1.63 +
1.64 +/**
1.65 + * Notification message types.
1.66 + */
1.67 +typedef enum
1.68 +{
1.69 + PURPLE_NOTIFY_MSG_ERROR = 0, /**< Error notification. */
1.70 + PURPLE_NOTIFY_MSG_WARNING, /**< Warning notification. */
1.71 + PURPLE_NOTIFY_MSG_INFO /**< Information notification. */
1.72 +
1.73 +} PurpleNotifyMsgType;
1.74 +
1.75 +
1.76 +/**
1.77 + * The types of buttons
1.78 + */
1.79 +typedef enum
1.80 +{
1.81 + PURPLE_NOTIFY_BUTTON_LABELED = 0, /**< special use, see _button_add_labeled */
1.82 + PURPLE_NOTIFY_BUTTON_CONTINUE = 1,
1.83 + PURPLE_NOTIFY_BUTTON_ADD,
1.84 + PURPLE_NOTIFY_BUTTON_INFO,
1.85 + PURPLE_NOTIFY_BUTTON_IM,
1.86 + PURPLE_NOTIFY_BUTTON_JOIN,
1.87 + PURPLE_NOTIFY_BUTTON_INVITE
1.88 +} PurpleNotifySearchButtonType;
1.89 +
1.90 +
1.91 +/**
1.92 + * Search results object.
1.93 + */
1.94 +typedef struct
1.95 +{
1.96 + GList *columns; /**< List of the search column objects. */
1.97 + GList *rows; /**< List of rows in the result. */
1.98 + GList *buttons; /**< List of buttons to display. */
1.99 +
1.100 +} PurpleNotifySearchResults;
1.101 +
1.102 +/**
1.103 + * Types of PurpleNotifyUserInfoEntry objects
1.104 + */
1.105 +typedef enum
1.106 +{
1.107 + PURPLE_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
1.108 + PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
1.109 + PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
1.110 +} PurpleNotifyUserInfoEntryType;
1.111 +
1.112 +/**
1.113 + * Single column of a search result.
1.114 + */
1.115 +typedef struct
1.116 +{
1.117 + char *title; /**< Title of the column. */
1.118 +
1.119 +} PurpleNotifySearchColumn;
1.120 +
1.121 +
1.122 +/**
1.123 + * Callback for a button in a search result.
1.124 + *
1.125 + * @param c the PurpleConnection passed to purple_notify_searchresults
1.126 + * @param row the contents of the selected row
1.127 + * @param user_data User defined data.
1.128 + */
1.129 +typedef void (*PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row,
1.130 + gpointer user_data);
1.131 +
1.132 +
1.133 +/**
1.134 + * Definition of a button.
1.135 + */
1.136 +typedef struct
1.137 +{
1.138 + PurpleNotifySearchButtonType type;
1.139 + PurpleNotifySearchResultsCallback callback; /**< Function to be called when clicked. */
1.140 + char *label; /**< only for PURPLE_NOTIFY_BUTTON_LABELED */
1.141 +} PurpleNotifySearchButton;
1.142 +
1.143 +
1.144 +/**
1.145 + * Notification UI operations.
1.146 + */
1.147 +typedef struct
1.148 +{
1.149 + void *(*notify_message)(PurpleNotifyMsgType type, const char *title,
1.150 + const char *primary, const char *secondary);
1.151 +
1.152 + void *(*notify_email)(PurpleConnection *gc,
1.153 + const char *subject, const char *from,
1.154 + const char *to, const char *url);
1.155 +
1.156 + void *(*notify_emails)(PurpleConnection *gc,
1.157 + size_t count, gboolean detailed,
1.158 + const char **subjects, const char **froms,
1.159 + const char **tos, const char **urls);
1.160 +
1.161 + void *(*notify_formatted)(const char *title, const char *primary,
1.162 + const char *secondary, const char *text);
1.163 +
1.164 + void *(*notify_searchresults)(PurpleConnection *gc, const char *title,
1.165 + const char *primary, const char *secondary,
1.166 + PurpleNotifySearchResults *results, gpointer user_data);
1.167 +
1.168 + void (*notify_searchresults_new_rows)(PurpleConnection *gc,
1.169 + PurpleNotifySearchResults *results,
1.170 + void *data);
1.171 +
1.172 + void *(*notify_userinfo)(PurpleConnection *gc, const char *who,
1.173 + PurpleNotifyUserInfo *user_info);
1.174 +
1.175 + void *(*notify_uri)(const char *uri);
1.176 +
1.177 + void (*close_notify)(PurpleNotifyType type, void *ui_handle);
1.178 +
1.179 + void (*_purple_reserved1)(void);
1.180 + void (*_purple_reserved2)(void);
1.181 + void (*_purple_reserved3)(void);
1.182 + void (*_purple_reserved4)(void);
1.183 +} PurpleNotifyUiOps;
1.184 +
1.185 +
1.186 +#ifdef __cplusplus
1.187 +extern "C" {
1.188 +#endif
1.189 +
1.190 +
1.191 +/**************************************************************************/
1.192 +/** Search results notification API */
1.193 +/**************************************************************************/
1.194 +/*@{*/
1.195 +
1.196 +/**
1.197 + * Displays results from a buddy search. This can be, for example,
1.198 + * a window with a list of all found buddies, where you are given the
1.199 + * option of adding buddies to your buddy list.
1.200 + *
1.201 + * @param gc The PurpleConnection handle associated with the information.
1.202 + * @param title The title of the message. If this is NULL, the title
1.203 + * will be "Search Results."
1.204 + * @param primary The main point of the message.
1.205 + * @param secondary The secondary information.
1.206 + * @param results The PurpleNotifySearchResults instance.
1.207 + * @param cb The callback to call when the user closes
1.208 + * the notification.
1.209 + * @param user_data The data to pass to the close callback and any other
1.210 + * callback associated with a button.
1.211 + *
1.212 + * @return A UI-specific handle.
1.213 + */
1.214 +void *purple_notify_searchresults(PurpleConnection *gc, const char *title,
1.215 + const char *primary, const char *secondary,
1.216 + PurpleNotifySearchResults *results, PurpleNotifyCloseCallback cb,
1.217 + gpointer user_data);
1.218 +
1.219 +/**
1.220 + * Frees a PurpleNotifySearchResults object.
1.221 + *
1.222 + * @param results The PurpleNotifySearchResults to free.
1.223 + */
1.224 +void purple_notify_searchresults_free(PurpleNotifySearchResults *results);
1.225 +
1.226 +/**
1.227 + * Replace old rows with the new. Reuse an existing window.
1.228 + *
1.229 + * @param gc The PurpleConnection structure.
1.230 + * @param results The PurpleNotifySearchResults structure.
1.231 + * @param data Data returned by the purple_notify_searchresults().
1.232 + */
1.233 +void purple_notify_searchresults_new_rows(PurpleConnection *gc,
1.234 + PurpleNotifySearchResults *results,
1.235 + void *data);
1.236 +
1.237 +
1.238 +/**
1.239 + * Adds a stock button that will be displayed in the search results dialog.
1.240 + *
1.241 + * @param results The search results object.
1.242 + * @param type Type of the button. (TODO: Only one button of a given type
1.243 + * can be displayed.)
1.244 + * @param cb Function that will be called on the click event.
1.245 + */
1.246 +void purple_notify_searchresults_button_add(PurpleNotifySearchResults *results,
1.247 + PurpleNotifySearchButtonType type,
1.248 + PurpleNotifySearchResultsCallback cb);
1.249 +
1.250 +
1.251 +/**
1.252 + * Adds a plain labelled button that will be displayed in the search results
1.253 + * dialog.
1.254 + *
1.255 + * @param results The search results object
1.256 + * @param label The label to display
1.257 + * @param cb Function that will be called on the click event
1.258 + */
1.259 +void purple_notify_searchresults_button_add_labeled(PurpleNotifySearchResults *results,
1.260 + const char *label,
1.261 + PurpleNotifySearchResultsCallback cb);
1.262 +
1.263 +
1.264 +/**
1.265 + * Returns a newly created search results object.
1.266 + *
1.267 + * @return The new search results object.
1.268 + */
1.269 +PurpleNotifySearchResults *purple_notify_searchresults_new(void);
1.270 +
1.271 +/**
1.272 + * Returns a newly created search result column object.
1.273 + *
1.274 + * @param title Title of the column. NOTE: Title will get g_strdup()ed.
1.275 + *
1.276 + * @return The new search column object.
1.277 + */
1.278 +PurpleNotifySearchColumn *purple_notify_searchresults_column_new(const char *title);
1.279 +
1.280 +/**
1.281 + * Adds a new column to the search result object.
1.282 + *
1.283 + * @param results The result object to which the column will be added.
1.284 + * @param column The column that will be added to the result object.
1.285 + */
1.286 +void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results,
1.287 + PurpleNotifySearchColumn *column);
1.288 +
1.289 +/**
1.290 + * Adds a new row of the results to the search results object.
1.291 + *
1.292 + * @param results The search results object.
1.293 + * @param row The row of the results.
1.294 + */
1.295 +void purple_notify_searchresults_row_add(PurpleNotifySearchResults *results,
1.296 + GList *row);
1.297 +
1.298 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.299 +/**
1.300 + * Returns a number of the rows in the search results object.
1.301 + *
1.302 + * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.303 + * there is sufficient demand to keep it. Using this
1.304 + * function encourages looping through the results
1.305 + * inefficiently. Instead of using this function you
1.306 + * should iterate through the results using a loop
1.307 + * similar to this:
1.308 + * for (l = results->rows; l != NULL; l = l->next)
1.309 + * If you really need to get the number of rows you
1.310 + * can use g_list_length(results->rows).
1.311 + *
1.312 + * @param results The search results object.
1.313 + *
1.314 + * @return Number of the result rows.
1.315 + */
1.316 +guint purple_notify_searchresults_get_rows_count(PurpleNotifySearchResults *results);
1.317 +#endif
1.318 +
1.319 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.320 +/**
1.321 + * Returns a number of the columns in the search results object.
1.322 + *
1.323 + * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.324 + * there is sufficient demand to keep it. Using this
1.325 + * function encourages looping through the columns
1.326 + * inefficiently. Instead of using this function you
1.327 + * should iterate through the columns using a loop
1.328 + * similar to this:
1.329 + * for (l = results->columns; l != NULL; l = l->next)
1.330 + * If you really need to get the number of columns you
1.331 + * can use g_list_length(results->columns).
1.332 + *
1.333 + * @param results The search results object.
1.334 + *
1.335 + * @return Number of the columns.
1.336 + */
1.337 +guint purple_notify_searchresults_get_columns_count(PurpleNotifySearchResults *results);
1.338 +#endif
1.339 +
1.340 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.341 +/**
1.342 + * Returns a row of the results from the search results object.
1.343 + *
1.344 + * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.345 + * there is sufficient demand to keep it. Using this
1.346 + * function encourages looping through the results
1.347 + * inefficiently. Instead of using this function you
1.348 + * should iterate through the results using a loop
1.349 + * similar to this:
1.350 + * for (l = results->rows; l != NULL; l = l->next)
1.351 + * If you really need to get the data for a particular
1.352 + * row you can use g_list_nth_data(results->rows, row_id).
1.353 + *
1.354 + * @param results The search results object.
1.355 + * @param row_id Index of the row to be returned.
1.356 + *
1.357 + * @return Row of the results.
1.358 + */
1.359 +GList *purple_notify_searchresults_row_get(PurpleNotifySearchResults *results,
1.360 + unsigned int row_id);
1.361 +#endif
1.362 +
1.363 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.364 +/**
1.365 + * Returns a title of the search results object's column.
1.366 + *
1.367 + * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.368 + * there is sufficient demand to keep it. Using this
1.369 + * function encourages looping through the columns
1.370 + * inefficiently. Instead of using this function you
1.371 + * should iterate through the name of a particular
1.372 + * column you can use
1.373 + * g_list_nth_data(results->columns, row_id).
1.374 + *
1.375 + * @param results The search results object.
1.376 + * @param column_id Index of the column.
1.377 + *
1.378 + * @return Title of the column.
1.379 + */
1.380 +char *purple_notify_searchresults_column_get_title(PurpleNotifySearchResults *results,
1.381 + unsigned int column_id);
1.382 +#endif
1.383 +
1.384 +/*@}*/
1.385 +
1.386 +/**************************************************************************/
1.387 +/** @name Notification API */
1.388 +/**************************************************************************/
1.389 +/*@{*/
1.390 +
1.391 +/**
1.392 + * Displays a notification message to the user.
1.393 + *
1.394 + * @param handle The plugin or connection handle.
1.395 + * @param type The notification type.
1.396 + * @param title The title of the message.
1.397 + * @param primary The main point of the message.
1.398 + * @param secondary The secondary information.
1.399 + * @param cb The callback to call when the user closes
1.400 + * the notification.
1.401 + * @param user_data The data to pass to the callback.
1.402 + *
1.403 + * @return A UI-specific handle.
1.404 + */
1.405 +void *purple_notify_message(void *handle, PurpleNotifyMsgType type,
1.406 + const char *title, const char *primary,
1.407 + const char *secondary, PurpleNotifyCloseCallback cb,
1.408 + gpointer user_data);
1.409 +
1.410 +/**
1.411 + * Displays a single email notification to the user.
1.412 + *
1.413 + * @param handle The plugin or connection handle.
1.414 + * @param subject The subject of the email.
1.415 + * @param from The from address.
1.416 + * @param to The destination address.
1.417 + * @param url The URL where the message can be read.
1.418 + * @param cb The callback to call when the user closes
1.419 + * the notification.
1.420 + * @param user_data The data to pass to the callback.
1.421 + *
1.422 + * @return A UI-specific handle.
1.423 + */
1.424 +void *purple_notify_email(void *handle, const char *subject,
1.425 + const char *from, const char *to,
1.426 + const char *url, PurpleNotifyCloseCallback cb,
1.427 + gpointer user_data);
1.428 +
1.429 +/**
1.430 + * Displays a notification for multiple emails to the user.
1.431 + *
1.432 + * @param handle The plugin or connection handle.
1.433 + * @param count The number of emails. '0' can be used to signify that
1.434 + * the user has no unread emails and the UI should remove
1.435 + * the mail notification.
1.436 + * @param detailed @c TRUE if there is information for each email in the
1.437 + * arrays.
1.438 + * @param subjects The array of subjects.
1.439 + * @param froms The array of from addresses.
1.440 + * @param tos The array of destination addresses.
1.441 + * @param urls The URLs where the messages can be read.
1.442 + * @param cb The callback to call when the user closes
1.443 + * the notification.
1.444 + * @param user_data The data to pass to the callback.
1.445 + *
1.446 + * @return A UI-specific handle.
1.447 + */
1.448 +void *purple_notify_emails(void *handle, size_t count, gboolean detailed,
1.449 + const char **subjects, const char **froms,
1.450 + const char **tos, const char **urls,
1.451 + PurpleNotifyCloseCallback cb, gpointer user_data);
1.452 +
1.453 +/**
1.454 + * Displays a notification with formatted text.
1.455 + *
1.456 + * The text is essentially a stripped-down format of HTML, the same that
1.457 + * IMs may send.
1.458 + *
1.459 + * @param handle The plugin or connection handle.
1.460 + * @param title The title of the message.
1.461 + * @param primary The main point of the message.
1.462 + * @param secondary The secondary information.
1.463 + * @param text The formatted text.
1.464 + * @param cb The callback to call when the user closes
1.465 + * the notification.
1.466 + * @param user_data The data to pass to the callback.
1.467 + *
1.468 + * @return A UI-specific handle.
1.469 + */
1.470 +void *purple_notify_formatted(void *handle, const char *title,
1.471 + const char *primary, const char *secondary,
1.472 + const char *text, PurpleNotifyCloseCallback cb, gpointer user_data);
1.473 +
1.474 +/**
1.475 + * Displays user information with formatted text, passing information giving
1.476 + * the connection and username from which the user information came.
1.477 + *
1.478 + * The text is essentially a stripped-down format of HTML, the same that
1.479 + * IMs may send.
1.480 + *
1.481 + * @param gc The PurpleConnection handle associated with the information.
1.482 + * @param who The username associated with the information.
1.483 + * @param user_info The PurpleNotifyUserInfo which contains the information
1.484 + * @param cb The callback to call when the user closes the notification.
1.485 + * @param user_data The data to pass to the callback.
1.486 + *
1.487 + * @return A UI-specific handle.
1.488 + */
1.489 +void *purple_notify_userinfo(PurpleConnection *gc, const char *who,
1.490 + PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb,
1.491 + gpointer user_data);
1.492 +
1.493 +/**
1.494 + * Create a new PurpleNotifyUserInfo which is suitable for passing to
1.495 + * purple_notify_userinfo()
1.496 + *
1.497 + * @return A new PurpleNotifyUserInfo, which the caller must destroy when done
1.498 + */
1.499 +PurpleNotifyUserInfo *purple_notify_user_info_new(void);
1.500 +
1.501 +/**
1.502 + * Destroy a PurpleNotifyUserInfo
1.503 + *
1.504 + * @param user_info The PurpleNotifyUserInfo
1.505 + */
1.506 +void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info);
1.507 +
1.508 +/**
1.509 + * Retrieve the array of PurpleNotifyUserInfoEntry objects from a
1.510 + * PurpleNotifyUserInfo
1.511 + *
1.512 + * This GList may be manipulated directly with normal GList functions such
1.513 + * as g_list_insert(). Only PurpleNotifyUserInfoEntry are allowed in the
1.514 + * list. If a PurpleNotifyUserInfoEntry item is added to the list, it
1.515 + * should not be g_free()'d by the caller; PurpleNotifyUserInfo will g_free
1.516 + * it when destroyed.
1.517 + *
1.518 + * To remove a PurpleNotifyUserInfoEntry, use
1.519 + * purple_notify_user_info_remove_entry(). Do not use the GList directly.
1.520 + *
1.521 + * @param user_info The PurpleNotifyUserInfo
1.522 + *
1.523 + * @constreturn A GList of PurpleNotifyUserInfoEntry objects
1.524 + */
1.525 +GList *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info);
1.526 +
1.527 +/**
1.528 + * Create a textual representation of a PurpleNotifyUserInfo, separating
1.529 + * entries with newline
1.530 + *
1.531 + * @param user_info The PurpleNotifyUserInfo
1.532 + * @param newline The separation character
1.533 + */
1.534 +char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline);
1.535 +
1.536 +/**
1.537 + * Add a label/value pair to a PurpleNotifyUserInfo object.
1.538 + * PurpleNotifyUserInfo keeps track of the order in which pairs are added.
1.539 + *
1.540 + * @param user_info The PurpleNotifyUserInfo
1.541 + * @param label A label, which for example might be displayed by a
1.542 + * UI with a colon after it ("Status:"). Do not include
1.543 + * a colon. If NULL, value will be displayed without a
1.544 + * label.
1.545 + * @param value The value, which might be displayed by a UI after
1.546 + * the label. If NULL, label will still be displayed;
1.547 + * the UI should then treat label as independent and not
1.548 + * include a colon if it would otherwise.
1.549 + */
1.550 +void purple_notify_user_info_add_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
1.551 +
1.552 +/**
1.553 + * Prepend a label/value pair to a PurpleNotifyUserInfo object
1.554 + *
1.555 + * @param user_info The PurpleNotifyUserInfo
1.556 + * @param label A label, which for example might be displayed by a
1.557 + * UI with a colon after it ("Status:"). Do not include
1.558 + * a colon. If NULL, value will be displayed without a
1.559 + * label.
1.560 + * @param value The value, which might be displayed by a UI after
1.561 + * the label. If NULL, label will still be displayed;
1.562 + * the UI should then treat label as independent and not
1.563 + * include a colon if it would otherwise.
1.564 + */
1.565 +void purple_notify_user_info_prepend_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
1.566 +
1.567 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.568 +/**
1.569 + * Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object
1.570 + * without freeing the entry.
1.571 + *
1.572 + * @param user_info The PurpleNotifyUserInfo
1.573 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.574 + *
1.575 + * @deprecated Nothing is using this function and it should be removed
1.576 + * in 3.0.0. Or, if we decide we want to keep it in 3.0.0
1.577 + * then we should make purple_notify_user_info_entry_destroy
1.578 + * public so that entries can be free'd after they're removed.
1.579 + */
1.580 +void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry);
1.581 +#endif
1.582 +
1.583 +/**
1.584 + * Create a new PurpleNotifyUserInfoEntry
1.585 + *
1.586 + * If added to a PurpleNotifyUserInfo object, this should not be free()'d,
1.587 + * as PurpleNotifyUserInfo will do so when destroyed.
1.588 + * purple_notify_user_info_add_pair() and
1.589 + * purple_notify_user_info_prepend_pair() are convenience methods for
1.590 + * creating entries and adding them to a PurpleNotifyUserInfo.
1.591 + *
1.592 + * @param label A label, which for example might be displayed by a UI
1.593 + * with a colon after it ("Status:"). Do not include a
1.594 + * colon. If NULL, value will be displayed without a label.
1.595 + * @param value The value, which might be displayed by a UI after the
1.596 + * label. If NULL, label will still be displayed; the UI
1.597 + * should then treat label as independent and not include a
1.598 + * colon if it would otherwise.
1.599 + *
1.600 + * @result A new PurpleNotifyUserInfoEntry
1.601 + */
1.602 +PurpleNotifyUserInfoEntry *purple_notify_user_info_entry_new(const char *label, const char *value);
1.603 +
1.604 +/**
1.605 + * Add a section break. A UI might display this as a horizontal line.
1.606 + *
1.607 + * @param user_info The PurpleNotifyUserInfo
1.608 + */
1.609 +void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info);
1.610 +
1.611 +/**
1.612 + * Prepend a section break. A UI might display this as a horizontal line.
1.613 + *
1.614 + * @param user_info The PurpleNotifyUserInfo
1.615 + * @since 2.5.0
1.616 + */
1.617 +void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info);
1.618 +
1.619 +/**
1.620 + * Add a section header. A UI might display this in a different font
1.621 + * from other text.
1.622 + *
1.623 + * @param user_info The PurpleNotifyUserInfo
1.624 + * @param label The name of the section
1.625 + */
1.626 +void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label);
1.627 +
1.628 +/**
1.629 + * Prepend a section header. A UI might display this in a different font
1.630 + * from other text.
1.631 + *
1.632 + * @param user_info The PurpleNotifyUserInfo
1.633 + * @param label The name of the section
1.634 + * @since 2.5.0
1.635 + */
1.636 +void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label);
1.637 +
1.638 +/**
1.639 + * Remove the last item which was added to a PurpleNotifyUserInfo. This
1.640 + * could be used to remove a section header which is not needed.
1.641 + */
1.642 +void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info);
1.643 +
1.644 +/**
1.645 + * Get the label for a PurpleNotifyUserInfoEntry
1.646 + *
1.647 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.648 + *
1.649 + * @return The label
1.650 + */
1.651 +const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry);
1.652 +
1.653 +/**
1.654 + * Set the label for a PurpleNotifyUserInfoEntry
1.655 + *
1.656 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.657 + * @param label The label
1.658 + */
1.659 +void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label);
1.660 +
1.661 +/**
1.662 + * Get the value for a PurpleNotifyUserInfoEntry
1.663 + *
1.664 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.665 + *
1.666 + * @result The value
1.667 + */
1.668 +const gchar *purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry);
1.669 +
1.670 +/**
1.671 + * Set the value for a PurpleNotifyUserInfoEntry
1.672 + *
1.673 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.674 + * @param value The value
1.675 + */
1.676 +void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value);
1.677 +
1.678 +
1.679 +/**
1.680 + * Get the type of a PurpleNotifyUserInfoEntry
1.681 + *
1.682 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.683 + *
1.684 + * @return The PurpleNotifyUserInfoEntryType
1.685 + */
1.686 +PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry);
1.687 +
1.688 +/**
1.689 + * Set the type of a PurpleNotifyUserInfoEntry
1.690 + *
1.691 + * @param user_info_entry The PurpleNotifyUserInfoEntry
1.692 + * @param type The PurpleNotifyUserInfoEntryType
1.693 + */
1.694 +void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry,
1.695 + PurpleNotifyUserInfoEntryType type);
1.696 +
1.697 +/**
1.698 + * Opens a URI or somehow presents it to the user.
1.699 + *
1.700 + * @param handle The plugin or connection handle.
1.701 + * @param uri The URI to display or go to.
1.702 + *
1.703 + * @return A UI-specific handle, if any. This may only be presented if
1.704 + * the UI code displays a dialog instead of a webpage, or something
1.705 + * similar.
1.706 + */
1.707 +void *purple_notify_uri(void *handle, const char *uri);
1.708 +
1.709 +/**
1.710 + * Closes a notification.
1.711 + *
1.712 + * This should be used only by the UI operation functions and part of the
1.713 + * core.
1.714 + *
1.715 + * @param type The notification type.
1.716 + * @param ui_handle The notification UI handle.
1.717 + */
1.718 +void purple_notify_close(PurpleNotifyType type, void *ui_handle);
1.719 +
1.720 +/**
1.721 + * Closes all notifications registered with the specified handle.
1.722 + *
1.723 + * @param handle The handle.
1.724 + */
1.725 +void purple_notify_close_with_handle(void *handle);
1.726 +
1.727 +/**
1.728 + * A wrapper for purple_notify_message that displays an information message.
1.729 + */
1.730 +#define purple_notify_info(handle, title, primary, secondary) \
1.731 + purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
1.732 + (primary), (secondary), NULL, NULL)
1.733 +
1.734 +/**
1.735 + * A wrapper for purple_notify_message that displays a warning message.
1.736 + */
1.737 +#define purple_notify_warning(handle, title, primary, secondary) \
1.738 + purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
1.739 + (primary), (secondary), NULL, NULL)
1.740 +
1.741 +/**
1.742 + * A wrapper for purple_notify_message that displays an error message.
1.743 + */
1.744 +#define purple_notify_error(handle, title, primary, secondary) \
1.745 + purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
1.746 + (primary), (secondary), NULL, NULL)
1.747 +
1.748 +/*@}*/
1.749 +
1.750 +/**************************************************************************/
1.751 +/** @name UI Registration Functions */
1.752 +/**************************************************************************/
1.753 +/*@{*/
1.754 +
1.755 +/**
1.756 + * Sets the UI operations structure to be used when displaying a
1.757 + * notification.
1.758 + *
1.759 + * @param ops The UI operations structure.
1.760 + */
1.761 +void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops);
1.762 +
1.763 +/**
1.764 + * Returns the UI operations structure to be used when displaying a
1.765 + * notification.
1.766 + *
1.767 + * @return The UI operations structure.
1.768 + */
1.769 +PurpleNotifyUiOps *purple_notify_get_ui_ops(void);
1.770 +
1.771 +/*@}*/
1.772 +
1.773 +/**************************************************************************/
1.774 +/** @name Notify Subsystem */
1.775 +/**************************************************************************/
1.776 +/*@{*/
1.777 +
1.778 +/**
1.779 + * Returns the notify subsystem handle.
1.780 + *
1.781 + * @return The notify subsystem handle.
1.782 + */
1.783 +void *purple_notify_get_handle(void);
1.784 +
1.785 +/**
1.786 + * Initializes the notify subsystem.
1.787 + */
1.788 +void purple_notify_init(void);
1.789 +
1.790 +/**
1.791 + * Uninitializes the notify subsystem.
1.792 + */
1.793 +void purple_notify_uninit(void);
1.794 +
1.795 +/*@}*/
1.796 +
1.797 +
1.798 +#ifdef __cplusplus
1.799 +}
1.800 +#endif
1.801 +
1.802 +#endif /* _PURPLE_NOTIFY_H_ */