notify.h File Reference

Notification API. More...

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

Include dependency graph for notify.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	PurpleNotifySearchResults
	Search results object. More...
struct	PurpleNotifySearchColumn
	Single column of a search result. More...
struct	PurpleNotifySearchButton
	Definition of a button. More...
struct	PurpleNotifyUiOps
	Notification UI operations. More...
Notification API
#define	purple_notify_info(handle, title, primary, secondary)
	A wrapper for purple_notify_message that displays an information message.
#define	purple_notify_warning(handle, title, primary, secondary)
	A wrapper for purple_notify_message that displays a warning message.
#define	purple_notify_error(handle, title, primary, secondary)
	A wrapper for purple_notify_message that displays an error message.
void *	purple_notify_message (void handle, PurpleNotifyMsgType type, const char title, const char primary, const char secondary, PurpleNotifyCloseCallback cb, gpointer user_data)
	Displays a notification message to the user.
void *	purple_notify_email (void handle, const char subject, const char from, const char to, const char *url, PurpleNotifyCloseCallback cb, gpointer user_data)
	Displays a single email notification to the user.
void *	purple_notify_emails (void handle, size_t count, gboolean detailed, const char subjects, const char froms, const char tos, const char *urls, PurpleNotifyCloseCallback cb, gpointer user_data)
	Displays a notification for multiple emails to the user.
void *	purple_notify_formatted (void handle, const char title, const char primary, const char secondary, const char *text, PurpleNotifyCloseCallback cb, gpointer user_data)
	Displays a notification with formatted text.
void *	purple_notify_userinfo (PurpleConnection gc, const char who, PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb, gpointer user_data)
	Displays user information with formatted text, passing information giving the connection and username from which the user information came.
PurpleNotifyUserInfo *	purple_notify_user_info_new (void)
	Create a new PurpleNotifyUserInfo which is suitable for passing to purple_notify_userinfo().
void	purple_notify_user_info_destroy (PurpleNotifyUserInfo *user_info)
	Destroy a PurpleNotifyUserInfo.
GList *	purple_notify_user_info_get_entries (PurpleNotifyUserInfo *user_info)
	Retrieve the array of PurpleNotifyUserInfoEntry objects from a PurpleNotifyUserInfo.
char *	purple_notify_user_info_get_text_with_newline (PurpleNotifyUserInfo user_info, const char newline)
	Create a textual representation of a PurpleNotifyUserInfo, separating entries with newline.
void	purple_notify_user_info_add_pair (PurpleNotifyUserInfo user_info, const char label, const char *value)
	Add a label/value pair to a PurpleNotifyUserInfo object.
void	purple_notify_user_info_prepend_pair (PurpleNotifyUserInfo user_info, const char label, const char *value)
	Prepend a label/value pair to a PurpleNotifyUserInfo object.
void	purple_notify_user_info_remove_entry (PurpleNotifyUserInfo user_info, PurpleNotifyUserInfoEntry user_info_entry)
	Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object without freeing the entry.
PurpleNotifyUserInfoEntry *	purple_notify_user_info_entry_new (const char label, const char value)
	Create a new PurpleNotifyUserInfoEntry.
void	purple_notify_user_info_add_section_break (PurpleNotifyUserInfo *user_info)
	Add a section break.
void	purple_notify_user_info_prepend_section_break (PurpleNotifyUserInfo *user_info)
	Prepend a section break.
void	purple_notify_user_info_add_section_header (PurpleNotifyUserInfo user_info, const char label)
	Add a section header.
void	purple_notify_user_info_prepend_section_header (PurpleNotifyUserInfo user_info, const char label)
	Prepend a section header.
void	purple_notify_user_info_remove_last_item (PurpleNotifyUserInfo *user_info)
	Remove the last item which was added to a PurpleNotifyUserInfo.
const gchar *	purple_notify_user_info_entry_get_label (PurpleNotifyUserInfoEntry *user_info_entry)
	Get the label for a PurpleNotifyUserInfoEntry.
void	purple_notify_user_info_entry_set_label (PurpleNotifyUserInfoEntry user_info_entry, const char label)
	Set the label for a PurpleNotifyUserInfoEntry.
const gchar *	purple_notify_user_info_entry_get_value (PurpleNotifyUserInfoEntry *user_info_entry)
	Get the value for a PurpleNotifyUserInfoEntry.
