Callback-based message reporting to the user.
This API helps in avoiding the abuse of strerror()-like functions and allowing for more meaningful and contextualized information.
The basic idea is that, on one hand, one or more message boxes are created and callbacks are associated to them in order to process (e.g., display) the messages, while on the other hand messages are created using the functions offered by this API, which are also in charge of delivering them.
There are two kinds of messages: status messages and text messages. The former are used to notify the beginning and the end of a lengthy and/or complex operation, as well as its end result. The latter consist of just simple text with a severity attribute.
Messages are implicitly organized into a hierarchy where each of them belongs to a certain context, which is either a message box or a status message.
Message reporting | Callback-based message reporting to the user. |
Enumerations | |
nacore_msg_severity | Severity of a text message. |
nacore_msg_result | Result of an operation described by a status message. |
Types | |
nacore_msg_context | Message context (message box or status message). |
nacore_msg_status_begin_cb | Status message begin callback. |
nacore_msg_status_end_cb | Status message end callback. |
nacore_msg_text_cb | Text message callback. |
Functions | |
nacore_msg_box_new() | Creates a new message box. |
nacore_msg_box_free() | Destroys a message box. |
nacore_msg_box_set_callbacks() | Associates callbacks to a message box. |
nacore_msg_status_begin() | Creates a new status message, possibly notifying it to the status message begin callback. |
nacore_msg_status_end() | Possibly reports the result of the operation described by a status message to the status message end callback and destroys such status message. |
nacore_msg_text() | Possibly reports a new text message to the text message callback. |
nacore_msg_context_get_opaque() | Gets the opaque data associated to a given message context. |
nacore_msg_context_get_parent() | Gets the parent message context of a given message context. |
typedef void ( * nacore_msg_status_begin_cb )(nacore_msg_context status_msg, const char *text, void *opaque)
Status message begin callback.
After the execution of the callback, text cannot be assumed to be still valid.
status_msg | Message context representing the status message. |
text | Message text. |
opaque | Extra opaque data associated to the message or NULL. |
typedef void ( * nacore_msg_status_end_cb )(nacore_msg_context status_msg, nacore_msg_result result, void *opaque)
Status message end callback.
status_msg | Message context represeting the status message. |
result | Result of the operation described by status_msg. |
opaque | Extra opaque data associated to the message or NULL. |
typedef void ( * nacore_msg_text_cb )(nacore_msg_context context, nacore_msg_severity severity, const char *text, void *opaque)
Text message callback.
After the execution of the callback, text cannot be assumed to be still valid.
context | Message context the text message belongs to. |
severity | Severity of the text message. |
text | Message text. |
opaque | Extra opaque data associated to the message or NULL. |
_NACORE_DEF void nacore_msg_box_free( nacore_msg_context msg_box )
Destroys a message box.
It is not thread-safe to concurrently use this function while operating on the message box and/or the messages directly or indirectly belonging to it.
Furthermore it should only be used when all the status messages belonging to it have been already destroied.
Once this function function is called, referring to msg_box will cause undefined behavior.
msg_box | Message context representing the message box. |
_NACORE_DEF void nacore_msg_box_set_callbacks( nacore_msg_context msg_box, nacore_msg_status_begin_cb status_begin_cb, nacore_msg_status_end_cb status_end_cb, nacore_msg_text_cb text_cb )
Associates callbacks to a message box.
It is not thread-safe to concurrently use this function while operating on the message box and/or the messages directly or indirectly belonging to it.
The function should be called only when there are no messages in the message box (i.e., all status messages belonging to it have been ended).
msg_box | Message context representing the message box. |
status_begin_cb | Status message begin callback or NULL. |
status_end_cb | Status message end callback or NULL. |
text_cb | Text message callback or NULL. |
_NACORE_DEF NACORE_FORMAT_PRINTF( 3, 4 ) nacore_msg_context nacore_msg_status_begin(nacore_msg_context context, void *opaque, const char *fmt, ...)
Creates a new status message, possibly notifying it to the status message begin callback.
In order to simplify the usage of the API, context can be NULL, in which case the function doesn’t do anything but returning NULL.
Furthermore, this function uses nacore_vasprintf() internally to create the text string, hence refer to the documentation of that function for details on how the text formatting is done.
The text should read like “Doing something”, with the first letter in capital case if possible.
This function is not thread-safe if the message box has a status message begin callback associated to it that is not thread-safe or if another thread changes locale settings of the calling thread while it is running.
context | Message context the new status message will belong to or NULL. |
opaque | Extra opaque data to be associated to the message or NULL. |
fmt | printf()-like format string. |
... | printf()-like extra arguments. |
NULL if context is NULL or the message box has no status message begin callback associated to it, otherwise the message context representing the status message or NULL if there was not enough memory.
_NACORE_DEF void nacore_msg_status_end( nacore_msg_context status_msg, nacore_msg_result result )
Possibly reports the result of the operation described by a status message to the status message end callback and destroys such status message.
In order to simplify the usage of the API, status_msg can be NULL, in which case the function does nothing.
A status message should be ended only when all its child status messages have been ended already.
This function is not thread-safe if the message box has a status message end callback associated to it that is not thread-safe or if another thread changes locale settings of the calling thread while it is running.
status_msg | Message context representing the status message or NULL. |
result | Result of the operation described by status_msg. |
_NACORE_DEF NACORE_FORMAT_PRINTF( 4, 5 ) void nacore_msg_text(nacore_msg_context context, nacore_msg_severity severity, void *opaque, const char *fmt, ...)
Possibly reports a new text message to the text message callback.
In order to simplify the usage of the API, context can be NULL, in which case the function does nothing.
Furthermore, this function uses nacore_vasprintf() internally to create the text string, hence refer to the documentation of that function for details on how the text formatting is done.
The text message should read like “Bla bla bla”, with the first letter in capital case if possible.
This function is not thread-safe if the message box has a text callback associated to it that is not thread-safe or if another thread changes locale settings of the calling thread while it is running.
context | Message context the new text message will belong to or NULL. |
severity | Severity of the text message. |
opaque | Extra opaque data to be associated to the message or NULL. |
fmt | printf()-like format string. |
... | printf()-like extra arguments. |
_NACORE_DEF nacore_msg_context nacore_msg_context_get_parent( nacore_msg_context context )
Gets the parent message context of a given message context.
context | The message context. |
The parent message context if the given message context is a status message, NULL if it is a message box.
Message context (message box or status message).
typedef struct _nacore_msg_context * nacore_msg_context
Status message begin callback.
typedef void ( * nacore_msg_status_begin_cb )(nacore_msg_context status_msg, const char *text, void *opaque)
Status message end callback.
typedef void ( * nacore_msg_status_end_cb )(nacore_msg_context status_msg, nacore_msg_result result, void *opaque)
Text message callback.
typedef void ( * nacore_msg_text_cb )(nacore_msg_context context, nacore_msg_severity severity, const char *text, void *opaque)
Creates a new message box.
_NACORE_DEF nacore_msg_context nacore_msg_box_new( void * opaque )
Destroys a message box.
_NACORE_DEF void nacore_msg_box_free( nacore_msg_context msg_box )
Associates callbacks to a message box.
_NACORE_DEF void nacore_msg_box_set_callbacks( nacore_msg_context msg_box, nacore_msg_status_begin_cb status_begin_cb, nacore_msg_status_end_cb status_end_cb, nacore_msg_text_cb text_cb )
Creates a new status message, possibly notifying it to the status message begin callback.
_NACORE_DEF NACORE_FORMAT_PRINTF( 3, 4 ) nacore_msg_context nacore_msg_status_begin(nacore_msg_context context, void *opaque, const char *fmt, ...)
Possibly reports the result of the operation described by a status message to the status message end callback and destroys such status message.
_NACORE_DEF void nacore_msg_status_end( nacore_msg_context status_msg, nacore_msg_result result )
Possibly reports a new text message to the text message callback.
_NACORE_DEF NACORE_FORMAT_PRINTF( 4, 5 ) void nacore_msg_text(nacore_msg_context context, nacore_msg_severity severity, void *opaque, const char *fmt, ...)
Gets the opaque data associated to a given message context.
_NACORE_DEF void * nacore_msg_context_get_opaque( nacore_msg_context context )
Gets the parent message context of a given message context.
_NACORE_DEF nacore_msg_context nacore_msg_context_get_parent( nacore_msg_context context )
Analog of vsprintf() that allocates a string large enough to hold the output including the terminating null character.
_NACORE_DEF NACORE_FORMAT_VPRINTF( 2 ) int nacore_vasprintf(char **strp, const char *fmt, va_list ap)