annotate libpurple/notify.h @ 15827:eec0d0202ffd

merge of '9d227438376255715d0d778ce0a57734aed4c99a' and 'ebb919dd47f8edc3b1b82fdbc2d2a7764bc9ab6f'

/**
 * @file notify.h Notification API
 * @ingroup core
 *
 * gaim
 *
 * Gaim is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef _GAIM_NOTIFY_H_
#define _GAIM_NOTIFY_H_

#include <stdlib.h>
#include <glib-object.h>
#include <glib.h>

typedef struct _GaimNotifyUserInfoEntry	GaimNotifyUserInfoEntry;
typedef struct _GaimNotifyUserInfo	GaimNotifyUserInfo;

#include "connection.h"

/**
 * Notification close callbacks.
 */
typedef void  (*GaimNotifyCloseCallback) (gpointer user_data);


/**
 * Notification types.
 */
typedef enum
{
	GAIM_NOTIFY_MESSAGE = 0,   /**< Message notification.         */
	GAIM_NOTIFY_EMAIL,         /**< Single e-mail notification.   */
	GAIM_NOTIFY_EMAILS,        /**< Multiple e-mail notification. */
	GAIM_NOTIFY_FORMATTED,     /**< Formatted text.               */
	GAIM_NOTIFY_SEARCHRESULTS, /**< Buddy search results.         */
	GAIM_NOTIFY_USERINFO,      /**< Formatted userinfo text.      */
	GAIM_NOTIFY_URI            /**< URI notification or display.  */

} GaimNotifyType;


/**
 * Notification message types.
 */
typedef enum
{
	GAIM_NOTIFY_MSG_ERROR   = 0, /**< Error notification.       */
	GAIM_NOTIFY_MSG_WARNING,     /**< Warning notification.     */
	GAIM_NOTIFY_MSG_INFO         /**< Information notification. */

} GaimNotifyMsgType;


/**
 * The types of buttons
 */
typedef enum
{
	GAIM_NOTIFY_BUTTON_LABELED = 0,  /**< special use, see _button_add_labeled */
	GAIM_NOTIFY_BUTTON_CONTINUE = 1,
	GAIM_NOTIFY_BUTTON_ADD,
	GAIM_NOTIFY_BUTTON_INFO,
	GAIM_NOTIFY_BUTTON_IM,
	GAIM_NOTIFY_BUTTON_JOIN,
	GAIM_NOTIFY_BUTTON_INVITE
} GaimNotifySearchButtonType;


/**
 * Search results object.
 */
typedef struct
{
	GList *columns;        /**< List of the search column objects. */
	GList *rows;           /**< List of rows in the result. */
	GList *buttons;        /**< List of buttons to display. */

} GaimNotifySearchResults;

/**
 * Types of GaimNotifyUserInfoEntry objects
 */
typedef enum
{
	GAIM_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
	GAIM_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
	GAIM_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
} GaimNotifyUserInfoEntryType;

/**
 * Single column of a search result.
 */
typedef struct
{
	char *title; /**< Title of the column. */

} GaimNotifySearchColumn;


/**
 * Callback for a button in a search result.
 *
 * @param c         the GaimConnection passed to gaim_notify_searchresults
 * @param row       the contents of the selected row
 * @param user_data User defined data.
 */
typedef void (*GaimNotifySearchResultsCallback)(GaimConnection *c, GList *row,
												gpointer user_data);


/**
 * Definition of a button.
 */
typedef struct
{
	GaimNotifySearchButtonType type;
	GaimNotifySearchResultsCallback callback; /**< Function to be called when clicked. */
	char *label;                              /**< only for GAIM_NOTIFY_BUTTON_LABELED */
} GaimNotifySearchButton;


/**
 * Notification UI operations.
 */