void	purple_notify_user_info_entry_set_value (PurpleNotifyUserInfoEntry user_info_entry, const char value)
	Set the value for a PurpleNotifyUserInfoEntry.
PurpleNotifyUserInfoEntryType	purple_notify_user_info_entry_get_type (PurpleNotifyUserInfoEntry *user_info_entry)
	Get the type of a PurpleNotifyUserInfoEntry.
void	purple_notify_user_info_entry_set_type (PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type)
	Set the type of a PurpleNotifyUserInfoEntry.
void *	purple_notify_uri (void handle, const char uri)
	Opens a URI or somehow presents it to the user.
void	purple_notify_close (PurpleNotifyType type, void *ui_handle)
	Closes a notification.
void	purple_notify_close_with_handle (void *handle)
	Closes all notifications registered with the specified handle.
Typedefs
typedef struct _PurpleNotifyUserInfoEntry	PurpleNotifyUserInfoEntry
typedef struct _PurpleNotifyUserInfo	PurpleNotifyUserInfo
typedef void(*	PurpleNotifyCloseCallback )(gpointer user_data)
	Notification close callbacks.
typedef void(*	PurpleNotifySearchResultsCallback )(PurpleConnection c, GList row, gpointer user_data)
	Callback for a button in a search result.
Enumerations
enum	PurpleNotifyType { PURPLE_NOTIFY_MESSAGE = 0, PURPLE_NOTIFY_EMAIL, PURPLE_NOTIFY_EMAILS, PURPLE_NOTIFY_FORMATTED, PURPLE_NOTIFY_SEARCHRESULTS, PURPLE_NOTIFY_USERINFO, PURPLE_NOTIFY_URI }
	Notification types. More...
enum	PurpleNotifyMsgType { PURPLE_NOTIFY_MSG_ERROR = 0, PURPLE_NOTIFY_MSG_WARNING, PURPLE_NOTIFY_MSG_INFO }
	Notification message types. More...
enum	PurpleNotifySearchButtonType { 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 }
	The types of buttons. More...
enum	PurpleNotifyUserInfoEntryType { PURPLE_NOTIFY_USER_INFO_ENTRY_PAIR = 0, PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK, PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER }
	Types of PurpleNotifyUserInfoEntry objects.
Functions

void *	purple_notify_searchresults (PurpleConnection gc, const char title, const char primary, const char secondary, PurpleNotifySearchResults *results, PurpleNotifyCloseCallback cb, gpointer user_data)
	Search results notification API.
void	purple_notify_searchresults_free (PurpleNotifySearchResults *results)
	Frees a PurpleNotifySearchResults object.
void	purple_notify_searchresults_new_rows (PurpleConnection gc, PurpleNotifySearchResults results, void *data)
	Replace old rows with the new.
void	purple_notify_searchresults_button_add (PurpleNotifySearchResults *results, PurpleNotifySearchButtonType type, PurpleNotifySearchResultsCallback cb)
	Adds a stock button that will be displayed in the search results dialog.
void	purple_notify_searchresults_button_add_labeled (PurpleNotifySearchResults results, const char label, PurpleNotifySearchResultsCallback cb)
	Adds a plain labelled button that will be displayed in the search results dialog.
PurpleNotifySearchResults *	purple_notify_searchresults_new (void)
	Returns a newly created search results object.
PurpleNotifySearchColumn *	purple_notify_searchresults_column_new (const char *title)
	Returns a newly created search result column object.
void	purple_notify_searchresults_column_add (PurpleNotifySearchResults results, PurpleNotifySearchColumn column)
	Adds a new column to the search result object.
void	purple_notify_searchresults_row_add (PurpleNotifySearchResults results, GList row)
	Adds a new row of the results to the search results object.
guint	purple_notify_searchresults_get_rows_count (PurpleNotifySearchResults *results)
	Returns a number of the rows in the search results object.
guint	purple_notify_searchresults_get_columns_count (PurpleNotifySearchResults *results)
	Returns a number of the columns in the search results object.
GList *	purple_notify_searchresults_row_get (PurpleNotifySearchResults *results, unsigned int row_id)
	Returns a row of the results from the search results object.
