1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
/** -*- mode: c-mode; tab-width: 4; indent-tabs-mode: t; -*-
* @file libnotify/notify.h Notifications library
*
* @Copyright (C) 2004 Christian Hammond
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#ifndef _LIBNOTIFY_NOTIFY_H_
#define _LIBNOTIFY_NOTIFY_H_
#include <glib.h>
#include <time.h>
/**
* Notification urgency levels.
*/
typedef enum
{
NOTIFY_URGENCY_LOW, /**< Low urgency. */
NOTIFY_URGENCY_NORMAL, /**< Normal urgency. */
NOTIFY_URGENCY_HIGH, /**< High urgency. */
NOTIFY_URGENCY_CRITICAL, /**< Critical urgency. */
} NotifyUrgency;
typedef struct _NotifyHandle NotifyHandle;
typedef struct _NotifyIcon NotifyIcon;
typedef void (*NotifyCallback)(NotifyHandle *, guint32, gpointer);
/**************************************************************************/
/** @name libnotify Base API */
/**************************************************************************/
/*@{*/
/**
* Initializes the notifications library.
*
* @param app_name The application name.
*
* @return TRUE if the library initialized properly and a connection to a
* notification server was made.
*/
gboolean notify_init(const char *app_name);
/**
* Uninitializes the notifications library.
*
* This will be automatically called on exit unless previously called.
*/
void notify_uninit(void);
/**
* Returns whether or not the notification library is initialized.
*
* @return TRUE if the library is initialized, or FALSE.
*/
gboolean notify_is_initted(void);
/**
* Manually closes a notification.
*
* @param handle The notification handle.
*/
void notify_close(NotifyHandle *handle);
/**
* Returns the server information.
*
* The strings returned must be freed.
*
* @param ret_name The returned product name of the server.
* @param ret_vendor The returned vendor.
* @param ret_version The returned specification version supported.
*
* @return TRUE if the call succeeded, or FALSE if there were errors.
*/
gboolean notify_get_server_info(char **ret_name, char **ret_vendor,
char **ret_version);
/**
* Returns the server's capabilities.
*
* The returned list and the strings inside must all be freed.
*
* @return The list of capabilities, or NULL on error.
*/
GList *notify_get_server_caps(void);
/*@}*/
/**************************************************************************/
/** @name NotifyIcon API */
/**************************************************************************/
/*@{*/
/**
* Creates an icon with the specified icon URI.
*
* @param icon_uri The icon URI.
*
* @return The icon.
*/
NotifyIcon *notify_icon_new(const char *icon_uri);
/**
* Creates an icon with the specified icon data.
*
* @param icon_len The icon data length.
* @param icon_data The icon data.
*
* @return The icon.
*/
NotifyIcon *notify_icon_new_with_data(size_t icon_len,
const guchar *icon_data);
/**
* Destroys an icon.
*
* @param icon The icon to destroy.
*/
void notify_icon_destroy(NotifyIcon *icon);
/*@}*/
/**************************************************************************/
/** @name Notifications API */
/**************************************************************************/
/*@{*/
/**
* Sends a notification.
*
* A callback has the following prototype:
*
* @code
* void callback(NotifyHandle *handle, guint32 action_id, void *user_data);
* @endcode
*
* @param replaces The ID of the notification to atomically replace
* @param urgency The urgency level.
* @param summary The summary of the notification.
* @param detailed The optional detailed information.
* @param icon The optional icon.
* @param expires TRUE if the notification should automatically expire,,
* or FALSE to keep it open until manually closed.
* @param expire_time The optional time to automatically close the
* notification, or 0 for the daemon's default.
* @param user_data User-specified data to send to a callback.
* @param action_count The number of actions.
* @param ... The actions in uint32/string/callback sets.
*
* @return A unique ID for the notification.
*/
NotifyHandle *notify_send_notification(NotifyHandle *replaces,
NotifyUrgency urgency,
const char *summary,
const char *detailed,
const NotifyIcon *icon,
gboolean expires, time_t expire_time,
gpointer user_data,
size_t action_count, ...);
/**
* Sends a notification, taking a va_list for the actions.
*
* A callback has the following prototype:
*
* @code
* void callback(NotifyHandle *handle, guint32 action, void *user_data);
* @endcode
*
* @param replaces The handle of the notification to atomically replace
* @param urgency The urgency level.
* @param summary The summary of the notification.
* @param detailed The optional detailed information.
* @param icon The optional icon.
* @param expires TRUE if the notification should automatically expire,
* or FALSE to keep it open until manually closed.
* @param expire_time The optional time to automatically close the
* notification, or 0 for the daemon's default.
* @param user_data User-specified data to send to a callback.
* @param action_count The number of actions.
* @param actions The actions in string/callback pairs.
*
* @return A unique ID for the notification.
*/
NotifyHandle *notify_send_notification_varg(NotifyHandle *replaces,
NotifyUrgency urgency,
const char *summary,
const char *detailed,
const NotifyIcon *icon,
gboolean expires,
time_t expire_time,
gpointer user_data,
size_t action_count,
va_list actions);
/*@}*/
#endif /* _LIBNOTIFY_NOTIFY_H_ */
|