typedef struct
{
	void *(*notify_message)(GaimNotifyMsgType type, const char *title,
	                        const char *primary, const char *secondary);

	void *(*notify_email)(GaimConnection *gc,
	                      const char *subject, const char *from,
	                      const char *to, const char *url);

	void *(*notify_emails)(GaimConnection *gc,
	                       size_t count, gboolean detailed,
	                       const char **subjects, const char **froms,
	                       const char **tos, const char **urls);

	void *(*notify_formatted)(const char *title, const char *primary,
	                          const char *secondary, const char *text);

	void *(*notify_searchresults)(GaimConnection *gc, const char *title,
	                              const char *primary, const char *secondary,
	                              GaimNotifySearchResults *results, gpointer user_data);

	void (*notify_searchresults_new_rows)(GaimConnection *gc,
	                                      GaimNotifySearchResults *results,
	                                      void *data);

	void *(*notify_userinfo)(GaimConnection *gc, const char *who,
	                         GaimNotifyUserInfo *user_info);

	void *(*notify_uri)(const char *uri);

	void (*close_notify)(GaimNotifyType type, void *ui_handle);

} GaimNotifyUiOps;


#ifdef __cplusplus
extern "C" {
#endif


/**************************************************************************/
/** Search results notification API                                       */
/**************************************************************************/
/*@{*/

/**
 * Displays results from a buddy search.  This can be, for example,
 * a window with a list of all found buddies, where you are given the
 * option of adding buddies to your buddy list.
 *
 * @param gc        The GaimConnection handle associated with the information.
 * @param title     The title of the message.  If this is NULL, the title
 *                  will be "Search Results."
 * @param primary   The main point of the message.
 * @param secondary The secondary information.
 * @param results   The GaimNotifySearchResults instance.
 * @param cb        The callback to call when the user closes
 *                  the notification.
 * @param user_data The data to pass to the close callback and any other
 *                  callback associated with a button.
 *
 * @return A UI-specific handle.
 */
void *gaim_notify_searchresults(GaimConnection *gc, const char *title,
								const char *primary, const char *secondary,
								GaimNotifySearchResults *results, GaimNotifyCloseCallback cb,
								gpointer user_data);

void gaim_notify_searchresults_free(GaimNotifySearchResults *results);

/**
 * Replace old rows with the new. Reuse an existing window.
 *
 * @param gc        The GaimConnection structure.
 * @param results   The GaimNotifySearchResults structure.
 * @param data      Data returned by the gaim_notify_searchresults().
 */
void gaim_notify_searchresults_new_rows(GaimConnection *gc,
										GaimNotifySearchResults *results,
										void *data);


/**
 * Adds a stock button that will be displayed in the search results dialog.
 *
 * @param results The search results object.
 * @param type    Type of the button. (TODO: Only one button of a given type can be displayed.)
 * @param cb      Function that will be called on the click event.
 */
void gaim_notify_searchresults_button_add(GaimNotifySearchResults *results,
										  GaimNotifySearchButtonType type,
										  GaimNotifySearchResultsCallback cb);


/**
 * Adds a plain labelled button that will be displayed in the search results dialog.
 * 
 * @param results The search results object
 * @param label   The label to display
 * @param cb      Function that will be called on the click event
 */
void gaim_notify_searchresults_button_add_labeled(GaimNotifySearchResults *results,
                                                  const char *label,
                                                  GaimNotifySearchResultsCallback cb);


/**
 * Returns a newly created search results object.
 *
 * @return The new search results object.
 */
GaimNotifySearchResults *gaim_notify_searchresults_new(void);

/**
 * Returns a newly created search result column object.
 *
 * @param title Title of the column. NOTE: Title will get g_strdup()ed.
 * 
 * @return The new search column object.
 */
GaimNotifySearchColumn *gaim_notify_searchresults_column_new(const char *title);

/**
 * Adds a new column to the search result object.
 *
 * @param results The result object to which the column will be added.
 * @param column The column that will be added to the result object.
 */
void gaim_notify_searchresults_column_add(GaimNotifySearchResults *results,
										  GaimNotifySearchColumn *column);

/**
 * Adds a new row of the results to the search results object.
 *
 * @param results The search results object.
 * @param row     The row of the results.
 */
void gaim_notify_searchresults_row_add(GaimNotifySearchResults *results,
									   GList *row);

/**
 * Returns a number of the rows in the search results object.
 * 
 * @param results The search results object.
 *
 * @return Number of the result rows.
 */
guint gaim_notify_searchresults_get_rows_count(GaimNotifySearchResults *results);

/**
 * Returns a number of the columns in the search results object.
 *
 * @param results The search results object.
 *
 * @return Number of the columns.
 */
guint gaim_notify_searchresults_get_columns_count(GaimNotifySearchResults *results);

/**
 * Returns a row of the results from the search results object.
 *
 * @param results The search results object.
 * @param row_id  Index of the row to be returned.
 *
 * @return Row of the results.
 */
GList *gaim_notify_searchresults_row_get(GaimNotifySearchResults *results,
										 unsigned int row_id);

/**
 * Returns a title of the search results object's column.
 * 
 * @param results   The search results object.
 * @param column_id Index of the column.
 *
 * @return Title of the column.
 */
char *gaim_notify_searchresults_column_get_title(GaimNotifySearchResults *results,
												 unsigned int column_id);

/*@}*/

/**************************************************************************/
/** @name Notification API                                                */
/**************************************************************************/
/*@{*/

/**
 * Displays a notification message to the user.
 *
 * @param handle    The plugin or connection handle.
 * @param type      The notification type.
 * @param title     The title of the message.
 * @param primary   The main point of the message.
 * @param secondary The secondary information.
 * @param cb        The callback to call when the user closes
 *                  the notification.
 * @param user_data The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *gaim_notify_message(void *handle, GaimNotifyMsgType type,
						  const char *title, const char *primary,
						  const char *secondary, GaimNotifyCloseCallback cb,
						  gpointer user_data);

/**
 * Displays a single e-mail notification to the user.
 *
 * @param handle    The plugin or connection handle.
 * @param subject   The subject of the e-mail.
 * @param from      The from address.
 * @param to        The destination address.
 * @param url       The URL where the message can be read.
 * @param cb        The callback to call when the user closes
 *                  the notification.
 * @param user_data The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *gaim_notify_email(void *handle, const char *subject,
						const char *from, const char *to,
						const char *url, GaimNotifyCloseCallback cb,
						gpointer user_data);

/**
 * Displays a notification for multiple e-mails to the user.
 *
 * @param handle    The plugin or connection handle.
 * @param count     The number of e-mails.
 * @param detailed  @c TRUE if there is information for each e-mail in the
 *                  arrays.
 * @param subjects  The array of subjects.
 * @param froms     The array of from addresses.
 * @param tos       The array of destination addresses.
 * @param urls      The URLs where the messages can be read.
 * @param cb        The callback to call when the user closes
 *                  the notification.
 * @param user_data The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *gaim_notify_emails(void *handle, size_t count, gboolean detailed,
						 const char **subjects, const char **froms,
						 const char **tos, const char **urls,
						 GaimNotifyCloseCallback cb, gpointer user_data);

/**
 * Displays a notification with formatted text.
 *
 * The text is essentially a stripped-down format of HTML, the same that
 * IMs may send.
 *
 * @param handle    The plugin or connection handle.
 * @param title     The title of the message.
 * @param primary   The main point of the message.
 * @param secondary The secondary information.
 * @param text      The formatted text.
 * @param cb        The callback to call when the user closes
 *                  the notification.
 * @param user_data The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *gaim_notify_formatted(void *handle, const char *title,
							const char *primary, const char *secondary,
							const char *text, GaimNotifyCloseCallback cb, gpointer user_data);

/**
 * Displays user information with formatted text, passing information giving
 * the connection and username from which the user information came.
 *
 * The text is essentially a stripped-down format of HTML, the same that
 * IMs may send.
 *
 * @param gc		         The GaimConnection handle associated with the information.
 * @param who				 The username associated with the information.
 * @param user_info          The GaimNotifyUserInfo which contains the information
 * @param cb                 The callback to call when the user closes
 *                           the notification.
 * @param user_data          The data to pass to the callback.
 *
 * @return A UI-specific handle.
 */
void *gaim_notify_userinfo(GaimConnection *gc, const char *who,
						   GaimNotifyUserInfo *user_info, GaimNotifyCloseCallback cb,
						   gpointer user_data);

/**
 * Create a new GaimNotifyUserInfo which is suitable for passing to gaim_notify_userinfo()
 *
 * @return A new GaimNotifyUserInfo, which the caller must destroy when done
 */
GaimNotifyUserInfo *gaim_notify_user_info_new(void);

/**
 * Destroy a GaimNotifyUserInfo
 *
 * @param user_info          The GaimNotifyUserInfo
 */
void gaim_notify_user_info_destroy(GaimNotifyUserInfo *user_info);

/**
 * Retrieve the array of GaimNotifyUserInfoEntry objects from a GaimNotifyUserInfo
 *
 * This GList may be manipulated directly with normal GList functions such as g_list_insert(). Only 
 * GaimNotifyUserInfoEntry are allowed in the list.  If a GaimNotifyUserInfoEntry item is added to the list,
 * it should not be g_free()'d by the caller; GaimNotifyUserInfo will g_free it when destroyed.
 *
 * To remove a GaimNotifyUserInfoEntry, use gaim_notify_user_info_remove_entry(). Do not use the GList directly.
 *
 * @param user_info          The GaimNotifyUserInfo
 *
 * @result                   A GList of GaimNotifyUserInfoEntry objects
 */
GList *gaim_notify_user_info_get_entries(GaimNotifyUserInfo *user_info);

/**
 * Create a textual representation of a GaimNotifyUserInfo, separating entries with newline
 *
 * @param user_info          The GaimNotifyUserInfo
 * @param newline            The separation character
 */
char *gaim_notify_user_info_get_text_with_newline(GaimNotifyUserInfo *user_info, const char *newline);

/**
 * Add a label/value pair to a GaimNotifyUserInfo object.
 * GaimNotifyUserInfo keeps track of the order in which pairs are added.
 *
 * @param user_info          The GaimNotifyUserInfo
 * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
 *                           If NULL, value will be displayed without a label.
 * @param value              The value, which might be displayed by a UI after the label.
 *                           If NULL, label will still be displayed; the UI should then treat label as independent
 *                           and not include a colon if it would otherwise.
 */
void gaim_notify_user_info_add_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);

