Message reporting

Callback-based message reporting to the user.

This API helps in avoiding the use 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 conventions

  • The caller function may create a status message regarding the operations of a called function, not the other way round (e.g., main() creates a status message saying “Reading files x”, then it calls read_file()).
  • The result of a status message shall be set by the caller function and never by the called function.
  • When displaying, the last received text message with the highet severity is the main message to be displayed.
  • The text of a message is meant to be plain text, not HTML or similar.
  • Messages referring to a certain line/column should be formatted like “line:column: message”.
  • The first character in the text of a message should be in upper case if alphabetical, except for identifiers, etc.
  • One message, one sentence.
  • Do not end the text of a message with a period.
Summary
Message reportingCallback-based message reporting to the user.
Enumerations
nacore_msg_severitySeverity of a text message.
nacore_msg_resultResult of an operation described by a status message.
Types
nacore_msg_contextMessage context (message box or status message).
nacore_op_with_msg_cbLike nacore_op_cb but also passes message reporting-related data.
nacore_msg_status_begin_cbStatus message begin callback.
nacore_msg_status_end_cbStatus message end callback.
nacore_msg_text_cbText message callback.
Functions
nacore_msg_box_new()Creates a new message box.
nacore_msg_box_free()Destroies 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 destroies 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.

Enumerations

nacore_msg_severity

Severity of a text message.

nacore_msg_severity_infoInformation message, nothing to worry about.
nacore_msg_severity_warnWarning message, something weird happened, could be a problem.
nacore_msg_severity_errError message, impossible to get past this point with the operation.

nacore_msg_result

Result of an operation described by a status message.

nacore_msg_result_okEverything fine.
nacore_msg_result_warnWarning.
nacore_msg_result_errError.

Types

nacore_msg_context

typedef struct _nacore_msg_context * nacore_msg_context

Message context (message box or status message).

nacore_op_with_msg_cb

typedef void (
   *nacore_op_with_msg_cb
)(void *value, nacore_msg_context msg_context, void *msg_opaque, void *opaque)

Like nacore_op_cb but also passes message reporting-related data.

Paramters

valuePointer to the value to operate on.
msg_contextMessage context or NULL.
msg_opaqueExtra opaque data to be passed to message reporting callback or NULL.
opaqueExtra opaque data pointer or NULL.

nacore_msg_status_begin_cb

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.

Parameters

status_msgMessage context representing the status message.
textMessage text.
opaqueExtra opaque data associated to the message or NULL.

nacore_msg_status_end_cb

typedef void (
   *nacore_msg_status_end_cb
)(nacore_msg_context status_msg, nacore_msg_result result, void *opaque)

Status message end callback.

Parameters

status_msgMessage context represeting the status message.
resultResult of the operation described by status_msg.
opaqueExtra opaque data associated to the message or NULL.

nacore_msg_text_cb

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.

Parameters

contextMessage context the text message belongs to.
severitySeverity of the text message.
textMessage text.
opaqueExtra opaque data associated to the message or NULL.

Functions

nacore_msg_box_new()

_NACORE_DEF nacore_msg_context nacore_msg_box_new(void *opaque)

Creates a new message box.

Parameters

opaqueExtra opaque data to be associated to the message box or NULL.

Returns

Message context representing the message box or NULL if there was not enough memory.

nacore_msg_box_free()

_NACORE_DEF void nacore_msg_box_free(nacore_msg_context msg_box)

Destroies 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.

Parameters

msg_boxMessage context representing the message box.

nacore_msg_box_set_callbacks()

_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).

Parameters

msg_boxMessage context representing the message box.
status_begin_cbStatus message begin callback or NULL.
status_end_cbStatus message end callback or NULL.
text_cbText message callback or NULL.

nacore_msg_status_begin()

_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.

Parameters

contextMessage context the new status message will belong to or NULL.
opaqueExtra opaque data to be associated to the message or NULL.
fmtprintf()-like format string.
...printf()-like extra arguments.

Returns

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_msg_status_end()

_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 destroies 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.

Parameters

status_msgMessage context representing the status message or NULL.
resultResult of the operation described by status_msg.

nacore_msg_text()

_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.

Parameters

contextMessage context the new text message will belong to or NULL.
severitySeverity of the text message.
opaqueExtra opaque data to be associated to the message or NULL.
fmtprintf()-like format string.
...printf()-like extra arguments.

nacore_msg_context_get_opaque()

_NACORE_DEF void * nacore_msg_context_get_opaque(nacore_msg_context context)

Gets the opaque data associated to a given message context.

Parameters

contextThe message context.

Returns

The opaque data associated to the message context or NULL.

nacore_msg_context_get_parent()

_NACORE_DEF nacore_msg_context nacore_msg_context_get_parent(
   nacore_msg_context context
)

Gets the parent message context of a given message context.

Parameters

contextThe message context.

Returns

The parent message context if the given message context is a status message, NULL if it is a message box.

typedef struct _nacore_msg_context * nacore_msg_context
Message context (message box or status message).
typedef void (
   *nacore_op_with_msg_cb
)(void *value, nacore_msg_context msg_context, void *msg_opaque, void *opaque)
Like nacore_op_cb but also passes message reporting-related data.
typedef void (*nacore_op_cb)(void *value, void *opaque)
A function that performs some operation on a value.
typedef void (
   *nacore_msg_status_begin_cb
)(nacore_msg_context status_msg, const char *text, void *opaque)
Status message begin callback.
typedef void (
   *nacore_msg_status_end_cb
)(nacore_msg_context status_msg, nacore_msg_result result, void *opaque)
Status message end callback.
typedef void (
   *nacore_msg_text_cb
)(nacore_msg_context context, nacore_msg_severity severity, const char *text, void *opaque)
Text message callback.
_NACORE_DEF nacore_msg_context nacore_msg_box_new(void *opaque)
Creates a new message box.
_NACORE_DEF void nacore_msg_box_free(nacore_msg_context msg_box)
Destroies 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
)
Associates callbacks to a message box.
_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.
_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 destroies such status message.
_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.
_NACORE_DEF void * nacore_msg_context_get_opaque(nacore_msg_context context)
Gets the opaque data associated to a given message context.
_NACORE_DEF nacore_msg_context nacore_msg_context_get_parent(
   nacore_msg_context context
)
Gets the parent message context of a given message context.
_NACORE_DEF NACORE_FORMAT_VPRINTF(
   2
) int nacore_vasprintf(char **strp, const char *fmt, va_list ap)
Analog of vsprintf() that allocates a string large enough to hold the output including the terminating null character.
Close