![]() |
![]() |
![]() |
libtinynotify Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <tinynotify.h> typedef NotifySession; NotifySession notify_session_new (const char *app_name
,const char *app_icon
); void notify_session_free (NotifySession session
); NotifyError notify_session_connect (NotifySession session
); void notify_session_disconnect (NotifySession session
); extern const char* const NOTIFY_SESSION_NO_APP_NAME; void notify_session_set_app_name (NotifySession session
,const char *app_name
); extern const char* const NOTIFY_SESSION_NO_APP_ICON; void notify_session_set_app_icon (NotifySession session
,const char *app_icon
);
All interaction with libtinynotify is associated with a single session,
represented by the NotifySession type. Before calling any of the library
functions, one must instantiate a new session using notify_session_new()
.
When done with it, one should free the session using notify_session_free()
.
One must not pass custom, invalid or freed NotifySession to any of the functions. Otherwise, the results are unpredictable (and a segfault is the most harmless of them). One must not attempt to modify or manually free a NotifySession instance, and one shall not assume anything specific about its actual type. When in question, one should pass a pointer to it rather than casting NotifySession to one.
typedef struct _notify_session* NotifySession;
A type describing a basic tinynotify session. It holds the data necessary for the notifications to be sent, like the D-Bus connection. It also provides a storage for errors.
It should be created using notify_session_new()
, and disposed using
notify_session_free()
.
NotifySession notify_session_new (const char *app_name
,const char *app_icon
);
Create and initialize a new libtinynotify session. Sets the default
app_name
(unless NOTIFY_SESSION_NO_APP_NAME
) and app_icon
(unless
NOTIFY_SESSION_NO_APP_ICON
).
This function always succeeds. If it is unable to allocate the memory, program execution will be aborted.
|
default application name for the session |
|
default application icon for the session |
Returns : |
a newly-instantiated NotifySession |
void notify_session_free (NotifySession session
);
Free a libtinynotify session. This handles disconnecting and other cleanup as well.
This function always succeeds. After a call to this function, a NotifySession is no longer valid.
|
the session to free |
NotifyError notify_session_connect (NotifySession session
);
Establish a connection to the D-Bus session bus.
Note that calling this function is not obligatory. If not used, the connection will be established when sending the first notification.
If a connection is established already, this function does nothing
and returns NOTIFY_ERROR_NO_ERROR
. If the connection was established
and got disconnected for some reason (e.g. by the remote end), this function
will try to re-establish it transparently.
|
session to operate on |
Returns : |
a NotifyError or NOTIFY_ERROR_NO_ERROR if connection succeeds.
For additional error details, see notify_session_get_error_message() . |
void notify_session_disconnect (NotifySession session
);
Drop the connection to the D-Bus session bus.
Note that calling this function is not obligatory. It will be called
by notify_session_free()
anyway.
If no connection is established already, this function does nothing.
|
session to operate on |
extern const char* const NOTIFY_SESSION_NO_APP_NAME;
A constant specifying that no default app name is to be specified.
void notify_session_set_app_name (NotifySession session
,const char *app_name
);
Set the default application name for notifications sent through this session.
This should be the formal application name rather than an ID.
If NOTIFY_SESSION_NO_APP_NAME
is passed, the default application name will
be cleared. Otherwise, the given string will be copied to NotifySession.
|
session to operate on |
|
a new app name |
extern const char* const NOTIFY_SESSION_NO_APP_ICON;
A constant specifying that no default app icon is to be specified.
void notify_session_set_app_icon (NotifySession session
,const char *app_icon
);
Set the default application icon for notifications sent through this session.
The value should be either a name in freedesktop.org-compliant icon scheme, or a file:// URI.
If NOTIFY_SESSION_NO_APP_ICON
is passed, the default application icon will
be cleared. Otherwise, the given string will be copied to NotifySession.
|
session to operate on |
|
a new icon name |