Error message handling

How to deal with error messages. More...

Functions
int	caps_cl_error_messages_catch (struct caps_cl_handle *instance, char **ptr, size_t *size)
void	caps_cl_error_messages_reset (struct caps_cl_handle *instance)

Detailed Description

Usually the error messages are handled by libcapsbase and are sent to stderr by default. For a console tool or a background process this might be a good choice. For a somehow graphical interactive application it makes more sense to be able to present the error message to the user.

Enable this feature immediately after the client instance creation and libcapsclient forwards all error messages to this buffer instead. If you catch an error code by one of the client functions, the buffer will contain a corresponding error message terminated by a '\0' character. This message uses the current locale and so, the error message might be already translated to the local language. If you like more the size of the string instead of the terminating '\0' character, you can use the size_t variable instead. Refer the manual page of the open_memstream() for details.

Note

Only some functions from the libcapsclient will emit their error messages in this way. The API description will mention this behaviour.

It is in your responsibility to manage the used buffer. The memory was dynamically allocated and needs to be freed after use.

Attention

Free the memory after calling caps_cl_instance_destroy()

In your program it looks like that:

struct caps_cl_handle *instance;
size_t error_size;
char *error_buf;
int rc;
 
 instance = caps_cl_instance_create();
 caps_cl_error_messages_catch(instance, &error_buf, error_size);
 rc = caps_cl_instance_register(instance, NULL, NULL);
 if (rc < 0) {
   // error_buf no contains a message of size error_size
   goto clean_up;
 }
 
 // […]all your work here[…]
 
 caps_cl_instance_unregister(instance);
clean_up:
 caps_cl_instance_destroy(instance);
 free(error_buf);

Function Documentation

caps_cl_error_messages_catch()

int caps_cl_error_messages_catch	(	struct caps_cl_handle *	instance,
		char **	ptr,
		size_t *	size
	)

Setup a self growing storage to catch error messages

Parameters

[in,out]	instance	Client instance
[out]	ptr	Where to store the base address of the buffer
[out]	size	Where to store the buffer size

Return values

0	Error catching successfully initialized
negative	errno from the open_memstream() call

If your local ptr is still NULL or your local size is still '0', then no error messages were created. Else the memory was dynamically allocated and needs to be freed after use. The buffer contains a '\0' terminated string.

Precondition

instance must be a valid client instance handle returned by caps_cl_instance_create() call

Postcondition

The allocated memory needs to be freed after its use

Todo:

What about more than one error message at the same time?

caps_cl_error_messages_reset()

void caps_cl_error_messages_reset

(

struct caps_cl_handle *

instance

)

Reset the error message buffer

Parameters

[in,out]

instance

Client instance

If you have processed an error message, you can reset the buffer for the next error message.

Precondition

instance must be a valid client instance handle returned by caps_cl_instance_create() call