notify.h File Reference
libpurple

Notification API. More...

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

Go to the source code of 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...

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

## 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. More...
void | purple_notify_searchresults_free (PurpleNotifySearchResults *results)
| Frees a PurpleNotifySearchResults object. More...
void | purple_notify_searchresults_new_rows (PurpleConnection *gc, PurpleNotifySearchResults *results, void *data)
| Replace old rows with the new. More...
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. More...
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. More...
PurpleNotifySearchResults * | purple_notify_searchresults_new (void)
| Returns a newly created search results object. More...
PurpleNotifySearchColumn * | purple_notify_searchresults_column_new (const char *title)
| Returns a newly created search result column object. More...
void | purple_notify_searchresults_column_add (PurpleNotifySearchResults *results, PurpleNotifySearchColumn *column)
| Adds a new column to the search result object. More...
void | purple_notify_searchresults_row_add (PurpleNotifySearchResults *results, GList *row)
| Adds a new row of the results to the search results object. More...
guint | purple_notify_searchresults_get_rows_count (PurpleNotifySearchResults *results)
| Returns a number of the rows in the search results object. More...
guint | purple_notify_searchresults_get_columns_count (PurpleNotifySearchResults *results)
| Returns a number of the columns in the search results object. More...
GList * | purple_notify_searchresults_row_get (PurpleNotifySearchResults *results, unsigned int row_id)
| Returns a row of the results from the search results object. More...
char * | purple_notify_searchresults_column_get_title (PurpleNotifySearchResults *results, unsigned int column_id)
| Returns a title of the search results object's column. More...
UI Registration Functions
void | purple_notify_set_ui_ops (PurpleNotifyUiOps *ops)
| Sets the UI operations structure to be used when displaying a notification. More...
PurpleNotifyUiOps * | purple_notify_get_ui_ops (void)
| Returns the UI operations structure to be used when displaying a notification. More...
Notify Subsystem
void * | purple_notify_get_handle (void)
| Returns the notify subsystem handle. More...
void | purple_notify_init (void)
| Initializes the notify subsystem.
void | purple_notify_uninit (void)
| Uninitializes the notify subsystem.

## Notification API

#define | purple_notify_info(handle, title, primary, secondary)
| A wrapper for purple_notify_message that displays an information message. More...
#define | purple_notify_warning(handle, title, primary, secondary)
| A wrapper for purple_notify_message that displays a warning message. More...
#define | purple_notify_error(handle, title, primary, secondary)
| A wrapper for purple_notify_message that displays an error message. More...
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. More...
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. More...
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. More...
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. More...
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. More...
PurpleNotifyUserInfo * | purple_notify_user_info_new (void)
| Create a new PurpleNotifyUserInfo which is suitable for passing to purple_notify_userinfo() More...
void | purple_notify_user_info_destroy (PurpleNotifyUserInfo *user_info)
| Destroy a PurpleNotifyUserInfo. More...
GList * | purple_notify_user_info_get_entries (PurpleNotifyUserInfo *user_info)
| Retrieve the array of PurpleNotifyUserInfoEntry objects from a PurpleNotifyUserInfo. More...
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. More...
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. More...
void | purple_notify_user_info_add_pair_plaintext (PurpleNotifyUserInfo *user_info, const char *label, const char *value)
| Like purple_notify_user_info_add_pair, but value should be plaintext and will be escaped using g_markup_escape_text().
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. More...
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. More...
PurpleNotifyUserInfoEntry * | purple_notify_user_info_entry_new (const char *label, const char *value)
| Create a new PurpleNotifyUserInfoEntry. More...
void | purple_notify_user_info_add_section_break (PurpleNotifyUserInfo *user_info)
| Add a section break. More...
void | purple_notify_user_info_prepend_section_break (PurpleNotifyUserInfo *user_info)
| Prepend a section break. More...
void | purple_notify_user_info_add_section_header (PurpleNotifyUserInfo *user_info, const char *label)
| Add a section header. More...
void | purple_notify_user_info_prepend_section_header (PurpleNotifyUserInfo *user_info, const char *label)
| Prepend a section header. More...
void | purple_notify_user_info_remove_last_item (PurpleNotifyUserInfo *user_info)
| Remove the last item which was added to a PurpleNotifyUserInfo. More...
const gchar * | purple_notify_user_info_entry_get_label (PurpleNotifyUserInfoEntry *user_info_entry)
| Get the label for a PurpleNotifyUserInfoEntry. More...
void | purple_notify_user_info_entry_set_label (PurpleNotifyUserInfoEntry *user_info_entry, const char *label)
| Set the label for a PurpleNotifyUserInfoEntry. More...
const gchar * | purple_notify_user_info_entry_get_value (PurpleNotifyUserInfoEntry *user_info_entry)
| Get the value for a PurpleNotifyUserInfoEntry. More...
void | purple_notify_user_info_entry_set_value (PurpleNotifyUserInfoEntry *user_info_entry, const char *value)
| Set the value for a PurpleNotifyUserInfoEntry. More...
PurpleNotifyUserInfoEntryType | purple_notify_user_info_entry_get_type (PurpleNotifyUserInfoEntry *user_info_entry)
| Get the type of a PurpleNotifyUserInfoEntry. More...
void | purple_notify_user_info_entry_set_type (PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type)
| Set the type of a PurpleNotifyUserInfoEntry. More...
void * | purple_notify_uri (void *handle, const char *uri)
| Opens a URI or somehow presents it to the user. More...
void | purple_notify_close (PurpleNotifyType type, void *ui_handle)
| Closes a notification. More...
void | purple_notify_close_with_handle (void *handle)
| Closes all notifications registered with the specified handle. More...

## Detailed Description

Notification API.

See also
  Notification Signals

Definition in file notify.h.

## Macro Definition Documentation

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

Value:
purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
(primary), (secondary), NULL, NULL)
purple_notify_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.
PURPLE_NOTIFY_MSG_ERROR
Error notification.
Definition: notify.h:66

A wrapper for purple_notify_message that displays an error message.

Definition at line 756 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)
PURPLE_NOTIFY_MSG_INFO
Information notification.
Definition: notify.h:68
purple_notify_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.

A wrapper for purple_notify_message that displays an information message.

Definition at line 742 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)
purple_notify_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.
PURPLE_NOTIFY_MSG_WARNING
Warning notification.
Definition: notify.h:67

A wrapper for purple_notify_message that displays a warning message.

Definition at line 749 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. 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.

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.