/**
 * Prepend a label/value pair to a GaimNotifyUserInfo object
 *
 * @param user_info          The GaimNotifyUserInfo
 * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
 *                           If NULL, value will be displayed without a label.
 * @param value              The value, which might be displayed by a UI after the label.
 *                           If NULL, label will still be displayed; the UI should then treat label as independent
 *                           and not include a colon if it would otherwise.
 */
void gaim_notify_user_info_prepend_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);

/**
 * Remove a GaimNotifyUserInfoEntry from a GaimNotifyUserInfo object
 *
 * @param user_info          The GaimNotifyUserInfo
 * @param user_info_entry    The GaimNotifyUserInfoEntry
 */
void gaim_notify_user_info_remove_entry(GaimNotifyUserInfo *user_info, GaimNotifyUserInfoEntry *user_info_entry);
/**
 * Create a new GaimNotifyUserInfoEntry
 *
 * If added to a GaimNotifyUserInfo object, this should not be free()'d, as GaimNotifyUserInfo will do so
 * when destroyed.  gaim_notify_user_info_add_pair() and gaim_notify_user_info_prepend_pair() are convenience
 * methods for creating entries and adding them to a GaimNotifyUserInfo.
 *
 * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
 *                           If NULL, value will be displayed without a label.
 * @param value              The value, which might be displayed by a UI after the label.
 *                           If NULL, label will still be displayed; the UI should then treat label as independent
 *                           and not include a colon if it would otherwise.
 *
 * @result A new GaimNotifyUserInfoEntry
 */
