1.1 --- a/Frameworks/libpurple.framework/Versions/0.5.6/Headers/notify.h Sun Jun 21 22:04:11 2009 -0400
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,789 +0,0 @@
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 -#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.298 -/**
1.299 - * Returns a number of the rows in the search results object.
1.300 - *
1.301 - * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.302 - * there is sufficient demand to keep it. Using this
1.303 - * function encourages looping through the results
1.304 - * inefficiently. Instead of using this function you
1.305 - * should iterate through the results using a loop
1.306 - * similar to this:
1.307 - * for (l = results->rows; l != NULL; l = l->next)
1.308 - * If you really need to get the number of rows you
1.309 - * can use g_list_length(results->rows).
1.310 - *
1.311 - * @param results The search results object.
1.312 - *
1.313 - * @return Number of the result rows.
1.314 - */
1.315 -guint purple_notify_searchresults_get_rows_count(PurpleNotifySearchResults *results);
1.316 -#endif
1.317 -
1.318 -#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.319 -/**
1.320 - * Returns a number of the columns in the search results object.
1.321 - *
1.322 - * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.323 - * there is sufficient demand to keep it. Using this
1.324 - * function encourages looping through the columns
1.325 - * inefficiently. Instead of using this function you
1.326 - * should iterate through the columns using a loop
1.327 - * similar to this:
1.328 - * for (l = results->columns; l != NULL; l = l->next)
1.329 - * If you really need to get the number of columns you
1.330 - * can use g_list_length(results->columns).
1.331 - *
1.332 - * @param results The search results object.
1.333 - *
1.334 - * @return Number of the columns.
1.335 - */
1.336 -guint purple_notify_searchresults_get_columns_count(PurpleNotifySearchResults *results);
1.337 -#endif
1.338 -
1.339 -#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.340 -/**
1.341 - * Returns a row of the results from the search results object.
1.342 - *
1.343 - * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.344 - * there is sufficient demand to keep it. Using this
1.345 - * function encourages looping through the results
1.346 - * inefficiently. Instead of using this function you
1.347 - * should iterate through the results using a loop
1.348 - * similar to this:
1.349 - * for (l = results->rows; l != NULL; l = l->next)
1.350 - * If you really need to get the data for a particular
1.351 - * row you can use g_list_nth_data(results->rows, row_id).
1.352 - *
1.353 - * @param results The search results object.
1.354 - * @param row_id Index of the row to be returned.
1.355 - *
1.356 - * @return Row of the results.
1.357 - */
1.358 -GList *purple_notify_searchresults_row_get(PurpleNotifySearchResults *results,
1.359 - unsigned int row_id);
1.360 -#endif
1.361 -
1.362 -#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
1.363 -/**
1.364 - * Returns a title of the search results object's column.
1.365 - *
1.366 - * @deprecated This function will be removed in Pidgin 3.0.0 unless
1.367 - * there is sufficient demand to keep it. Using this
1.368 - * function encourages looping through the columns
1.369 - * inefficiently. Instead of using this function you
1.370 - * should iterate through the name of a particular
1.371 - * column you can use
1.372 - * g_list_nth_data(results->columns, row_id).
1.373 - *
1.374 - * @param results The search results object.
1.375 - * @param column_id Index of the column.
1.376 - *
1.377 - * @return Title of the column.
1.378 - */
1.379 -char *purple_notify_searchresults_column_get_title(PurpleNotifySearchResults *results,
1.380 - unsigned int column_id);
1.381 -#endif
1.382 -
1.383 -/*@}*/
1.384 -
1.385 -/**************************************************************************/
1.386 -/** @name Notification API */
1.387 -/**************************************************************************/
1.388 -/*@{*/
1.389 -
1.390 -/**
1.391 - * Displays a notification message to the user.
1.392 - *
1.393 - * @param handle The plugin or connection handle.
1.394 - * @param type The notification type.
1.395 - * @param title The title of the message.
1.396 - * @param primary The main point of the message.
1.397 - * @param secondary The secondary information.
1.398 - * @param cb The callback to call when the user closes
1.399 - * the notification.
1.400 - * @param user_data The data to pass to the callback.
1.401 - *
1.402 - * @return A UI-specific handle.
1.403 - */
1.404 -void *purple_notify_message(void *handle, PurpleNotifyMsgType type,
1.405 - const char *title, const char *primary,
1.406 - const char *secondary, PurpleNotifyCloseCallback cb,
1.407 - gpointer user_data);
1.408 -
1.409 -/**
1.410 - * Displays a single email notification to the user.
1.411 - *
1.412 - * @param handle The plugin or connection handle.
1.413 - * @param subject The subject of the email.
1.414 - * @param from The from address.
1.415 - * @param to The destination address.
1.416 - * @param url The URL where the message can be read.
1.417 - * @param cb The callback to call when the user closes
1.418 - * the notification.
1.419 - * @param user_data The data to pass to the callback.
1.420 - *
1.421 - * @return A UI-specific handle.
1.422 - */
1.423 -void *purple_notify_email(void *handle, const char *subject,
1.424 - const char *from, const char *to,
1.425 - const char *url, PurpleNotifyCloseCallback cb,
1.426 - gpointer user_data);
1.427 -
1.428 -/**
1.429 - * Displays a notification for multiple emails to the user.
1.430 - *
1.431 - * @param handle The plugin or connection handle.
1.432 - * @param count The number of emails.
1.433 - * @param detailed @c TRUE if there is information for each email in the
1.434 - * arrays.
1.435 - * @param subjects The array of subjects.
1.436 - * @param froms The array of from addresses.
1.437 - * @param tos The array of destination addresses.
1.438 - * @param urls The URLs where the messages can be read.
1.439 - * @param cb The callback to call when the user closes
1.440 - * the notification.
1.441 - * @param user_data The data to pass to the callback.
1.442 - *
1.443 - * @return A UI-specific handle.
1.444 - */
1.445 -void *purple_notify_emails(void *handle, size_t count, gboolean detailed,
1.446 - const char **subjects, const char **froms,
1.447 - const char **tos, const char **urls,
1.448 - PurpleNotifyCloseCallback cb, gpointer user_data);
1.449 -
1.450 -/**
1.451 - * Displays a notification with formatted text.
1.452 - *
1.453 - * The text is essentially a stripped-down format of HTML, the same that
1.454 - * IMs may send.
1.455 - *
1.456 - * @param handle The plugin or connection handle.
1.457 - * @param title The title of the message.
1.458 - * @param primary The main point of the message.
1.459 - * @param secondary The secondary information.
1.460 - * @param text The formatted text.
1.461 - * @param cb The callback to call when the user closes
1.462 - * the notification.
1.463 - * @param user_data The data to pass to the callback.
1.464 - *
1.465 - * @return A UI-specific handle.
1.466 - */
1.467 -void *purple_notify_formatted(void *handle, const char *title,
1.468 - const char *primary, const char *secondary,
1.469 - const char *text, PurpleNotifyCloseCallback cb, gpointer user_data);
1.470 -
1.471 -/**
1.472 - * Displays user information with formatted text, passing information giving
1.473 - * the connection and username from which the user information came.
1.474 - *
1.475 - * The text is essentially a stripped-down format of HTML, the same that
1.476 - * IMs may send.
1.477 - *
1.478 - * @param gc The PurpleConnection handle associated with the information.
1.479 - * @param who The username associated with the information.
1.480 - * @param user_info The PurpleNotifyUserInfo which contains the information
1.481 - * @param cb The callback to call when the user closes the notification.
1.482 - * @param user_data The data to pass to the callback.
1.483 - *
1.484 - * @return A UI-specific handle.
1.485 - */
1.486 -void *purple_notify_userinfo(PurpleConnection *gc, const char *who,
1.487 - PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb,
1.488 - gpointer user_data);
1.489 -
1.490 -/**
1.491 - * Create a new PurpleNotifyUserInfo which is suitable for passing to
1.492 - * purple_notify_userinfo()
1.493 - *
1.494 - * @return A new PurpleNotifyUserInfo, which the caller must destroy when done
1.495 - */
1.496 -PurpleNotifyUserInfo *purple_notify_user_info_new(void);
1.497 -
1.498 -/**
1.499 - * Destroy a PurpleNotifyUserInfo
1.500 - *
1.501 - * @param user_info The PurpleNotifyUserInfo
1.502 - */
1.503 -void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info);
1.504 -
1.505 -/**
1.506 - * Retrieve the array of PurpleNotifyUserInfoEntry objects from a
1.507 - * PurpleNotifyUserInfo
1.508 - *
1.509 - * This GList may be manipulated directly with normal GList functions such
1.510 - * as g_list_insert(). Only PurpleNotifyUserInfoEntry are allowed in the
1.511 - * list. If a PurpleNotifyUserInfoEntry item is added to the list, it
1.512 - * should not be g_free()'d by the caller; PurpleNotifyUserInfo will g_free
1.513 - * it when destroyed.
1.514 - *
1.515 - * To remove a PurpleNotifyUserInfoEntry, use
1.516 - * purple_notify_user_info_remove_entry(). Do not use the GList directly.
1.517 - *
1.518 - * @param user_info The PurpleNotifyUserInfo
1.519 - *
1.520 - * @constreturn A GList of PurpleNotifyUserInfoEntry objects
1.521 - */
1.522 -GList *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info);
1.523 -
1.524 -/**
1.525 - * Create a textual representation of a PurpleNotifyUserInfo, separating
1.526 - * entries with newline
1.527 - *
1.528 - * @param user_info The PurpleNotifyUserInfo
1.529 - * @param newline The separation character
1.530 - */
1.531 -char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline);
1.532 -
1.533 -/**
1.534 - * Add a label/value pair to a PurpleNotifyUserInfo object.
1.535 - * PurpleNotifyUserInfo keeps track of the order in which pairs are added.
1.536 - *
1.537 - * @param user_info The PurpleNotifyUserInfo
1.538 - * @param label A label, which for example might be displayed by a
1.539 - * UI with a colon after it ("Status:"). Do not include
1.540 - * a colon. If NULL, value will be displayed without a
1.541 - * label.
1.542 - * @param value The value, which might be displayed by a UI after
1.543 - * the label. If NULL, label will still be displayed;
1.544 - * the UI should then treat label as independent and not
1.545 - * include a colon if it would otherwise.
1.546 - */
1.547 -void purple_notify_user_info_add_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
1.548 -
1.549 -/**
1.550 - * Prepend a label/value pair to a PurpleNotifyUserInfo object
1.551 - *
1.552 - * @param user_info The PurpleNotifyUserInfo
1.553 - * @param label A label, which for example might be displayed by a
1.554 - * UI with a colon after it ("Status:"). Do not include
1.555 - * a colon. If NULL, value will be displayed without a
1.556 - * label.
1.557 - * @param value The value, which might be displayed by a UI after
1.558 - * the label. If NULL, label will still be displayed;
1.559 - * the UI should then treat label as independent and not
1.560 - * include a colon if it would otherwise.
1.561 - */
1.562 -void purple_notify_user_info_prepend_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
1.563 -
1.564 -/**
1.565 - * Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object
1.566 - * without freeing the entry.
1.567 - *
1.568 - * @param user_info The PurpleNotifyUserInfo
1.569 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.570 - */
1.571 -void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry);
1.572 -
1.573 -/**
1.574 - * Create a new PurpleNotifyUserInfoEntry
1.575 - *
1.576 - * If added to a PurpleNotifyUserInfo object, this should not be free()'d,
1.577 - * as PurpleNotifyUserInfo will do so when destroyed.
1.578 - * purple_notify_user_info_add_pair() and
1.579 - * purple_notify_user_info_prepend_pair() are convenience methods for
1.580 - * creating entries and adding them to a PurpleNotifyUserInfo.
1.581 - *
1.582 - * @param label A label, which for example might be displayed by a UI
1.583 - * with a colon after it ("Status:"). Do not include a
1.584 - * colon. If NULL, value will be displayed without a label.
1.585 - * @param value The value, which might be displayed by a UI after the
1.586 - * label. If NULL, label will still be displayed; the UI
1.587 - * should then treat label as independent and not include a
1.588 - * colon if it would otherwise.
1.589 - *
1.590 - * @result A new PurpleNotifyUserInfoEntry
1.591 - */
1.592 -PurpleNotifyUserInfoEntry *purple_notify_user_info_entry_new(const char *label, const char *value);
1.593 -
1.594 -/**
1.595 - * Add a section break. A UI might display this as a horizontal line.
1.596 - *
1.597 - * @param user_info The PurpleNotifyUserInfo
1.598 - */
1.599 -void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info);
1.600 -
1.601 -/**
1.602 - * Prepend a section break. A UI might display this as a horizontal line.
1.603 - *
1.604 - * @param user_info The PurpleNotifyUserInfo
1.605 - * @since 2.5.0
1.606 - */
1.607 -void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info);
1.608 -
1.609 -/**
1.610 - * Add a section header. A UI might display this in a different font
1.611 - * from other text.
1.612 - *
1.613 - * @param user_info The PurpleNotifyUserInfo
1.614 - * @param label The name of the section
1.615 - */
1.616 -void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label);
1.617 -
1.618 -/**
1.619 - * Prepend a section header. A UI might display this in a different font
1.620 - * from other text.
1.621 - *
1.622 - * @param user_info The PurpleNotifyUserInfo
1.623 - * @param label The name of the section
1.624 - * @since 2.5.0
1.625 - */
1.626 -void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label);
1.627 -
1.628 -/**
1.629 - * Remove the last item which was added to a PurpleNotifyUserInfo. This
1.630 - * could be used to remove a section header which is not needed.
1.631 - */
1.632 -void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info);
1.633 -
1.634 -/**
1.635 - * Get the label for a PurpleNotifyUserInfoEntry
1.636 - *
1.637 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.638 - *
1.639 - * @return The label
1.640 - */
1.641 -const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry);
1.642 -
1.643 -/**
1.644 - * Set the label for a PurpleNotifyUserInfoEntry
1.645 - *
1.646 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.647 - * @param label The label
1.648 - */
1.649 -void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label);
1.650 -
1.651 -/**
1.652 - * Get the value for a PurpleNotifyUserInfoEntry
1.653 - *
1.654 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.655 - *
1.656 - * @result The value
1.657 - */
1.658 -const gchar *purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry);
1.659 -
1.660 -/**
1.661 - * Set the value for a PurpleNotifyUserInfoEntry
1.662 - *
1.663 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.664 - * @param value The value
1.665 - */
1.666 -void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value);
1.667 -
1.668 -
1.669 -/**
1.670 - * Get the type of a PurpleNotifyUserInfoEntry
1.671 - *
1.672 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.673 - *
1.674 - * @return The PurpleNotifyUserInfoEntryType
1.675 - */
1.676 -PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry);
1.677 -
1.678 -/**
1.679 - * Set the type of a PurpleNotifyUserInfoEntry
1.680 - *
1.681 - * @param user_info_entry The PurpleNotifyUserInfoEntry
1.682 - * @param type The PurpleNotifyUserInfoEntryType
1.683 - */
1.684 -void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry,
1.685 - PurpleNotifyUserInfoEntryType type);
1.686 -
1.687 -/**
1.688 - * Opens a URI or somehow presents it to the user.
1.689 - *
1.690 - * @param handle The plugin or connection handle.
1.691 - * @param uri The URI to display or go to.
1.692 - *
1.693 - * @return A UI-specific handle, if any. This may only be presented if
1.694 - * the UI code displays a dialog instead of a webpage, or something
1.695 - * similar.
1.696 - */
1.697 -void *purple_notify_uri(void *handle, const char *uri);
1.698 -
1.699 -/**
1.700 - * Closes a notification.
1.701 - *
1.702 - * This should be used only by the UI operation functions and part of the
1.703 - * core.
1.704 - *
1.705 - * @param type The notification type.
1.706 - * @param ui_handle The notification UI handle.
1.707 - */
1.708 -void purple_notify_close(PurpleNotifyType type, void *ui_handle);
1.709 -
1.710 -/**
1.711 - * Closes all notifications registered with the specified handle.
1.712 - *
1.713 - * @param handle The handle.
1.714 - */
1.715 -void purple_notify_close_with_handle(void *handle);
1.716 -
1.717 -/**
1.718 - * A wrapper for purple_notify_message that displays an information message.
1.719 - */
1.720 -#define purple_notify_info(handle, title, primary, secondary) \
1.721 - purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
1.722 - (primary), (secondary), NULL, NULL)
1.723 -
1.724 -/**
1.725 - * A wrapper for purple_notify_message that displays a warning message.
1.726 - */
1.727 -#define purple_notify_warning(handle, title, primary, secondary) \
1.728 - purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
1.729 - (primary), (secondary), NULL, NULL)
1.730 -
1.731 -/**
1.732 - * A wrapper for purple_notify_message that displays an error message.
1.733 - */
1.734 -#define purple_notify_error(handle, title, primary, secondary) \
1.735 - purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
1.736 - (primary), (secondary), NULL, NULL)
1.737 -
1.738 -/*@}*/
1.739 -
1.740 -/**************************************************************************/
1.741 -/** @name UI Registration Functions */
1.742 -/**************************************************************************/
1.743 -/*@{*/
1.744 -
1.745 -/**
1.746 - * Sets the UI operations structure to be used when displaying a
1.747 - * notification.
1.748 - *
1.749 - * @param ops The UI operations structure.
1.750 - */
1.751 -void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops);
1.752 -
1.753 -/**
1.754 - * Returns the UI operations structure to be used when displaying a
1.755 - * notification.
1.756 - *
1.757 - * @return The UI operations structure.
1.758 - */
1.759 -PurpleNotifyUiOps *purple_notify_get_ui_ops(void);
1.760 -
1.761 -/*@}*/
1.762 -
1.763 -/**************************************************************************/
1.764 -/** @name Notify Subsystem */
1.765 -/**************************************************************************/
1.766 -/*@{*/
1.767 -
1.768 -/**
1.769 - * Returns the notify subsystem handle.
1.770 - *
1.771 - * @return The notify subsystem handle.
1.772 - */
1.773 -void *purple_notify_get_handle(void);
1.774 -
1.775 -/**
1.776 - * Initializes the notify subsystem.
1.777 - */
1.778 -void purple_notify_init(void);
1.779 -
1.780 -/**
1.781 - * Uninitializes the notify subsystem.
1.782 - */
1.783 -void purple_notify_uninit(void);
1.784 -
1.785 -/*@}*/
1.786 -
1.787 -
1.788 -#ifdef __cplusplus
1.789 -}
1.790 -#endif
1.791 -
1.792 -#endif /* _PURPLE_NOTIFY_H_ */