char *	purple_notify_searchresults_column_get_title (PurpleNotifySearchResults *results, unsigned int column_id)
	Returns a title of the search results object's column.
UI Registration Functions
void	purple_notify_set_ui_ops (PurpleNotifyUiOps *ops)
	Sets the UI operations structure to be used when displaying a notification.
PurpleNotifyUiOps *	purple_notify_get_ui_ops (void)
	Returns the UI operations structure to be used when displaying a notification.
Notify Subsystem
void *	purple_notify_get_handle (void)
	Returns the notify subsystem handle.
void	purple_notify_init (void)
	Initializes the notify subsystem.
void	purple_notify_uninit (void)
	Uninitializes the notify subsystem.

Detailed Description

Notification API.

See also:: Notification Signals

Definition in file notify.h.

Define Documentation

#define purple_notify_error	(	handle,
		title,
		primary,
		secondary	)

Value:

purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
                        (primary), (secondary), NULL, NULL)

A wrapper for purple_notify_message that displays an error message.

Definition at line 741 of file notify.h.

#define purple_notify_info	(	handle,
		title,
		primary,
		secondary	)

Value:

purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
                        (primary), (secondary), NULL, NULL)

A wrapper for purple_notify_message that displays an information message.

Definition at line 727 of file notify.h.

#define purple_notify_warning	(	handle,
		title,
		primary,
		secondary	)

Value:

purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
                        (primary), (secondary), NULL, NULL)

A wrapper for purple_notify_message that displays a warning message.

Definition at line 734 of file notify.h.

Typedef Documentation

typedef void(* PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row, gpointer user_data)

Callback for a button in a search result.

Parameters:

	c	the PurpleConnection passed to purple_notify_searchresults
	row	the contents of the selected row
	user_data	User defined data.

Definition at line 126 of file notify.h.

Enumeration Type Documentation

enum PurpleNotifyMsgType

Notification message types.

Enumerator:

PURPLE_NOTIFY_MSG_ERROR	Error notification.
PURPLE_NOTIFY_MSG_WARNING	Warning notification.
PURPLE_NOTIFY_MSG_INFO	Information notification.

Definition at line 64 of file notify.h.

enum PurpleNotifySearchButtonType

The types of buttons.

Enumerator:

PURPLE_NOTIFY_BUTTON_LABELED

special use, see _button_add_labeled

Definition at line 76 of file notify.h.

enum PurpleNotifyType

Notification types.

Enumerator:

PURPLE_NOTIFY_MESSAGE	Message notification.
PURPLE_NOTIFY_EMAIL	Single email notification.
PURPLE_NOTIFY_EMAILS	Multiple email 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.

Definition at line 48 of file notify.h.

Function Documentation

void purple_notify_close	(	PurpleNotifyType	type,
		void *	ui_handle
	)

Closes a notification.

This should be used only by the UI operation functions and part of the core.

Parameters:

	type	The notification type.
	ui_handle	The notification UI handle.

void purple_notify_close_with_handle ( void * handle )

Closes all notifications registered with the specified handle.

Parameters:

handle

The handle.

void* purple_notify_email	(	void *	handle,
		const char *	subject,
		const char *	from,
		const char *	to,
		const char *	url,
		PurpleNotifyCloseCallback	cb,
		gpointer	user_data
	)

Displays a single email notification to the user.

Parameters:

	handle	The plugin or connection handle.
	subject	The subject of the email.
	from	The from address.
	to	The destination address.
	url	The URL where the message can be read.
	cb	The callback to call when the user closes the notification.
	user_data	The data to pass to the callback.

Returns:: A UI-specific handle.

void* purple_notify_emails	(	void *	handle,
		size_t	count,
		gboolean	detailed,
		const char **	subjects,
		const char **	froms,
		const char **	tos,
		const char **	urls,
		PurpleNotifyCloseCallback	cb,
		gpointer	user_data
	)

Displays a notification for multiple emails to the user.

Parameters:

	handle	The plugin or connection handle.
	count	The number of emails. '0' can be used to signify that the user has no unread emails and the UI should remove the mail notification.
	detailed	`TRUE` if there is information for each email in the arrays.
	subjects	The array of subjects.
	froms	The array of from addresses.
	tos	The array of destination addresses.
	urls	The URLs where the messages can be read.
	cb	The callback to call when the user closes the notification.
	user_data	The data to pass to the callback.

