notify.h
Go to the documentation of this file.
1
7 /* purple
8 *
9 * Purple is the legal property of its developers, whose names are too numerous
10 * to list here. Please refer to the COPYRIGHT file distributed with this
11 * source distribution.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
26 */
27 #ifndef _PURPLE_NOTIFY_H_
28 #define _PURPLE_NOTIFY_H_
29
30 #include <stdlib.h>
31 #include <glib-object.h>
32 #include <glib.h>
33
34 typedef struct _PurpleNotifyUserInfoEntry PurpleNotifyUserInfoEntry;
35 typedef struct _PurpleNotifyUserInfo PurpleNotifyUserInfo;
36
37 #include "connection.h"
38
42 typedef void (*PurpleNotifyCloseCallback) (gpointer user_data);
43
44
48 typedef enum
49 {
50 PURPLE_NOTIFY_MESSAGE = 0,
51 PURPLE_NOTIFY_EMAIL,
52 PURPLE_NOTIFY_EMAILS,
53 PURPLE_NOTIFY_FORMATTED,
54 PURPLE_NOTIFY_SEARCHRESULTS,
55 PURPLE_NOTIFY_USERINFO,
56 PURPLE_NOTIFY_URI
58 } PurpleNotifyType;
59
60
64 typedef enum
65 {
66 PURPLE_NOTIFY_MSG_ERROR = 0,
67 PURPLE_NOTIFY_MSG_WARNING,
68 PURPLE_NOTIFY_MSG_INFO
70 } PurpleNotifyMsgType;
71
72
76 typedef enum
77 {
78 PURPLE_NOTIFY_BUTTON_LABELED = 0,
79 PURPLE_NOTIFY_BUTTON_CONTINUE = 1,
80 PURPLE_NOTIFY_BUTTON_ADD,
81 PURPLE_NOTIFY_BUTTON_INFO,
82 PURPLE_NOTIFY_BUTTON_IM,
83 PURPLE_NOTIFY_BUTTON_JOIN,
84 PURPLE_NOTIFY_BUTTON_INVITE
85 } PurpleNotifySearchButtonType;
86
87
91 typedef struct
92 {
93 GList *columns;
94 GList *rows;
95 GList *buttons;
97 } PurpleNotifySearchResults;
98
102 typedef enum
103 {
104 PURPLE_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
105 PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
106 PURPLE_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
107 } PurpleNotifyUserInfoEntryType;
108
112 typedef struct
113 {
114 char *title;
116 } PurpleNotifySearchColumn;
117
118
126 typedef void (*PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row,
127 gpointer user_data);
128
129
133 typedef struct
134 {
135 PurpleNotifySearchButtonType type;
136 PurpleNotifySearchResultsCallback callback;
137 char *label;
138 } PurpleNotifySearchButton;
139
140
144 typedef struct
145 {
146 void *(*notify_message)(PurpleNotifyMsgType type, const char *title,
147 const char *primary, const char *secondary);
148
149 void *(*notify_email)(PurpleConnection *gc,
150 const char *subject, const char *from,
151 const char *to, const char *url);
152
153 void *(*notify_emails)(PurpleConnection *gc,
154 size_t count, gboolean detailed,
155 const char **subjects, const char **froms,
156 const char **tos, const char **urls);
157
158 void *(*notify_formatted)(const char *title, const char *primary,
159 const char *secondary, const char *text);
160
161 void *(*notify_searchresults)(PurpleConnection *gc, const char *title,
162 const char *primary, const char *secondary,
163 PurpleNotifySearchResults *results, gpointer user_data);
164
165 void (*notify_searchresults_new_rows)(PurpleConnection *gc,
166 PurpleNotifySearchResults *results,
167 void *data);
168
169 void *(*notify_userinfo)(PurpleConnection *gc, const char *who,
170 PurpleNotifyUserInfo *user_info);
171
172 void *(*notify_uri)(const char *uri);
173
174 void (*close_notify)(PurpleNotifyType type, void *ui_handle);
175
176 void (*_purple_reserved1)(void);
177 void (*_purple_reserved2)(void);
178 void (*_purple_reserved3)(void);
179 void (*_purple_reserved4)(void);
180 } PurpleNotifyUiOps;
181
182
183 #ifdef __cplusplus
184 extern "C" {
185 #endif
186
187
188 /**************************************************************************/
190 /**************************************************************************/
211 void *purple_notify_searchresults(PurpleConnection *gc, const char *title,
212 const char *primary, const char *secondary,
213 PurpleNotifySearchResults *results, PurpleNotifyCloseCallback cb,
214 gpointer user_data);
215
221 void purple_notify_searchresults_free(PurpleNotifySearchResults *results);
222
230 void purple_notify_searchresults_new_rows(PurpleConnection *gc,
231 PurpleNotifySearchResults *results,
232 void *data);
233
234
243 void purple_notify_searchresults_button_add(PurpleNotifySearchResults *results,
244 PurpleNotifySearchButtonType type,
245 PurpleNotifySearchResultsCallback cb);
246
247
256 void purple_notify_searchresults_button_add_labeled(PurpleNotifySearchResults *results,
257 const char *label,
258 PurpleNotifySearchResultsCallback cb);
259
260
266 PurpleNotifySearchResults *purple_notify_searchresults_new(void);
267
275 PurpleNotifySearchColumn *purple_notify_searchresults_column_new(const char *title);
276
283 void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results,
284 PurpleNotifySearchColumn *column);
285
292 void purple_notify_searchresults_row_add(PurpleNotifySearchResults *results,
293 GList *row);
294
295 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
296
313 guint purple_notify_searchresults_get_rows_count(PurpleNotifySearchResults *results);
314 #endif
315
316 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
317
334 guint purple_notify_searchresults_get_columns_count(PurpleNotifySearchResults *results);
335 #endif
336
337 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
338
356 GList *purple_notify_searchresults_row_get(PurpleNotifySearchResults *results,
357 unsigned int row_id);
358 #endif
359
360 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
361
377 char *purple_notify_searchresults_column_get_title(PurpleNotifySearchResults *results,
378 unsigned int column_id);
379 #endif
380
383 /**************************************************************************/
385 /**************************************************************************/
402 void *purple_notify_message(void *handle, PurpleNotifyMsgType type,
403 const char *title, const char *primary,
404 const char *secondary, PurpleNotifyCloseCallback cb,
405 gpointer user_data);
406
421 void *purple_notify_email(void *handle, const char *subject,
422 const char *from, const char *to,
423 const char *url, PurpleNotifyCloseCallback cb,
424 gpointer user_data);
425
445 void *purple_notify_emails(void *handle, size_t count, gboolean detailed,
446 const char **subjects, const char **froms,
447 const char **tos, const char **urls,
448 PurpleNotifyCloseCallback cb, gpointer user_data);
449
467 void *purple_notify_formatted(void *handle, const char *title,
468 const char *primary, const char *secondary,
469 const char *text, PurpleNotifyCloseCallback cb, gpointer user_data);
470
486 void *purple_notify_userinfo(PurpleConnection *gc, const char *who,
487 PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb,
488 gpointer user_data);
489
496 PurpleNotifyUserInfo *purple_notify_user_info_new(void);
497
503 void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info);
504
522 GList *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info);
523
531 char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline);
532
550 /*
551 * TODO: In 3.0.0 this function should be renamed to
552 * purple_notify_user_info_add_pair_html(). And optionally
553 * purple_notify_user_info_add_pair_plaintext() could be renamed to
554 * purple_notify_user_info_add_pair().
555 */
556 void purple_notify_user_info_add_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
557
562 void purple_notify_user_info_add_pair_plaintext(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
563
577 void purple_notify_user_info_prepend_pair(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
578
579 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
580
592 void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry);
593 #endif
594
614 PurpleNotifyUserInfoEntry *purple_notify_user_info_entry_new(const char *label, const char *value);
615
621 void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info);
622
629 void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info);
630
638 void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label);
639
648 void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label);
649
654 void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info);
655
663 const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry);
664
671 void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label);
672
680 const gchar *purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry);
681
688 void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value);
689
690
698 PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry);
699
706 void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry,
707 PurpleNotifyUserInfoEntryType type);
708
719 void *purple_notify_uri(void *handle, const char *uri);
720
730 void purple_notify_close(PurpleNotifyType type, void *ui_handle);
731
737 void purple_notify_close_with_handle(void *handle);
738
742 #define purple_notify_info(handle, title, primary, secondary) \
743 purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
744 (primary), (secondary), NULL, NULL)
745
749 #define purple_notify_warning(handle, title, primary, secondary) \
750 purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
751 (primary), (secondary), NULL, NULL)
752
756 #define purple_notify_error(handle, title, primary, secondary) \
757 purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \
758 (primary), (secondary), NULL, NULL)
759
762 /**************************************************************************/
764 /**************************************************************************/
773 void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops);
774
781 PurpleNotifyUiOps *purple_notify_get_ui_ops(void);
782
785 /**************************************************************************/
787 /**************************************************************************/
795 void *purple_notify_get_handle(void);
796
800 void purple_notify_init(void);
801
805 void purple_notify_uninit(void);
806
810 #ifdef __cplusplus
811 }
812 #endif
813
814 #endif /* _PURPLE_NOTIFY_H_ */
purple_notify_close_with_handle
void purple_notify_close_with_handle(void *handle)
Closes all notifications registered with the specified handle.
purple_notify_user_info_destroy
void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info)
Destroy a PurpleNotifyUserInfo.
PurpleNotifySearchButtonType
PurpleNotifySearchButtonType
The types of buttons.
Definition: notify.h:76
purple_notify_uri
void * purple_notify_uri(void *handle, const char *uri)
Opens a URI or somehow presents it to the user.
purple_notify_close
void purple_notify_close(PurpleNotifyType type, void *ui_handle)
Closes a notification.
purple_notify_set_ui_ops
void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops)
Sets the UI operations structure to be used when displaying a notification.
purple_notify_uninit
void purple_notify_uninit(void)
Uninitializes the notify subsystem.
purple_notify_searchresults_column_new
PurpleNotifySearchColumn * purple_notify_searchresults_column_new(const char *title)
Returns a newly created search result column object.
purple_notify_get_ui_ops
PurpleNotifyUiOps * purple_notify_get_ui_ops(void)
Returns the UI operations structure to be used when displaying a notification.
purple_notify_formatted
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.
purple_notify_user_info_entry_set_label
void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label)
Set the label for a PurpleNotifyUserInfoEntry.
PurpleNotifySearchColumn::title
char * title
Title of the column.
Definition: notify.h:114
PurpleNotifySearchButton::callback
PurpleNotifySearchResultsCallback callback
Function to be called when clicked.
Definition: notify.h:136
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.
connection.h
Connection API.
PURPLE_NOTIFY_MSG_WARNING
Warning notification.
Definition: notify.h:67
purple_notify_user_info_new
PurpleNotifyUserInfo * purple_notify_user_info_new(void)
Create a new PurpleNotifyUserInfo which is suitable for passing to purple_notify_userinfo() ...
purple_notify_searchresults_button_add
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.
PURPLE_NOTIFY_FORMATTED
Formatted text.
Definition: notify.h:53
purple_notify_get_handle
void * purple_notify_get_handle(void)
Returns the notify subsystem handle.
purple_notify_searchresults_get_rows_count
guint purple_notify_searchresults_get_rows_count(PurpleNotifySearchResults *results)
Returns a number of the rows in the search results object.
purple_notify_searchresults_button_add_labeled
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. ...
purple_notify_searchresults_get_columns_count
guint purple_notify_searchresults_get_columns_count(PurpleNotifySearchResults *results)
Returns a number of the columns in the search results object.
PurpleNotifySearchColumn
Single column of a search result.
Definition: notify.h:112
purple_notify_searchresults_row_add
void purple_notify_searchresults_row_add(PurpleNotifySearchResults *results, GList *row)
Adds a new row of the results to the search results object.
PURPLE_NOTIFY_BUTTON_LABELED
special use, see _button_add_labeled
Definition: notify.h:78
purple_notify_user_info_get_entries
GList * purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info)
Retrieve the array of PurpleNotifyUserInfoEntry objects from a PurpleNotifyUserInfo.
purple_notify_searchresults
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.
purple_notify_emails
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.
purple_notify_user_info_prepend_section_break
void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info)
Prepend a section break.
PURPLE_NOTIFY_MSG_ERROR
Error notification.
Definition: notify.h:66
PurpleNotifySearchButton
Definition of a button.
Definition: notify.h:133
PURPLE_NOTIFY_SEARCHRESULTS
Buddy search results.
Definition: notify.h:54
PurpleNotifySearchResults::columns
GList * columns
List of the search column objects.
Definition: notify.h:93
PurpleNotifySearchButton::label
char * label
only for PURPLE_NOTIFY_BUTTON_LABELED
Definition: notify.h:137
purple_notify_searchresults_column_add
void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results, PurpleNotifySearchColumn *column)
Adds a new column to the search result object.
purple_notify_user_info_prepend_pair
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.
PurpleNotifySearchResultsCallback
void(* PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row, gpointer user_data)
Callback for a button in a search result.
Definition: notify.h:126
purple_notify_user_info_add_section_break
void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info)
Add a section break.
purple_notify_searchresults_column_get_title
char * purple_notify_searchresults_column_get_title(PurpleNotifySearchResults *results, unsigned int column_id)
Returns a title of the search results object&#39;s column.
PurpleNotifyMsgType
PurpleNotifyMsgType
Notification message types.
Definition: notify.h:64
purple_notify_init
void purple_notify_init(void)
Initializes the notify subsystem.
purple_notify_user_info_add_pair
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.
PURPLE_NOTIFY_MESSAGE
Message notification.
Definition: notify.h:50
PurpleNotifySearchResults::rows
GList * rows
List of rows in the result.
Definition: notify.h:94
purple_notify_userinfo
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...
purple_notify_user_info_get_text_with_newline
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...
PurpleNotifyUserInfoEntryType
PurpleNotifyUserInfoEntryType
Types of PurpleNotifyUserInfoEntry objects.
Definition: notify.h:102
purple_notify_user_info_entry_get_value
const gchar * purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry)
Get the value for a PurpleNotifyUserInfoEntry.
purple_notify_email
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.
purple_notify_user_info_remove_last_item
void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info)
Remove the last item which was added to a PurpleNotifyUserInfo.
PurpleNotifyType
PurpleNotifyType
Notification types.
Definition: notify.h:48
PURPLE_NOTIFY_USERINFO
Formatted userinfo text.
Definition: notify.h:55
purple_notify_searchresults_new
PurpleNotifySearchResults * purple_notify_searchresults_new(void)
Returns a newly created search results object.
PURPLE_NOTIFY_EMAIL
Single email notification.
Definition: notify.h:51
purple_notify_user_info_entry_new
PurpleNotifyUserInfoEntry * purple_notify_user_info_entry_new(const char *label, const char *value)
Create a new PurpleNotifyUserInfoEntry.
purple_notify_user_info_entry_get_type
PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry)
Get the type of a PurpleNotifyUserInfoEntry.
purple_notify_searchresults_new_rows
void purple_notify_searchresults_new_rows(PurpleConnection *gc, PurpleNotifySearchResults *results, void *data)
Replace old rows with the new.
_PurpleConnection
Definition: connection.h:245
PURPLE_NOTIFY_EMAILS
Multiple email notification.
Definition: notify.h:52
purple_notify_searchresults_free
void purple_notify_searchresults_free(PurpleNotifySearchResults *results)
Frees a PurpleNotifySearchResults object.
PurpleNotifyCloseCallback
void(* PurpleNotifyCloseCallback)(gpointer user_data)
Notification close callbacks.
Definition: notify.h:42
purple_notify_user_info_add_pair_plaintext
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_mark...
PurpleNotifyUiOps
Notification UI operations.
Definition: notify.h:144
purple_notify_user_info_remove_entry
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...
PurpleNotifySearchResults::buttons
GList * buttons
List of buttons to display.
Definition: notify.h:95
purple_notify_searchresults_row_get
GList * purple_notify_searchresults_row_get(PurpleNotifySearchResults *results, unsigned int row_id)
Returns a row of the results from the search results object.
purple_notify_user_info_entry_set_type
void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type)
Set the type of a PurpleNotifyUserInfoEntry.
PurpleNotifySearchResults
Search results object.
Definition: notify.h:91
purple_notify_user_info_prepend_section_header
void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label)
Prepend a section header.
PURPLE_NOTIFY_URI
URI notification or display.
Definition: notify.h:56
purple_notify_user_info_add_section_header
void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label)
Add a section header.
purple_notify_user_info_entry_get_label
const gchar * purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry)
Get the label for a PurpleNotifyUserInfoEntry.
purple_notify_user_info_entry_set_value
void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value)
Set the value for a PurpleNotifyUserInfoEntry.