GaimNotifyUserInfoEntry *gaim_notify_user_info_entry_new(const char *label, const char *value);

/**
 * Add a section break.  A UI might display this as a horizontal line.
 *
 * @param user_info          The GaimNotifyUserInfo
 */
void gaim_notify_user_info_add_section_break(GaimNotifyUserInfo *user_info);

/**
 * Add a section header.  A UI might display this in a different font from other text.
 *
 * @param user_info          The GaimNotifyUserInfo
 * @param label              The name of the section
 */
void gaim_notify_user_info_add_section_header(GaimNotifyUserInfo *user_info, const char *label);

/**
 * Remove the last item which was added to a GaimNotifyUserInfo. This could be used to remove a section header which is not needed.
 */
void gaim_notify_user_info_remove_last_item(GaimNotifyUserInfo *user_info);

/**
 * Get the label for a GaimNotifyUserInfoEntry
 *
 * @param user_info_entry     The GaimNotifyUserInfoEntry
 *
 * @result                    The label
 */
gchar *gaim_notify_user_info_entry_get_label(GaimNotifyUserInfoEntry *user_info_entry);

/**
 * Set the label for a GaimNotifyUserInfoEntry
 *
 * @param user_info_entry     The GaimNotifyUserInfoEntry
 * @param label			      The label
 */
