pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Add purple_saved_presence_matches to enable searching in UIs
4 months ago, Gary Kramlich
8627951788d1
Add purple_saved_presence_matches to enable searching in UIs
Testing Done:
Consulted with Turtles and ran the unit tests under valgrind.
Reviewed at https://reviews.imfreedom.org/r/2942/
/* purple
*
* 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 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., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#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"
typedef
struct
_PurpleNotifyUserInfoEntry
PurpleNotifyUserInfoEntry
;
#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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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
*
* Since: 2.0.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.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.0
*/
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.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.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.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.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.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.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.0
*/
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.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.0
*/
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.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.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.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.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.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.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.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.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.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.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.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.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.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.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleNotifyUiOps
*
purple_notify_get_ui_ops
(
void
);
/**************************************************************************/
/* Notify Subsystem */
/**************************************************************************/
/**
* purple_notify_init:
*
* Initializes the notify subsystem.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_notify_init
(
void
);
/**
* purple_notify_uninit:
*
* Uninitializes the notify subsystem.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_notify_uninit
(
void
);
G_END_DECLS
#endif
/* PURPLE_NOTIFY_H */