Returns:: A UI-specific handle.

void* purple_notify_formatted	(	void *	handle,
		const char *	title,
		const char *	primary,
		const char *	secondary,
		const char *	text,
		PurpleNotifyCloseCallback	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.

Parameters:

	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	The callback to call when the user closes the notification.
	user_data	The data to pass to the callback.

Returns:: A UI-specific handle.

void* purple_notify_get_handle ( void )

Returns the notify subsystem handle.

Returns:: The notify subsystem handle.

PurpleNotifyUiOps* purple_notify_get_ui_ops ( void )

Returns the UI operations structure to be used when displaying a notification.

Returns:: The UI operations structure.

void* purple_notify_message	(	void *	handle,
		PurpleNotifyMsgType	type,
		const char *	title,
		const char *	primary,
		const char *	secondary,
		PurpleNotifyCloseCallback	cb,
		gpointer	user_data
	)

Displays a notification message to the user.

Parameters:

	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.
	cb	The callback to call when the user closes the notification.
	user_data	The data to pass to the callback.

Returns:: A UI-specific handle.

void* purple_notify_searchresults	(	PurpleConnection *	gc,
		const char *	title,
		const char *	primary,
		const char *	secondary,
		PurpleNotifySearchResults *	results,
		PurpleNotifyCloseCallback	cb,
		gpointer	user_data
	)

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.

Parameters:

	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	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.

Returns:: A UI-specific handle.

void purple_notify_searchresults_button_add	(	PurpleNotifySearchResults *	results,
		PurpleNotifySearchButtonType	type,
		PurpleNotifySearchResultsCallback	cb
	)

Adds a stock button that will be displayed in the search results dialog.

Parameters:

	results	The search results object.
	type	Type of the button. (TODO: Only one button of a given type can be displayed.)
	cb	Function that will be called on the click event.

void purple_notify_searchresults_button_add_labeled	(	PurpleNotifySearchResults *	results,
		const char *	label,
		PurpleNotifySearchResultsCallback	cb
	)

Adds a plain labelled button that will be displayed in the search results dialog.

Parameters:

	results	The search results object
	label	The label to display
	cb	Function that will be called on the click event

void purple_notify_searchresults_column_add	(	PurpleNotifySearchResults *	results,
		PurpleNotifySearchColumn *	column
	)

Adds a new column to the search result object.

Parameters:

	results	The result object to which the column will be added.
	column	The column that will be added to the result object.

char* purple_notify_searchresults_column_get_title	(	PurpleNotifySearchResults *	results,
		unsigned int	column_id
	)

Returns a title of the search results object's column.

Deprecated:: This function will be removed in Pidgin 3.0.0 unless there is sufficient demand to keep it. Using this function encourages looping through the columns inefficiently. Instead of using this function you should iterate through the name of a particular column you can use g_list_nth_data(results->columns, row_id).

Parameters:

	results	The search results object.
	column_id	Index of the column.

Returns:: Title of the column.

PurpleNotifySearchColumn* purple_notify_searchresults_column_new ( const char * title )

Returns a newly created search result column object.

Parameters:

title

Title of the column. NOTE: Title will get g_strdup()ed.

Returns:: The new search column object.

void purple_notify_searchresults_free ( PurpleNotifySearchResults * results )

Frees a PurpleNotifySearchResults object.

Parameters:

results

The PurpleNotifySearchResults to free.

guint purple_notify_searchresults_get_columns_count ( PurpleNotifySearchResults * results )

Returns a number of the columns in the search results object.

Deprecated:: This function will be removed in Pidgin 3.0.0 unless there is sufficient demand to keep it. Using this function encourages looping through the columns inefficiently. Instead of using this function you should iterate through the columns using a loop similar to this: for (l = results->columns; l != NULL; l = l->next) If you really need to get the number of columns you can use g_list_length(results->columns).

Parameters:

results

The search results object.

Returns:: Number of the columns.

guint purple_notify_searchresults_get_rows_count ( PurpleNotifySearchResults * results )

Returns a number of the rows in the search results object.

Deprecated:: This function will be removed in Pidgin 3.0.0 unless there is sufficient demand to keep it. Using this function encourages looping through the results inefficiently. Instead of using this function you should iterate through the results using a loop similar to this: for (l = results->rows; l != NULL; l = l->next) If you really need to get the number of rows you can use g_list_length(results->rows).

Parameters:

results

The search results object.

Returns:: Number of the result rows.

PurpleNotifySearchResults* purple_notify_searchresults_new ( void )

Returns a newly created search results object.

Returns:: The new search results object.

void purple_notify_searchresults_new_rows	(	PurpleConnection *	gc,
		PurpleNotifySearchResults *	results,
		void *	data
	)

Replace old rows with the new.

Reuse an existing window.

Parameters:

	gc	The PurpleConnection structure.
	results	The PurpleNotifySearchResults structure.
	data	Data returned by the purple_notify_searchresults().

void purple_notify_searchresults_row_add	(	PurpleNotifySearchResults *	results,
		GList *	row
	)

Adds a new row of the results to the search results object.

Parameters:

	results	The search results object.
	row	The row of the results.

GList* purple_notify_searchresults_row_get	(	PurpleNotifySearchResults *	results,
		unsigned int	row_id
	)

Returns a row of the results from the search results object.

Deprecated:: This function will be removed in Pidgin 3.0.0 unless there is sufficient demand to keep it. Using this function encourages looping through the results inefficiently. Instead of using this function you should iterate through the results using a loop similar to this: for (l = results->rows; l != NULL; l = l->next) If you really need to get the data for a particular row you can use g_list_nth_data(results->rows, row_id).

Parameters:

	results	The search results object.
	row_id	Index of the row to be returned.

Returns:: Row of the results.

void purple_notify_set_ui_ops ( PurpleNotifyUiOps * ops )

Sets the UI operations structure to be used when displaying a notification.

Parameters:

ops

The UI operations structure.

void* purple_notify_uri	(	void *	handle,
		const char *	uri
	)

Opens a URI or somehow presents it to the user.

Parameters:

	handle	The plugin or connection handle.
	uri	The URI to display or go to.

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.

void purple_notify_user_info_add_pair	(	PurpleNotifyUserInfo *	user_info,
		const char *	label,
		const char *	value
	)

Add a label/value pair to a PurpleNotifyUserInfo object.

PurpleNotifyUserInfo keeps track of the order in which pairs are added.

Parameters:

	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. 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 purple_notify_user_info_add_section_break ( PurpleNotifyUserInfo * user_info )

Add a section break.

A UI might display this as a horizontal line.

Parameters:

user_info

The PurpleNotifyUserInfo

void purple_notify_user_info_add_section_header	(	PurpleNotifyUserInfo *	user_info,
		const char *	label
	)

Add a section header.

A UI might display this in a different font from other text.

Parameters:

	user_info	The PurpleNotifyUserInfo
	label	The name of the section

void purple_notify_user_info_destroy ( PurpleNotifyUserInfo * user_info )

Destroy a PurpleNotifyUserInfo.

Parameters:

user_info

The PurpleNotifyUserInfo

const gchar* purple_notify_user_info_entry_get_label ( PurpleNotifyUserInfoEntry * user_info_entry )

Get the label for a PurpleNotifyUserInfoEntry.

Parameters:

user_info_entry

The PurpleNotifyUserInfoEntry

Returns:: The label

PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type ( PurpleNotifyUserInfoEntry * user_info_entry )

Get the type of a PurpleNotifyUserInfoEntry.

Parameters:

user_info_entry

The PurpleNotifyUserInfoEntry

Returns:: The PurpleNotifyUserInfoEntryType

const gchar* purple_notify_user_info_entry_get_value ( PurpleNotifyUserInfoEntry * user_info_entry )

Get the value for a PurpleNotifyUserInfoEntry.

Parameters:

user_info_entry

The PurpleNotifyUserInfoEntry

Returns:: The value

PurpleNotifyUserInfoEntry* purple_notify_user_info_entry_new	(	const char *	label,
		const char *	value
	)

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() and purple_notify_user_info_prepend_pair() are convenience methods for creating entries and adding them to a PurpleNotifyUserInfo.

Parameters:

	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.

Returns:: A new PurpleNotifyUserInfoEntry

void purple_notify_user_info_entry_set_label	(	PurpleNotifyUserInfoEntry *	user_info_entry,
		const char *	label
	)

Set the label for a PurpleNotifyUserInfoEntry.

Parameters:

	user_info_entry	The PurpleNotifyUserInfoEntry
	label	The label

void purple_notify_user_info_entry_set_type	(	PurpleNotifyUserInfoEntry *	user_info_entry,
		PurpleNotifyUserInfoEntryType	type
	)

Set the type of a PurpleNotifyUserInfoEntry.

Parameters:

	user_info_entry	The PurpleNotifyUserInfoEntry
	type	The PurpleNotifyUserInfoEntryType

void purple_notify_user_info_entry_set_value	(	PurpleNotifyUserInfoEntry *	user_info_entry,
		const char *	value
	)

Set the value for a PurpleNotifyUserInfoEntry.

Parameters:

	user_info_entry	The PurpleNotifyUserInfoEntry
	value	The value

GList* purple_notify_user_info_get_entries ( PurpleNotifyUserInfo * user_info )

Retrieve the array of PurpleNotifyUserInfoEntry objects from a PurpleNotifyUserInfo.

This GList may be manipulated directly with normal GList functions such as g_list_insert(). Only PurpleNotifyUserInfoEntry are allowed in the list. If a PurpleNotifyUserInfoEntry item is added to the list, it should not be g_free()'d by the caller; PurpleNotifyUserInfo will g_free it when destroyed.

To remove a PurpleNotifyUserInfoEntry, use purple_notify_user_info_remove_entry(). Do not use the GList directly.

Parameters:

user_info

The PurpleNotifyUserInfo

Note:: The return value of this function must not be modified or freed.

Returns:: A GList of PurpleNotifyUserInfoEntry objects

char* purple_notify_user_info_get_text_with_newline	(	PurpleNotifyUserInfo *	user_info,
		const char *	newline
	)

Create a textual representation of a PurpleNotifyUserInfo, separating entries with newline.

Parameters:

	user_info	The PurpleNotifyUserInfo
	newline	The separation character

PurpleNotifyUserInfo* purple_notify_user_info_new ( void )

Create a new PurpleNotifyUserInfo which is suitable for passing to purple_notify_userinfo().

Returns:: A new PurpleNotifyUserInfo, which the caller must destroy when done

void purple_notify_user_info_prepend_pair	(	PurpleNotifyUserInfo *	user_info,
		const char *	label,
		const char *	value
	)

Prepend a label/value pair to a PurpleNotifyUserInfo object.

Parameters:

	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. 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 purple_notify_user_info_prepend_section_break ( PurpleNotifyUserInfo * user_info )

Prepend a section break.

A UI might display this as a horizontal line.

Parameters:

user_info

The PurpleNotifyUserInfo

Since:: 2.5.0

void purple_notify_user_info_prepend_section_header	(	PurpleNotifyUserInfo *	user_info,
		const char *	label
	)

Prepend a section header.

A UI might display this in a different font from other text.

Parameters:

	user_info	The PurpleNotifyUserInfo
	label	The name of the section

Since:: 2.5.0

void purple_notify_user_info_remove_entry	(	PurpleNotifyUserInfo *	user_info,
		PurpleNotifyUserInfoEntry *	user_info_entry
	)

Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object without freeing the entry.

Parameters:

	user_info	The PurpleNotifyUserInfo
	user_info_entry	The PurpleNotifyUserInfoEntry

Deprecated:: Nothing is using this function and it should be removed in 3.0.0. Or, if we decide we want to keep it in 3.0.0 then we should make purple_notify_user_info_entry_destroy public so that entries can be free'd after they're removed.

void purple_notify_user_info_remove_last_item ( PurpleNotifyUserInfo * user_info )

Remove the last item which was added to a PurpleNotifyUserInfo.

This could be used to remove a section header which is not needed.

void* purple_notify_userinfo	(	PurpleConnection *	gc,
		const char *	who,
		PurpleNotifyUserInfo *	user_info,
		PurpleNotifyCloseCallback	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.

Parameters:

	gc	The PurpleConnection handle associated with the information.
	who	The username associated with the information.
	user_info	The PurpleNotifyUserInfo which contains the information
	cb	The callback to call when the user closes the notification.
	user_data	The data to pass to the callback.

Returns:: A UI-specific handle.

Context Navigation

notify.h File Reference

Data Structures

Notification API

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation