axl main logo
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Modules Pages
void axl_error_new ( int  code,
char *  error_code,
axlStream stream,
axlError **  _error 

Allows to create a new axlError value that contains an error code and a error string.

axlError error reporting abstraction is a convenient way for the developer and the user that makes use of the API to report and get textual diagnostic errors produced. Many times, API provided do not allow to get more information if something wrong happen making it difficult to reach and solve the problem (including the development phase).

From a developer's perspective, here is how works axlError,

1 void some_public_exported_function (int param, axlError ** error)
2 {
3  // do some work, but if it fails call to produce the error
4  // reporting.
5  axl_error_new (-2, // reporting an error code
6  "Something wasn't ok while processing..",
7  NULL, // a reference to the stream (optional)
8  error); // variable received.
9  return;
10 }

Previous construction makes error reporting optional but at the same time, available, because the programmer doesn't requires to check if the user did define the error variable, making it available at user option.

Now, if the user defines the axlError reference, by calling to the function, it can get the error reported as follows:

1 // declare the variable and it to null
2 axlError * error = NULL;
4 // call to function
5 some_pulic_exported_function (10, &error);
6 if (! axl_error_was_ok (error)) {
7  // drop the message
8  printf ("Something has failed: (code: %d) %s\n",
9  axl_error_get_code (error),
10  axl_error_get (error));
11  // dealloc the reference
12  axl_error_free (error);
13 }

Alternatively, the user can just bypass the error reporting mechanism, without affecting the written code inside the source of the function supporting the axlError notification (even if the code calls to axl_error_new):

1 // call to the function without error reporting
2 some_pulic_exported_function (10, NULL);

In most cases, axl_error_new is not used by API consumers but by API developers. Once returned the axlError reference the following functions could be checked.

codeThe error code to set and the error code string.
error_codeString to report.
streamIf provided, the error will try to get current stream position to add more information to the place where the error was found.
_errorThe error string to be used to initialize the received axlError.

References AXL_LEVEL_CRITICAL, axl_log(), axl_new, axl_strdup(), axl_stream_get_following(), axl_stream_get_global_index(), axl_stream_get_index(), axl_stream_get_near_to(), axl_stream_get_size(), and axl_stream_strdup_printf().

Referenced by axl_dtd_check_entity_ref_and_expand(), axl_dtd_validate(), axl_ns_doc_validate(), and axl_stream_new().