pidgin  2.14.10
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 {
59 
60 
64 typedef enum
65 {
71 
72 
76 typedef enum
77 {
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
86 
87 
91 typedef struct
92 {
93  GList *columns;
94  GList *rows;
95  GList *buttons;
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
108 
112 typedef struct
113 {
114  char *title;
117 
118 
127  gpointer user_data);
128 
129 
133 typedef struct
134 {
137  char *label;
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);
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,
214  gpointer user_data);
215 
222 
231  PurpleNotifySearchResults *results,
232  void *data);
233 
234 
246 
247 
257  const char *label,
259 
260 
267 
276 
284  PurpleNotifySearchColumn *column);
285 
293  GList *row);
294 
295 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
314 #endif
315 
316 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
335 #endif
336 
337 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
357  unsigned int row_id);
358 #endif
359 
360 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_NOTIFY_C_)
378  unsigned int column_id);
379 #endif
380 
383 /**************************************************************************/
385 /**************************************************************************/
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_)
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,
708 
719 void *purple_notify_uri(void *handle, const char *uri);
720 
730 void purple_notify_close(PurpleNotifyType type, void *ui_handle);
731 
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 /**************************************************************************/
774 
782 
785 /**************************************************************************/
787 /**************************************************************************/
796 
801 
806 
810 #ifdef __cplusplus
811 }
812 #endif
813 
814 #endif /* _PURPLE_NOTIFY_H_ */
Connection API.
PurpleNotifySearchButtonType
The types of buttons.
Definition: notify.h:77
@ PURPLE_NOTIFY_BUTTON_LABELED
special use, see _button_add_labeled
Definition: notify.h:78
PurpleNotifyUserInfoEntryType
Types of PurpleNotifyUserInfoEntry objects.
Definition: notify.h:103
void * purple_notify_uri(void *handle, const char *uri)
Opens a URI or somehow presents it to the user.
void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type)
Set the type of a PurpleNotifyUserInfoEntry.
PurpleNotifyMsgType
Notification message types.
Definition: notify.h:65
@ PURPLE_NOTIFY_MSG_INFO
Information notification.
Definition: notify.h:68
@ PURPLE_NOTIFY_MSG_WARNING
Warning notification.
Definition: notify.h:67
@ PURPLE_NOTIFY_MSG_ERROR
Error notification.
Definition: notify.h:66
void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value)
Set the value for a PurpleNotifyUserInfoEntry.
void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops)
Sets the UI operations structure to be used when displaying a notification.
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.
PurpleNotifySearchResults * purple_notify_searchresults_new(void)
Returns a newly created search results object.
guint purple_notify_searchresults_get_rows_count(PurpleNotifySearchResults *results)
Returns a number of the rows in the search results object.
void(* PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row, gpointer user_data)
Callback for a button in a search result.
Definition: notify.h:126
void purple_notify_user_info_remove_last_item(PurpleNotifyUserInfo *user_info)
Remove the last item which was added to a PurpleNotifyUserInfo.
PurpleNotifySearchColumn * purple_notify_searchresults_column_new(const char *title)
Returns a newly created search result column object.
PurpleNotifyUserInfoEntry * purple_notify_user_info_entry_new(const char *label, const char *value)
Create a new PurpleNotifyUserInfoEntry.
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_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label)
Set the label for a PurpleNotifyUserInfoEntry.
char * purple_notify_searchresults_column_get_title(PurpleNotifySearchResults *results, unsigned int column_id)
Returns a title of the search results object's column.
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_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_searchresults_row_add(PurpleNotifySearchResults *results, GList *row)
Adds a new row of the results to the search results object.
void purple_notify_close(PurpleNotifyType type, void *ui_handle)
Closes a notification.
void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info)
Destroy a PurpleNotifyUserInfo.
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.
GList * purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info)
Retrieve the array of PurpleNotifyUserInfoEntry objects from a PurpleNotifyUserInfo.
PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry)
Get the type of a PurpleNotifyUserInfoEntry.
void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info)
Prepend a section break.
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.
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_add_section_header(PurpleNotifyUserInfo *user_info, const char *label)
Add a section header.
void purple_notify_close_with_handle(void *handle)
Closes all notifications registered with the specified handle.
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_get_handle(void)
Returns the notify subsystem handle.
void purple_notify_init(void)
Initializes the notify subsystem.
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.
const gchar * purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry)
Get the label for a PurpleNotifyUserInfoEntry.
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
const gchar * purple_notify_user_info_entry_get_value(PurpleNotifyUserInfoEntry *user_info_entry)
Get the value for a PurpleNotifyUserInfoEntry.
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...
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.
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_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...
void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info)
Add a section break.
void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results, PurpleNotifySearchColumn *column)
Adds a new column to the search result object.
guint purple_notify_searchresults_get_columns_count(PurpleNotifySearchResults *results)
Returns a number of the columns in the search results object.
void(* PurpleNotifyCloseCallback)(gpointer user_data)
Notification close callbacks.
Definition: notify.h:42
void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label)
Prepend a section header.
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_uninit(void)
Uninitializes the notify subsystem.
PurpleNotifyType
Notification types.
Definition: notify.h:49
@ PURPLE_NOTIFY_EMAIL
Single email notification.
Definition: notify.h:51
@ PURPLE_NOTIFY_MESSAGE
Message notification.
Definition: notify.h:50
@ PURPLE_NOTIFY_URI
URI notification or display.
Definition: notify.h:56
@ PURPLE_NOTIFY_FORMATTED
Formatted text.
Definition: notify.h:53
@ PURPLE_NOTIFY_SEARCHRESULTS
Buddy search results.
Definition: notify.h:54
@ PURPLE_NOTIFY_USERINFO
Formatted userinfo text.
Definition: notify.h:55
@ PURPLE_NOTIFY_EMAILS
Multiple email notification.
Definition: notify.h:52
PurpleNotifyUiOps * purple_notify_get_ui_ops(void)
Returns the UI operations structure to be used when displaying a notification.
GList * purple_notify_searchresults_row_get(PurpleNotifySearchResults *results, unsigned int row_id)
Returns a row of the results from the search results object.
Definition of a button.
Definition: notify.h:134
char * label
only for PURPLE_NOTIFY_BUTTON_LABELED
Definition: notify.h:137
PurpleNotifySearchResultsCallback callback
Function to be called when clicked.
Definition: notify.h:136
Single column of a search result.
Definition: notify.h:113
char * title
Title of the column.
Definition: notify.h:114
Search results object.
Definition: notify.h:92
GList * buttons
List of buttons to display.
Definition: notify.h:95
GList * rows
List of rows in the result.
Definition: notify.h:94
GList * columns
List of the search column objects.
Definition: notify.h:93
Notification UI operations.
Definition: notify.h:145