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,

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

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:

 // declare the variable and it to null 
 axlError * error = NULL;

 // call to function
 some_pulic_exported_function (10, &error);
 if (! axl_error_was_ok (error)) {
     // drop the message 
     printf ("Something has failed: (code: %d) %s\n",
             axl_error_get_code (error),
             axl_error_get (error));
     // dealloc the reference 
     axl_error_free (error);
 }

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):

 // call to the function without error reporting 
 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.

  • axl_error_was_ok allows to check if some error was reported, base on the value initialization.

Parameters:
code The error code to set and the error code string.
error_code String to report.
stream If provided, the error will try to get current stream position to add more information to the place where the error was found.
_error The error string to be used to initialize the received axlError.