NotifyError

NotifyError — API to deal with libtinynotify errors

Synopsis

#include <tinynotify.h>

typedef             NotifyError;
extern const NotifyError NOTIFY_ERROR_NO_ERROR;
extern const NotifyError NOTIFY_ERROR_DBUS_CONNECT;
extern const NotifyError NOTIFY_ERROR_DBUS_SEND;
extern const NotifyError NOTIFY_ERROR_INVALID_REPLY;
extern const NotifyError NOTIFY_ERROR_NO_NOTIFICATION_ID;
NotifyError         notify_session_get_error            (NotifySession session);
const char *        notify_session_get_error_message    (NotifySession session);
NotifyError         notify_session_set_error            (NotifySession session,
                                                         NotifyError new_error,
                                                         ...);

Description

All actual error handling in libtinynotify is done within the bounds of a NotifySession. Each of the libtinynotify functions (except for notify_session_new(), notify_session_free() and error grabbing funcs) store their results and any additional error details in the corresponding NotifySession.

After a call to such a function, one may get its error status using notify_session_get_error(). If a function returns NotifyError, then it is guaranteed that the return value is equal to the result of calling notify_session_get_error() immediately after the function.

One may assume that NOTIFY_ERROR_NO_ERROR will always evaluate to false. Thus, NotifyError can be used as a boolean result as well.

A more detailed error description can be obtained using notify_session_get_error_message(). It can contain additional details not available via NotifyError like backend error messages.

The libtinynotify functions don't check for existing error conditions. It is unnecessary to reset the error within NotifySession (and thus there is no function implementing such a thing). Calling another function will implicitly reset the current error status, and replace with its own result.

Details

NotifyError

typedef const struct notify_error* NotifyError;

A tinynotify error code.

Note that NOTIFY_ERROR_NO_ERROR is guaranteed to be always false. Thus, one can use this type as a boolean for error indication.

NOTIFY_ERROR_NO_ERROR

extern const NotifyError NOTIFY_ERROR_NO_ERROR;

A constant denoting that no error occured.

NOTIFY_ERROR_DBUS_CONNECT

extern const NotifyError NOTIFY_ERROR_DBUS_CONNECT;

An error occuring while establishing the D-Bus connection.

NOTIFY_ERROR_DBUS_SEND

extern const NotifyError NOTIFY_ERROR_DBUS_SEND;

An error occuring while trying to send the D-Bus message.

NOTIFY_ERROR_INVALID_REPLY

extern const NotifyError NOTIFY_ERROR_INVALID_REPLY;

An error denoting that the return value from a D-Bus method call is invalid.

NOTIFY_ERROR_NO_NOTIFICATION_ID

extern const NotifyError NOTIFY_ERROR_NO_NOTIFICATION_ID;

An error denoting that the Notification has no ID associated while it is necessary for the function to proceed (e.g. when using notification_close() on an unsubmitted notification).

notify_session_get_error ()

NotifyError         notify_session_get_error            (NotifySession session);

Get current error for session.

`session` :	session to operate on
Returns :	positive NotifyError or `NOTIFY_ERROR_NO_ERROR` if no error

notify_session_get_error_message ()

const char *        notify_session_get_error_message    (NotifySession session);

Get detailed error message for session.

`session` :	session to operate on
Returns :	a statically allocated or constant string (not to be freed)

notify_session_set_error ()

NotifyError         notify_session_set_error            (NotifySession session,
                                                         NotifyError new_error,
                                                         ...);

Set a new error in session session.

Note: this function is mostly intended for internal use in submodules.

`session` :	session to operate on
`new_error` :	new error code
`...` :	additional arguments for error message format string
Returns :	same value as `new_error`, for convenience.

			libtinynotify Reference Manual
Top \| Description