/*==================================================================*\
| EXIP - Embeddable EXI Processor in C |
|--------------------------------------------------------------------|
| This work is licensed under BSD 3-Clause License |
| The full license terms and conditions are located in LICENSE.txt |
\===================================================================*/
/**
* @file errorHandle.h
* @brief Error handling codes and function definitions
*
* @date Jul 7, 2010
* @author Rumen Kyusakov
* @version 0.5
* @par[Revision] $Id: errorHandle.h 352 2014-11-25 16:37:24Z kjussakov $
*/
#ifndef ERRORHANDLE_H_
#define ERRORHANDLE_H_
#include "exipConfig.h"
#define INFO 1
#define WARNING 2
#define ERROR 3
/**
* @page debugging How to debug
*
* Turning the debugging is done by setting EXIP_DEBUG to ON.
* You have control over the level of verbosity (INFO, WARNING or ERROR)
* and the source of debugging information. All these parameters
* can be configured in the exipConfig.h header that is defined
* per target platform in build/gcc/[target platform].
* When turned on, the debugging information is by default
* printed on the standard output.
*
* @section configuration Debug configuration
* The following macro definitions are used to customize the debugging:
* <dl>
* <dt>EXIP_DEBUG</dt>
* <dd>Switch ON/OFF the debugging</dd>
* <dt>DEBUG_CHAR_OUTPUT(ch)</dt>
* <dd>Defines a function to print a single character ch</dd>
* <dt>DEBUG_OUTPUT(str)</dt>
* <dd>Defines a function to print a NULL terminated string str</dd>
* <dt>EXIP_DEBUG_LEVEL</dt>
* <dd>Verbosity level: one of INFO, WARNING or ERROR</dd>
* <dt>DEBUG_MSG(level, module, msg)</dt>
* <dd>Used to print a debug message</dd>
* </dl>
*
* @section error_codes Error codes
* Most of the functions in the exip library return a 8 bit integer that
* indicates the status of the execution with 0 being success and
* non-zero value indication an error condition.
* <p>
* The error codes are defined in errorHandle.h
* </p>
*
* @section debug_output Debug output
* DEBUG_STREAM_IO provides a detailed stream output and position debug messages. It shows byte-level
* output on a new line, beginning with '>>'. It indicates position of next write
* in the form \@B:b, where B is the byte offset and b is the bit offset within
* the byte.
*
* <div>
* Below is an example encoding for the EXI equivalent of "<description>new</description>". First,
* you see the local name for each production in the rule. Below the rule, the ">> 0x0 (3 bits)"
* tells exactly what was written to select the 'description' production at index 0.
* Then the "@8:4" shows the position at which the next output occurs. Just above the
* output below was "@8:1", where the present output was placed.
*
* To see this sort of output, use DEBUG_STREAM_IO and DEBUG_CONTENT_IO.
*
*
* <pre>
* >RULE
* NT-1:
* SE (qname: 4:34) NT-2 0 description
* SE (qname: 4:75) NT-3 1 notes
* SE (qname: 4:3) NT-4 2 activateAt
* SE (qname: 4:44) NT-5 3 expireAt
* SE (qname: 4:80) NT-6 4 panId
* SE (qname: 4:111) NT-7 5 timezoneId
* SE (qname: 4:33) NT-8 6 deploymentDevices
* EE 7
* >> 0x0 (3 bits) \@8:4
*
* >Start string data serialization
*
* >RULE
* NT-0:
* CH [2] NT-1 0
* AT (qname 2:1) [1] NT-0 1.0
* >> 0x0 (1 bits) \@8:5
* >> 0x05 \@8:6 \@9:5
*
* Write string, len 3: new
* >> 0x6E \@9:6 \@10:5
* >> 0x65 \@10:6 \@11:5
* >> 0x77 \@11:6 \@12:5
* >End element serialization
* </pre>
* </div>
*/
#if EXIP_DEBUG == ON
# include <stdio.h>
/* Platform specific debugging character output */
# ifndef DEBUG_CHAR_OUTPUT
# define DEBUG_CHAR_OUTPUT(character) do {putchar (character);} while(0)
# endif
/* Platform specific debugging formatted output */
# ifndef DEBUG_OUTPUT
# define DEBUG_OUTPUT(msg) do {printf msg;} while(0)
# endif
# ifndef EXIP_DEBUG_LEVEL
# define EXIP_DEBUG_LEVEL INFO
# endif
# define DEBUG_MSG(level, module, msg) do { if (level >= EXIP_DEBUG_LEVEL && module == ON) { DEBUG_OUTPUT(msg); } } while(0)
#else
# define DEBUG_MSG(level, module, msg)
#endif /* EXIP_DEBUG */
// IMPORTANT: remember to keep in sync with "errorCodeStrings[]" in procTypes.c!
/* Definitions for error constants. */
enum errorCode
{
/** No error, everything is OK. */
EXIP_OK = 0,
/** The code for this function
* is not yet implemented. */
EXIP_NOT_IMPLEMENTED_YET = 1,
/** Any error that does not fall
* into the other categories */
EXIP_UNEXPECTED_ERROR = 2,
/** Hash table error */
EXIP_HASH_TABLE_ERROR = 3,
/** Array out of bound */
EXIP_OUT_OF_BOUND_BUFFER = 4,
/** Try to access null pointer */
EXIP_NULL_POINTER_REF = 5,
/** Unsuccessful memory allocation */
EXIP_MEMORY_ALLOCATION_ERROR = 6,
/** Error in the EXI header */
EXIP_INVALID_EXI_HEADER = 7,
/** Processor state is inconsistent
* with the stream events */
EXIP_INCONSISTENT_PROC_STATE = 8,
/** Received EXI value type or event
* encoding that is invalid according
* to the specification */
EXIP_INVALID_EXI_INPUT = 9,
/** Buffer end reached */
EXIP_BUFFER_END_REACHED =10,
EXIP_PARSING_COMPLETE =11,
/** The information passed to
* the EXIP API is invalid */
EXIP_INVALID_EXIP_CONFIGURATION =12,
/** When encoding XML Schema in EXI the prefixes must be preserved:
* When qualified namesNS are used in the values of AT or CH events in an EXI Stream,
* the Preserve.prefixes fidelity option SHOULD be turned on to enable the preservation of
* the NS prefix declarations used by these values. Note, in particular among other cases,
* that this practice applies to the use of xsi:type attributes in EXI streams when Preserve.lexicalValues
* fidelity option is set to true. */
EXIP_NO_PREFIXES_PRESERVED_XML_SCHEMA =13,
EXIP_INVALID_STRING_OPERATION =14,
/** Mismatch in the header options.
* This error can be due to:
* 1) The "alignment" element MUST NOT appear in an EXI options document when the "compression" element is present;
* 2) The "strict" element MUST NOT appear in an EXI options document when one of "dtd", "prefixes",
* "comments", "pis" or "selfContained" element is present in the same options document. That is only the
* element "lexicalValues", from the fidelity options, is permitted to occur in the presence of "strict" element;
* 3) The "selfContained" element MUST NOT appear in an EXI options document when one of "compression",
* "pre-compression" or "strict" elements are present in the same options document.
* 4) The datatypeRepresentationMap option does not take effect when the value of the Preserve.lexicalValues
* fidelity option is true (see 6.3 Fidelity Options), or when the EXI stream is a schema-less EXI stream.
* 5) Presence Bit for EXI Options not set and no out-of-band options set
*/
EXIP_HEADER_OPTIONS_MISMATCH =15,
/**
* Send a signal to the EXIP parser from a content handler callback
* for gracefully stopping the EXI stream parsing.
*/
EXIP_HANDLER_STOP =16
};
typedef enum errorCode errorCode;
#if EXIP_DEBUG == ON
extern const char* errorCodeStrings[];
# define GET_ERR_STRING(indx) errorCodeStrings[indx]
#else
# define GET_ERR_STRING(indx) ""
#endif
# define TRY(func) do { tmp_err_code = func;\
if (tmp_err_code != EXIP_OK) { \
DEBUG_MSG(ERROR, EXIP_DEBUG, ("\n>Error %s:%d at %s, line %d", GET_ERR_STRING(tmp_err_code), tmp_err_code, __FILE__, __LINE__)); \
return tmp_err_code; } } while(0)
# define TRY_CATCH(func, cblock) do { tmp_err_code = func;\
if (tmp_err_code != EXIP_OK) { \
DEBUG_MSG(ERROR, EXIP_DEBUG, ("\n>Error %s:%d at %s, line %d", GET_ERR_STRING(tmp_err_code), tmp_err_code, __FILE__, __LINE__)); \
cblock;\
return tmp_err_code; } } while(0)
#endif /* ERRORHANDLE_H_ */
