![]() |
![]() |
![]() |
libtinynotify Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <tinynotify.h> typedef NotificationCloseReason; extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_DISCONNECT; extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_CALLER; extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_EXPIRATION; extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_USER; void (*NotificationCloseCallback) (Notification notification
,NotificationCloseReason close_reason
,void *user_data
); extern const NotificationCloseCallback NOTIFICATION_FREE_ON_CLOSE; extern const NotificationCloseCallback NOTIFICATION_NOOP_ON_CLOSE; extern const NotificationCloseCallback NOTIFICATION_NO_CLOSE_CALLBACK; void notification_bind_close_callback (Notification notification
,NotificationCloseCallback callback
,void *user_data
); void (*NotificationActionCallback) (Notification notification
,const char *key
,void *user_data
); extern const NotificationActionCallback NOTIFICATION_NO_ACTION; extern const char* const NOTIFICATION_DEFAULT_ACTION; extern const char* const NOTIFICATION_AUTO_ACTION_KEY; void notification_bind_action (Notification notification
,const char *key
,NotificationActionCallback callback
,void *user_data
,const char *description
); typedef NotifyDispatchStatus; extern const NotifyDispatchStatus NOTIFY_DISPATCH_DONE; extern const NotifyDispatchStatus NOTIFY_DISPATCH_ALL_CLOSED; extern const NotifyDispatchStatus NOTIFY_DISPATCH_NOT_CONNECTED; extern const int NOTIFY_SESSION_NO_TIMEOUT; NotifyDispatchStatus notify_session_dispatch (NotifySession session
,int timeout
);
A more advanced functionality of libtinynotify is provided via the so-called event API.
The core of the event API are callbacks bound to Notification -specific events. When a notification with at least a single callback bound is send through a particular NotifySession, the notification becomes associated to that session and it must not be freed before it is closed.
Thus, one must either bind to the close event explicitly and use a callback to free a Notification afterwards, or ensure to disconnect the associated NotifySession first (which guarantees sending the close event).
typedef unsigned char NotificationCloseReason;
A reason for which the notification was closed.
extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_DISCONNECT;
A constant passed to NotificationCloseCallback when the close event is emitted because of the NotifySession being disconnected.
Note that this doesn't actually mean the notification was closed. It just means that libtinynotify didn't receive a NotificationClosed signal before the connection was interrupted. The notification may still be open, or be long gone (if daemon failed to send the signal).
extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_CALLER;
A constant passed to NotificationCloseCallback when the notification was
closed by a call to notification_close()
.
extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_EXPIRATION;
A constant passed to NotificationCloseCallback when the notification was closed because of the expiration timeout.
extern const NotificationCloseReason NOTIFICATION_CLOSED_BY_USER;
A constant passed to NotificationCloseCallback when the notification was closed because of the user action.
void (*NotificationCloseCallback) (Notification notification
,NotificationCloseReason close_reason
,void *user_data
);
The callback for notification closed event. It is invoked once and only once
per a single notification_send()
call.
After this event, no more events can be sent from the particular
Notification until notification_send()
or notification_update()
is used.
Thus, this event is a good place to inject a simple GC.
Note: the close_reason
parameter may contain a value not listed in constants
in this section. If it does so, one should assume the reason is unknown.
|
the notification which was closed |
|
reason for which the notification was closed |
|
additional user data pointer as passed
to notification_bind_close_callback()
|
extern const NotificationCloseCallback NOTIFICATION_FREE_ON_CLOSE;
A callback function for notification_bind_close_callback()
which frees
Notification as soon as it's closed.
Note: when using this callback, one must not use the same Notification after sending it for the first time as it will become invalid at a random point in time.
extern const NotificationCloseCallback NOTIFICATION_NOOP_ON_CLOSE;
A dummy callback function for notification_bind_close_callback()
. It may be
used if one isn't interested in the notification being closed itself but
just wants notify_session_dispatch()
to block until all notifications are
closed.
extern const NotificationCloseCallback NOTIFICATION_NO_CLOSE_CALLBACK;
A constant used to disable close callback.
void notification_bind_close_callback (Notification notification
,NotificationCloseCallback callback
,void *user_data
);
Bind a callback function which will be executed when notification is closed,
or remove a current binding (when callback
is
NOTIFICATION_NO_CLOSE_CALLBACK
).
A few standard callbacks are provided as well:
|
notification to operate on |
|
new callback function, or NOTIFICATION_NO_CLOSE_CALLBACK
to disable |
|
additional user data to pass to the callback |
void (*NotificationActionCallback) (Notification notification
,const char *key
,void *user_data
);
The callback for invoked action.
|
the notification which was closed |
|
the key for invoked action |
|
additional user data pointer as passed
to notification_bind_action()
|
extern const NotificationActionCallback NOTIFICATION_NO_ACTION;
A constant for callback used to disable/remove action.
extern const char* const NOTIFICATION_DEFAULT_ACTION;
A special (reserved) action key which makes the passed action a default one. It corresponds to the `default` key reserved by the protocol.
Note that the default action may be not be displayed as a regular action (i.e. with its description).
extern const char* const NOTIFICATION_AUTO_ACTION_KEY;
A special value for action key which makes libtinynotify autogenerate it. This means one doesn't need to type in the key, and it is guaranteed to be unique.
On the other hand, using autogenerated keys mean one is unable to know keys
assigned to created actions. Thus, when using NOTIFICATION_AUTO_ACTION_KEY
,
no further actions shall use hand-written keys.
void notification_bind_action (Notification notification
,const char *key
,NotificationActionCallback callback
,void *user_data
,const char *description
);
Add an action to the notification and bind a callback function for it. The callback function will be executed whenever user invokes the particular action. Note that it may be called multiple times.
The key must be unique per action. Special value NOTIFICATION_DEFAULT_ACTION
corresponds to the default action.
Actions are sent to server in the order of adding them. If one calls
notification_bind_action()
again with the same key, the previous action will
be replaced by the new one without changing its position.
If one calls notification_bind_action()
with callback
==
NOTIFICATION_NO_ACTION
, the existing action will be removed (if exists;
otherwise nothing will happen). Afterwards, adding the same action again will
move it to the end of action list.
If description
is NULL
, it will default to key
. This is usually not a good
idea.
|
notification to operate on |
|
a key for the new (or replaced) action, or NOTIFICATION_DEFAULT_ACTION
|
|
a callback function, or NOTIFICATION_NO_ACTION
|
|
user data to pass to the callback |
|
human-readable action description |
typedef const int NotifyDispatchStatus;
A return value from notify_session_dispatch()
.
Note that the NOTIFY_DISPATCH_DONE
constant is guaranteed always
to evaluate to a false value. Thus, one can use NotifyDispatchStatus
as a boolean.
extern const NotifyDispatchStatus NOTIFY_DISPATCH_DONE;
A constant denoting that the notify_session_dispatch()
completed
successfully, and there may be more messages to dispatch in the future.
extern const NotifyDispatchStatus NOTIFY_DISPATCH_ALL_CLOSED;
A constant denoting that the notify_session_dispatch()
completed
successfully, and doesn't expect any further events to come unless
a new notification is sent (all notifications were closed).
extern const NotifyDispatchStatus NOTIFY_DISPATCH_NOT_CONNECTED;
A constant denoting that the notify_session_dispatch()
failed because
the connection is not established (anymore). This could happen also
if the client was disconnected for some reason.
As disconnect results in sending 'close' event for all open notifications,
this could be treated similar to NOTIFY_DISPATCH_ALL_CLOSED
.
extern const int NOTIFY_SESSION_NO_TIMEOUT;
A constant for notify_session_dispatch()
denoting that the session should
block until a message is received.
NotifyDispatchStatus notify_session_dispatch (NotifySession session
,int timeout
);
Perform any I/O necessary for D-Bus and dispatch any new messages.
The return value can be treated as a boolean stating whether more events are expected, and thus used to terminate the main loop. Note, however, that if for some reason the notification daemon doesn't send NotificationClosed signal, the program may deadlock waiting for it. In order to avoid that, one should use a kind of timeout timer.
|
session to operate on |
|
max time to block in milliseconds, or NOTIFY_SESSION_NO_TIMEOUT
|
Returns : |
NOTIFY_DISPATCH_DONE (which evaluates to false) unless
no more events are expected to come |