void gaim_notify_user_info_entry_set_label(GaimNotifyUserInfoEntry *user_info_entry, const char *label);

/**
 * Get the value for a GaimNotifyUserInfoEntry
 *
 * @param user_info_entry     The GaimNotifyUserInfoEntry
 *
 * @result                    The value
 */
gchar *gaim_notify_user_info_entry_get_value(GaimNotifyUserInfoEntry *user_info_entry);

/**
 * Set the value for a GaimNotifyUserInfoEntry
 *
 * @param user_info_entry     The GaimNotifyUserInfoEntry
 * @param value				  The value
 */
void gaim_notify_user_info_entry_set_value(GaimNotifyUserInfoEntry *user_info_entry, const char *value);


/**
 * Get the type of a GaimNotifyUserInfoEntry
 *
 * @param user_info_entry     The GaimNotifyUserInfoEntry
 *
 * @result					  The GaimNotifyUserInfoEntryType
 */
GaimNotifyUserInfoEntryType gaim_notify_user_info_entry_get_type(GaimNotifyUserInfoEntry *user_info_entry);

/**
 * Set the type of a GaimNotifyUserInfoEntry
 *
 * @param user_info_entry     The GaimNotifyUserInfoEntry
 * @param					  The GaimNotifyUserInfoEntryType
 */
void gaim_notify_user_info_entry_set_type(GaimNotifyUserInfoEntry *user_info_entry,
										  GaimNotifyUserInfoEntryType type);

/**
 * Opens a URI or somehow presents it to the user.
 *
 * @param handle The plugin or connection handle.
 * @param uri    The URI to display or go to.
 *
 * @return A UI-specific handle, if any. This may only be presented if
 *         the UI code displays a dialog instead of a webpage, or something
 *         similar.
 */
void *gaim_notify_uri(void *handle, const char *uri);

/**
 * Closes a notification.
 *
 * This should be used only by the UI operation functions and part of the
 * core.
 *
 * @param type      The notification type.
 * @param ui_handle The notification UI handle.
 */
void gaim_notify_close(GaimNotifyType type, void *ui_handle);

/**
 * Closes all notifications registered with the specified handle.
 *
 * @param handle The handle.
 */
void gaim_notify_close_with_handle(void *handle);

/**
 * A wrapper for gaim_notify_message that displays an information message.
 */
#define gaim_notify_info(handle, title, primary, secondary) \
	gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \
						(primary), (secondary), NULL, NULL)

/**
 * A wrapper for gaim_notify_message that displays a warning message.
 */
#define gaim_notify_warning(handle, title, primary, secondary) \
	gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \
						(primary), (secondary), NULL, NULL)

/**
 * A wrapper for gaim_notify_message that displays an error message.
 */
#define gaim_notify_error(handle, title, primary, secondary) \
	gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \
						(primary), (secondary), NULL, NULL)

/*@}*/

/**************************************************************************/
/** @name UI Registration Functions                                       */
/**************************************************************************/
/*@{*/

/**
 * Sets the UI operations structure to be used when displaying a
 * notification.
 *
 * @param ops The UI operations structure.
 */
void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops);

/**
 * Returns the UI operations structure to be used when displaying a
 * notification.
 *
 * @return The UI operations structure.
 */
GaimNotifyUiOps *gaim_notify_get_ui_ops(void);

/*@}*/

/**************************************************************************/
/** @name Notify Subsystem                                         */
/**************************************************************************/
/*@{*/

/**
 * Returns the notify subsystem handle.
 *
 * @return The notify subsystem handle.
 */
void *gaim_notify_get_handle(void);

/**
 * Initializes the notify subsystem.
 */
void gaim_notify_init(void);

/**
 * Uninitializes the notify subsystem.
 */
void gaim_notify_uninit(void);

/*@}*/


#ifdef __cplusplus
}
#endif

#endif /* _GAIM_NOTIFY_H_ */