pidgin/pidgin

Update the demo protocol plugin to not depend on conversation names
default tip
37 hours ago, Gary Kramlich
f755b10c05a3
Update the demo protocol plugin to not depend on conversation names

We're starting to phase out conversation names as they don't work well with
modern stuff. So this goes ahead and fixes the not interactions in the demo
protocol.

I also generated the echo message in the send_message_async rather than in the
callback.

Testing Done:
Ran the turtles and send some messages to Echo on the demo protocol.

Reviewed at https://reviews.imfreedom.org/r/3135/
/*
* Purple - Internet Messaging Library
* Copyright (C) Pidgin Developers <devel@pidgin.im>
*
* Purple 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 library 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 library 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 library; if not, see <https://www.gnu.org/licenses/>.
*/
#if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
# error "only <purple.h> may be included directly"
#endif
#ifndef PURPLE_NOTIFY_H
#define PURPLE_NOTIFY_H
#include <stdlib.h>
#include <glib-object.h>
#include <glib.h>
#include "purpleversion.h"
/**
* PurpleNotifyUserInfoEntry:
*
* A entry for the user information.
*
* Since: 2.0
*/
typedef struct _PurpleNotifyUserInfoEntry PurpleNotifyUserInfoEntry;
/**
* PurpleNotifyUserInfo:
*
* A collection of user information entries.
*
* Since: 2.0
*/
#define PURPLE_TYPE_NOTIFY_USER_INFO (purple_notify_user_info_get_type())
typedef struct _PurpleNotifyUserInfo PurpleNotifyUserInfo;
#define PURPLE_TYPE_NOTIFY_SEARCH_BUTTON (purple_notify_search_button_get_type())
typedef struct _PurpleNotifySearchButton PurpleNotifySearchButton;
/**
* PurpleNotifySearchColumn:
*
* Single column of a search result.
*/
typedef struct _PurpleNotifySearchColumn PurpleNotifySearchColumn;
#include "connection.h"
#include "request.h"
typedef struct _PurpleNotifySearchResults PurpleNotifySearchResults;
#define PURPLE_TYPE_NOTIFY_UI_OPS (purple_notify_ui_ops_get_type())
typedef struct _PurpleNotifyUiOps PurpleNotifyUiOps;
/**
* PurpleNotifyCloseCallback:
* @user_data: User specified data.
*
* Notification close callbacks.
*/
typedef void (*PurpleNotifyCloseCallback) (gpointer user_data);
/**
* PurpleNotifyType:
* @PURPLE_NOTIFY_MESSAGE: Message notification.
* @PURPLE_NOTIFY_FORMATTED: Formatted text.
* @PURPLE_NOTIFY_SEARCHRESULTS: Buddy search results.
* @PURPLE_NOTIFY_USERINFO: Formatted userinfo text.
* @PURPLE_NOTIFY_URI: URI notification or display.
*
* Notification types.
*/
typedef enum
{
PURPLE_NOTIFY_MESSAGE = 0,
PURPLE_NOTIFY_FORMATTED,
PURPLE_NOTIFY_SEARCHRESULTS,
PURPLE_NOTIFY_USERINFO,
PURPLE_NOTIFY_URI
} PurpleNotifyType;
/**
* PurpleNotifyMessageType:
* @PURPLE_NOTIFY_MSG_ERROR: Error notification.
* @PURPLE_NOTIFY_MSG_WARNING: Warning notification.
* @PURPLE_NOTIFY_MSG_INFO: Information notification.
*
* Notification message types.
*/
typedef enum
{
PURPLE_NOTIFY_MSG_ERROR = 0,
PURPLE_NOTIFY_MSG_WARNING,
PURPLE_NOTIFY_MSG_INFO
} PurpleNotifyMessageType;
/**
* PurpleNotifySearchButtonType:
* @PURPLE_NOTIFY_BUTTON_LABELED: special use, see
* purple_notify_searchresults_button_add_labeled()
* @PURPLE_NOTIFY_BUTTON_CONTINUE: A continue button.
* @PURPLE_NOTIFY_BUTTON_ADD: An add button.
* @PURPLE_NOTIFY_BUTTON_INFO: An info button.
* @PURPLE_NOTIFY_BUTTON_IM: An IM button.
* @PURPLE_NOTIFY_BUTTON_JOIN: A join button.
* @PURPLE_NOTIFY_BUTTON_INVITE: An invite button.
*
* Constant values to define the type of buttons to use in a request dialog.
* These are used by user interfaces to label and possibly add an icon to the
* button.
*/
typedef enum
{
PURPLE_NOTIFY_BUTTON_LABELED = 0,
PURPLE_NOTIFY_BUTTON_CONTINUE = 1,
PURPLE_NOTIFY_BUTTON_ADD,
PURPLE_NOTIFY_BUTTON_INFO,
PURPLE_NOTIFY_BUTTON_IM,
PURPLE_NOTIFY_BUTTON_JOIN,
PURPLE_NOTIFY_BUTTON_INVITE
} PurpleNotifySearchButtonType;
/**
* PurpleNotifySearchResults:
* @columns: List of the search column objects.
* @rows: List of rows in the result.
* @buttons: List of buttons to display.
*
* Search results object.
*/
struct _PurpleNotifySearchResults
{
GList *columns;
GList *rows;
GList *buttons;
};
/**
* PurpleNotifyUserInfoEntryType:
* @PURPLE_NOTIFY_USER_INFO_ENTRY_PAIR: A label and its value.
* @PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK: Separates two sections.
* @PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER: Create a header for the
* current section.
*
* Types of PurpleNotifyUserInfoEntry objects
*/
typedef enum
{
PURPLE_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
} PurpleNotifyUserInfoEntryType;
/**
* PurpleNotifySearchResultsCallback:
* @c: the PurpleConnection passed to purple_notify_searchresults
* @row: the contents of the selected row
* @user_data: User defined data.
*
* Callback for a button in a search result.
*/
typedef void (*PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row,
gpointer user_data);
/**
* PurpleNotifySearchButton:
* @type: The type of search button that will be used.
* @callback: Function to be called when clicked.
* @label: only for PURPLE_NOTIFY_BUTTON_LABELED
*
* Definition of a button.
*/
struct _PurpleNotifySearchButton
{
PurpleNotifySearchButtonType type;
PurpleNotifySearchResultsCallback callback;
char *label;
};
/**
* PurpleNotifyUiOps:
* @notify_message: UI op for purple_notify_message().
* @notify_formatted: UI op for purple_notify_formatted().
* @notify_searchresults: UI op for purple_notify_searchresults().
* @notify_searchresults_new_rows: UI op for
* purple_notify_searchresults_new_rows().
* @notify_userinfo: UI op for purple_notify_userinfo().
* @notify_uri: UI op for purple_notify_uri().
* @close_notify: UI op for purple_notify_close() and
* purple_notify_close_with_handle().
*
* Notification UI operations.
*/
struct _PurpleNotifyUiOps
{
void *(*notify_message)(PurpleNotifyMessageType type, const char *title,
const char *primary, const char *secondary,
PurpleRequestCommonParameters *cpar);
void *(*notify_formatted)(const char *title, const char *primary,
const char *secondary, const char *text);
void *(*notify_searchresults)(PurpleConnection *gc, const char *title,
const char *primary, const char *secondary,
PurpleNotifySearchResults *results, gpointer user_data);
void (*notify_searchresults_new_rows)(PurpleConnection *gc,
PurpleNotifySearchResults *results,
void *data);
void *(*notify_userinfo)(PurpleConnection *gc, const char *who,
PurpleNotifyUserInfo *user_info);
void *(*notify_uri)(const char *uri);
void (*close_notify)(PurpleNotifyType type, void *ui_handle);
/*< private >*/
void (*_purple_reserved1)(void);
void (*_purple_reserved2)(void);
void (*_purple_reserved3)(void);
void (*_purple_reserved4)(void);
};
G_BEGIN_DECLS
/**************************************************************************/
/* Search results notification API */
/**************************************************************************/
/**
* purple_notify_searchresults:
* @gc: The PurpleConnection handle associated with the information.
* @title: The title of the message. If this is NULL, the title
* will be "Search Results."
* @primary: The main point of the message.
* @secondary: The secondary information.
* @results: The PurpleNotifySearchResults instance.
* @cb: (scope call): The callback to call when the user closes
* the notification.
* @user_data: The data to pass to the close callback and any other
* callback associated with a button.
*
* 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.
*
* Returns: A UI-specific handle.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void *purple_notify_searchresults(PurpleConnection *gc, const char *title, const char *primary, const char *secondary, PurpleNotifySearchResults *results, PurpleNotifyCloseCallback cb, gpointer user_data);
/**
* purple_notify_searchresults_free:
* @results: The PurpleNotifySearchResults to free.
*
* Frees a PurpleNotifySearchResults object.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_searchresults_free(PurpleNotifySearchResults *results);
/**
* purple_notify_searchresults_new_rows:
* @gc: The PurpleConnection structure.
* @results: The PurpleNotifySearchResults structure.
* @data: Data returned by the purple_notify_searchresults().
*
* Replace old rows with the new. Reuse an existing window.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_searchresults_new_rows(PurpleConnection *gc, PurpleNotifySearchResults *results, void *data);
/**
* purple_notify_searchresults_button_add:
* @results: The search results object.
* @type: Type of the button. (TODO: Only one button of a given type
* can be displayed.)
* @cb: (scope call): Function that will be called on the click event.
*
* Adds a stock button that will be displayed in the search results dialog.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_searchresults_button_add(PurpleNotifySearchResults *results, PurpleNotifySearchButtonType type, PurpleNotifySearchResultsCallback cb);
/**
* purple_notify_searchresults_button_add_labeled:
* @results: The search results object
* @label: The label to display
* @cb: (scope call): Function that will be called on the click event
*
* Adds a plain labelled button that will be displayed in the search results
* dialog.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_searchresults_button_add_labeled(PurpleNotifySearchResults *results, const char *label, PurpleNotifySearchResultsCallback cb);
/**
* purple_notify_searchresults_new:
*
* Returns a newly created search results object.
*
* Returns: (transfer full): The new search results object.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleNotifySearchResults *purple_notify_searchresults_new(void);
/**
* purple_notify_searchresults_column_new:
* @title: Title of the column. NOTE: Title will get g_strdup()ed.
*
* Returns a newly created search result column object. The column defaults
* to being visible.
*
* Returns: (transfer full): The new search column object.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleNotifySearchColumn *purple_notify_searchresults_column_new(const char *title);
/**
* purple_notify_searchresult_column_get_title:
* @column: The search column object.
*
* Returns the title of the column
*
* Returns: The title of the column
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
const char *purple_notify_searchresult_column_get_title(const PurpleNotifySearchColumn *column);
/**
* purple_notify_searchresult_column_set_visible:
* @column: The search column object.
* @visible: TRUE if visible, or FALSE if not.
*
* Sets whether or not a search result column is visible.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
void purple_notify_searchresult_column_set_visible(PurpleNotifySearchColumn *column, gboolean visible);
/**
* purple_notify_searchresult_column_is_visible:
* @column: The search column object.
*
* Returns whether or not a search result column is visible.
*
* Returns: TRUE if the search result column is visible. FALSE otherwise.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
gboolean purple_notify_searchresult_column_is_visible(const PurpleNotifySearchColumn *column);
/**
* purple_notify_searchresults_column_add:
* @results: The result object to which the column will be added.
* @column: The column that will be added to the result object.
*
* Adds a new column to the search result object.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results, PurpleNotifySearchColumn *column);
/**
* purple_notify_searchresults_row_add:
* @results: The search results object.
* @row: (element-type utf8) (transfer full): The row of the results.
*
* Adds a new row of the results to the search results object.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_searchresults_row_add(PurpleNotifySearchResults *results, GList *row);
/**************************************************************************/
/* Notification API */
/**************************************************************************/
/**
* purple_notify_message:
* @handle: The plugin or connection handle.
* @type: The notification type.
* @title: The title of the message.
* @primary: The main point of the message.
* @secondary: The secondary information.
* @cpar: The #PurpleRequestCommonParameters associated with this
* request, or %NULL if none is.
* @cb: (scope call): The callback to call when the user closes
* the notification.
* @user_data: The data to pass to the callback.
*
* Displays a notification message to the user.
*
* Returns: A UI-specific handle.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void *purple_notify_message(void *handle, PurpleNotifyMessageType type, const char *title, const char *primary, const char *secondary, PurpleRequestCommonParameters *cpar, PurpleNotifyCloseCallback cb, gpointer user_data);
/**
* purple_notify_formatted:
* @handle: The plugin or connection handle.
* @title: The title of the message.
* @primary: The main point of the message.
* @secondary: The secondary information.
* @text: The formatted text.
* @cb: (scope call): The callback to call when the user closes
* the notification.
* @user_data: The data to pass to the callback.
*
* Displays a notification with formatted text.
*
* The text is essentially a stripped-down format of HTML, the same that
* IMs may send.
*
* Returns: A UI-specific handle.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void *purple_notify_formatted(void *handle, const char *title, const char *primary, const char *secondary, const char *text, PurpleNotifyCloseCallback cb, gpointer user_data);
/**
* purple_notify_userinfo:
* @gc: The PurpleConnection handle associated with the information.
* @who: The username associated with the information.
* @user_info: The PurpleNotifyUserInfo which contains the information
* @cb: (scope call): The callback to call when the user closes the
* notification.
* @user_data: The data to pass to the callback.
*
* 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.
*
* Returns: A UI-specific handle.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void *purple_notify_userinfo(PurpleConnection *gc, const char *who, PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb, gpointer user_data);
/**
* purple_notify_search_button_get_type:
*
* Returns: The #GType for #PurpleNotifiySearchButton boxed structure.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
GType purple_notify_search_button_get_type(void);
/**
* purple_notify_user_info_get_type:
*
* Returns: The #GType for the #PurpleNotifyUserInfo boxed structure.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
GType purple_notify_user_info_get_type(void);
/**
* purple_notify_user_info_new:
*
* Create a new PurpleNotifyUserInfo which is suitable for passing to
* purple_notify_userinfo()
*
* Returns: A new PurpleNotifyUserInfo, which the caller must destroy when done
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleNotifyUserInfo *purple_notify_user_info_new(void);
/**
* purple_notify_user_info_destroy:
* @user_info: The PurpleNotifyUserInfo
*
* Destroy a PurpleNotifyUserInfo
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info);
/**
* purple_notify_user_info_get_entries:
* @user_info: The PurpleNotifyUserInfo
*
* Retrieve the array of PurpleNotifyUserInfoEntry objects from a
* PurpleNotifyUserInfo
*
* This GQueue may be manipulated directly with normal GQueue functions such
* as g_queue_push_tail(). Only PurpleNotifyUserInfoEntry are allowed in the
* queue. If a PurpleNotifyUserInfoEntry item is added to the queue, it
* should not be freed by the caller; PurpleNotifyUserInfo will free it when
* destroyed.
*
* To remove a PurpleNotifyUserInfoEntry, use
* purple_notify_user_info_remove_entry(). Do not use the GQueue directly.
*
* Returns: (transfer none): A GQueue of PurpleNotifyUserInfoEntry objects.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
GQueue *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info);
/**
* purple_notify_user_info_get_text_with_newline:
* @user_info: The PurpleNotifyUserInfo
* @newline: The separation character
*
* Create a textual representation of a PurpleNotifyUserInfo, separating
* entries with newline
*
* Returns: (transfer full): The text.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline);
/**
* purple_notify_user_info_add_pair_html:
* @user_info: The PurpleNotifyUserInfo
* @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.
* @value: The value, which might be displayed by a UI after the label. This
* should be valid HTML. If you want to insert plaintext then use
* purple_notify_user_info_add_pair_plaintext(), instead. If this is
* %NULL the label will still be displayed; the UI should treat label as
* independent and not include a colon if it would otherwise.
*
* Add a label/value pair to a #PurpleNotifyUserInfo object.
* #PurpleNotifyUserInfo keeps track of the order in which pairs are added.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
void purple_notify_user_info_add_pair_html(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_add_pair_plaintext:
* @user_info: The PurpleNotifyUserInfo
* @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.
* @value: The value, which might be displayed by a UI after the label. This
* will be escaped to produce valid HTML. If you want to insert HTML
* then use purple_notify_user_info_add_pair_html(), instead. If this is
* %NULL the label will still be displayed; the UI should treat label as
* independent and not include a colon if it would otherwise.
*
* Add a label/value pair to a #PurpleNotifyUserInfo object.
* #PurpleNotifyUserInfo keeps track of the order in which pairs are added.
*
* Like purple_notify_user_info_add_pair_html(), but value should be plaintext
* and will be escaped using g_markup_escape_text().
*
* Since: 2.8
*/
PURPLE_AVAILABLE_IN_2_8
void purple_notify_user_info_add_pair_plaintext(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_prepend_pair_html:
* @user_info: The PurpleNotifyUserInfo
* @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.
* @value: The value, which might be displayed by a UI after the label. This
* should be valid HTML. If you want to insert plaintext then use
* purple_notify_user_info_prepend_pair_plaintext(), instead. If this is
* %NULL the label will still be displayed; the UI should treat label as
* independent and not include a colon if it would otherwise.
*
* Like purple_notify_user_info_add_pair_html(), but the pair is inserted
* at the beginning of the list.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
void purple_notify_user_info_prepend_pair_html(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_prepend_pair_plaintext:
* @user_info: The PurpleNotifyUserInfo
* @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.
* @value: The value, which might be displayed by a UI after the label. This
* will be escaped to produce valid HTML. If you want to insert HTML
* then use purple_notify_user_info_prepend_pair_html(), instead. If
* this is %NULL the label will still be displayed; the UI should treat
* label as independent and not include a colon if it would otherwise.
*
* Like purple_notify_user_info_prepend_pair_html(), but value should be
* plaintext and will be escaped using g_markup_escape_text().
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
void purple_notify_user_info_prepend_pair_plaintext(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_remove_entry:
* @user_info: The PurpleNotifyUserInfo
* @user_info_entry: The PurpleNotifyUserInfoEntry
*
* Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object
* without freeing the entry.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry);
/**
* purple_notify_user_info_entry_new:
* @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.
* @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.
*
* Create a new PurpleNotifyUserInfoEntry
*
* If added to a PurpleNotifyUserInfo object, this should not be free()'d,
* as PurpleNotifyUserInfo will do so when destroyed.
* purple_notify_user_info_add_pair_html(),
* purple_notify_user_info_add_pair_plaintext(),
* purple_notify_user_info_prepend_pair_html() and
* purple_notify_user_info_prepend_pair_plaintext() are convenience
* methods for creating entries and adding them to a PurpleNotifyUserInfo.
*
* Returns: (transfer full): A new PurpleNotifyUserInfoEntry
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleNotifyUserInfoEntry *purple_notify_user_info_entry_new(const char *label, const char *value);
/**
* purple_notify_user_info_entry_destroy:
* @user_info_entry: The PurpleNotifyUserInfoEntry
*
* Destroy a PurpleNotifyUserInfoEntry
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
void purple_notify_user_info_entry_destroy(PurpleNotifyUserInfoEntry *user_info_entry);
/**
* purple_notify_user_info_add_section_break:
* @user_info: The PurpleNotifyUserInfo
*
* Add a section break. A UI might display this as a horizontal line.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info);
/**
* purple_notify_user_info_prepend_section_break:
* @user_info: The PurpleNotifyUserInfo
*
* Prepend a section break. A UI might display this as a horizontal line.
*
* Since: 2.5
*/
PURPLE_AVAILABLE_IN_2_5
void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info);
/**
* purple_notify_user_info_add_section_header:
* @user_info: The PurpleNotifyUserInfo
* @label: The name of the section
*
* Add a section header. A UI might display this in a different font
* from other text.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label);
/**
* purple_notify_user_info_prepend_section_header:
* @user_info: The PurpleNotifyUserInfo
* @label: The name of the section
*
* Prepend a section header. A UI might display this in a different font
* from other text.
*
* Since: 2.5
*/
PURPLE_AVAILABLE_IN_2_5
void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label);
/**
* purple_notify_user_info_remove_last_item:
* @user_info: The PurpleNotifyUserInfo
*
* Remove the last item which was added to a PurpleNotifyUserInfo. This
* could be used to remove a section header which is not needed.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info);
/**
* purple_notify_user_info_entry_get_label:
* @user_info_entry: The PurpleNotifyUserInfoEntry
*
* Get the label for a PurpleNotifyUserInfoEntry
*
* Returns: The label
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry);
/**
* purple_notify_user_info_entry_set_label:
* @user_info_entry: The PurpleNotifyUserInfoEntry
* @label: The label
*
* Set the label for a PurpleNotifyUserInfoEntry
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label);
/**
* purple_notify_user_info_entry_get_value:
* @user_info_entry: The PurpleNotifyUserInfoEntry
*
* Get the value for a PurpleNotifyUserInfoEntry
*
* Returns: The value
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
const gchar *purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry);
/**
* purple_notify_user_info_entry_set_value:
* @user_info_entry: The PurpleNotifyUserInfoEntry
* @value: The value
*
* Set the value for a PurpleNotifyUserInfoEntry
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value);
/**
* purple_notify_user_info_entry_get_entry_type:
* @user_info_entry: The PurpleNotifyUserInfoEntry
*
* Get the type of a PurpleNotifyUserInfoEntry
*
* Returns: The PurpleNotifyUserInfoEntryType
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_entry_type(
PurpleNotifyUserInfoEntry *user_info_entry);
/**
* purple_notify_user_info_entry_set_entry_type:
* @user_info_entry: The PurpleNotifyUserInfoEntry
* @type: The PurpleNotifyUserInfoEntryType
*
* Set the type of a PurpleNotifyUserInfoEntry
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
void purple_notify_user_info_entry_set_entry_type(
PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type);
/**
* purple_notify_uri:
* @handle: The plugin or connection handle.
* @uri: The URI to display or go to.
*
* Opens a URI or somehow presents it to the user.
*
* Returns: 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.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void *purple_notify_uri(void *handle, const char *uri);
/**
* purple_notify_is_valid_ui_handle:
* @ui_handle: The UI handle.
* @type: The pointer to variable, where request type may be stored
* (may be %NULL).
*
* Checks, if passed UI handle is valid.
*
* Returns: TRUE, if handle is valid, FALSE otherwise.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
gboolean
purple_notify_is_valid_ui_handle(void *ui_handle, PurpleNotifyType *type);
/**
* purple_notify_close:
* @type: The notification type.
* @ui_handle: The notification UI handle.
*
* Closes a notification.
*
* This should be used only by the UI operation functions and part of the
* core.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_close(PurpleNotifyType type, void *ui_handle);
/**
* purple_notify_close_with_handle:
* @handle: The handle.
*
* Closes all notifications registered with the specified handle.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_close_with_handle(void *handle);
/**
* purple_notify_info:
* @handle: The plugin or connection handle.
* @title: The title of the message.
* @primary: The main point of the message.
* @secondary: The secondary information.
* @cpar: The #PurpleRequestCommonParameters associated with this request, or
* %NULL if none is.
*
* A wrapper for purple_notify_message() that displays an information message.
*/
#define purple_notify_info(handle, title, primary, secondary, cpar) \
purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
(primary), (secondary), (cpar), NULL, NULL)
/**
* purple_notify_warning:
* @handle: The plugin or connection handle.
* @title: The title of the message.
* @primary: The main point of the message.
* @secondary: The secondary information.
* @cpar: The #PurpleRequestCommonParameters associated with this request, or
* %NULL if none is.
*
* A wrapper for purple_notify_message() that displays a warning message.
*/
#define purple_notify_warning(handle, title, primary, secondary, cpar) \
purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
(primary), (secondary), (cpar), NULL, NULL)
/**
* purple_notify_error:
* @handle: The plugin or connection handle.
* @title: The title of the message.
* @primary: The main point of the message.
* @secondary: The secondary information.
* @cpar: The #PurpleRequestCommonParameters associated with this request, or
* %NULL if none is.
*
* A wrapper for purple_notify_message() that displays an error message.
*/
#define purple_notify_error(handle, title, primary, secondary, cpar) \
purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
(primary), (secondary), (cpar), NULL, NULL)
/**************************************************************************/
/* UI Registration Functions */
/**************************************************************************/
/**
* purple_notify_ui_ops_get_type:
*
* Returns: The #GType for the #PurpleNotifyUiOps boxed structure.
*
* Since: 3.0
*/
PURPLE_AVAILABLE_IN_3_0
GType purple_notify_ui_ops_get_type(void);
/**
* purple_notify_set_ui_ops:
* @ops: The UI operations structure.
*
* Sets the UI operations structure to be used when displaying a
* notification.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops);
/**
* purple_notify_get_ui_ops:
*
* Returns the UI operations structure to be used when displaying a
* notification.
*
* Returns: The UI operations structure.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleNotifyUiOps *purple_notify_get_ui_ops(void);
/**************************************************************************/
/* Notify Subsystem */
/**************************************************************************/
/**
* purple_notify_init:
*
* Initializes the notify subsystem.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_init(void);
/**
* purple_notify_uninit:
*
* Uninitializes the notify subsystem.
*
* Since: 2.0
*/
PURPLE_AVAILABLE_IN_ALL
void purple_notify_uninit(void);
G_END_DECLS
#endif /* PURPLE_NOTIFY_H */