errors: XML Security Library Reference Manual

## errors errors — Error reporting and logging functions. |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | (*xmlSecErrorsCallback) ()
void | xmlSecErrorsInit ()
void | xmlSecErrorsShutdown ()
void | xmlSecErrorsSetCallback ()
void | xmlSecErrorsDefaultCallback ()
void | xmlSecErrorsDefaultCallbackEnableOutput ()
int | xmlSecErrorsGetCode ()
const char * | xmlSecErrorsGetMsg ()
#define | xmlSecErrorsSafeString()
void | xmlSecError ()
#define | xmlSecAssert()
#define | xmlSecAssert2()

## Types and Values

#define | XMLSEC_ERRORS_R_XMLSEC_FAILED
#define | XMLSEC_ERRORS_R_MALLOC_FAILED
#define | XMLSEC_ERRORS_R_STRDUP_FAILED
#define | XMLSEC_ERRORS_R_CRYPTO_FAILED
#define | XMLSEC_ERRORS_R_XML_FAILED
#define | XMLSEC_ERRORS_R_XSLT_FAILED
#define | XMLSEC_ERRORS_R_IO_FAILED
#define | XMLSEC_ERRORS_R_DISABLED
#define | XMLSEC_ERRORS_R_NOT_IMPLEMENTED
#define | XMLSEC_ERRORS_R_INVALID_CONFIG
#define | XMLSEC_ERRORS_R_INVALID_SIZE
#define | XMLSEC_ERRORS_R_INVALID_DATA
#define | XMLSEC_ERRORS_R_INVALID_RESULT
#define | XMLSEC_ERRORS_R_INVALID_TYPE
#define | XMLSEC_ERRORS_R_INVALID_OPERATION
#define | XMLSEC_ERRORS_R_INVALID_STATUS
#define | XMLSEC_ERRORS_R_INVALID_FORMAT
#define | XMLSEC_ERRORS_R_DATA_NOT_MATCH
#define | XMLSEC_ERRORS_R_INVALID_VERSION
#define | XMLSEC_ERRORS_R_INVALID_NODE
#define | XMLSEC_ERRORS_R_INVALID_NODE_CONTENT
#define | XMLSEC_ERRORS_R_INVALID_NODE_ATTRIBUTE
#define | XMLSEC_ERRORS_R_MISSING_NODE_ATTRIBUTE
#define | XMLSEC_ERRORS_R_NODE_ALREADY_PRESENT
#define | XMLSEC_ERRORS_R_UNEXPECTED_NODE
#define | XMLSEC_ERRORS_R_NODE_NOT_FOUND
#define | XMLSEC_ERRORS_R_INVALID_TRANSFORM
#define | XMLSEC_ERRORS_R_INVALID_TRANSFORM_KEY
#define | XMLSEC_ERRORS_R_INVALID_URI_TYPE
#define | XMLSEC_ERRORS_R_TRANSFORM_SAME_DOCUMENT_REQUIRED
#define | XMLSEC_ERRORS_R_TRANSFORM_DISABLED
#define | XMLSEC_ERRORS_R_INVALID_KEY_DATA
#define | XMLSEC_ERRORS_R_KEY_DATA_NOT_FOUND
#define | XMLSEC_ERRORS_R_KEY_DATA_ALREADY_EXIST
#define | XMLSEC_ERRORS_R_INVALID_KEY_DATA_SIZE
#define | XMLSEC_ERRORS_R_KEY_NOT_FOUND
#define | XMLSEC_ERRORS_R_KEYDATA_DISABLED
#define | XMLSEC_ERRORS_R_MAX_RETRIEVALS_LEVEL
#define | XMLSEC_ERRORS_R_MAX_RETRIEVAL_TYPE_MISMATCH
#define | XMLSEC_ERRORS_R_MAX_ENCKEY_LEVEL
#define | XMLSEC_ERRORS_R_CERT_VERIFY_FAILED
#define | XMLSEC_ERRORS_R_CERT_NOT_FOUND
#define | XMLSEC_ERRORS_R_CERT_REVOKED
#define | XMLSEC_ERRORS_R_CERT_ISSUER_FAILED
#define | XMLSEC_ERRORS_R_CERT_NOT_YET_VALID
#define | XMLSEC_ERRORS_R_CERT_HAS_EXPIRED
#define | XMLSEC_ERRORS_R_DSIG_NO_REFERENCES
#define | XMLSEC_ERRORS_R_DSIG_INVALID_REFERENCE
#define | XMLSEC_ERRORS_R_ASSERTION
#define | XMLSEC_ERROR_R_CAST_IMPOSSIBLE
#define | XMLSEC_ERRORS_MAX_NUMBER
#define | XMLSEC_ERRORS_HERE
#define | XMLSEC_ERRORS_NO_MESSAGE

## Description

## Functions

### xmlSecErrorsCallback ()

    void
    (*xmlSecErrorsCallback) (const char *file,
                             int line,
                             const char *func,
                             const char *errorObject,
                             const char *errorSubject,
                             int reason,
                             const char *msg);

The errors reporting callback function.

#### Parameters

file | the error location file name (__FILE__ macro). |
line | the error location line number (__LINE__ macro). |
func | the error location function name (__func__ macro). |
errorObject | the error specific error object |
errorSubject | the error specific error subject. |
reason | the error code. |
msg | the additional error message. |

### xmlSecErrorsInit ()

    void
    xmlSecErrorsInit (void);

Initializes the errors reporting. It is called from xmlSecInit function. and applications must not call this function directly.

### xmlSecErrorsShutdown ()

    void
    xmlSecErrorsShutdown (void);

Cleanups the errors reporting. It is called from xmlSecShutdown function. and applications must not call this function directly.

### xmlSecErrorsSetCallback ()

    void
    xmlSecErrorsSetCallback (xmlSecErrorsCallback callback);

Sets the errors callback function to `callback` that will be called every time an error occurs.

#### Parameters

callback | the new errors callback function. |

### xmlSecErrorsDefaultCallback ()

    void
    xmlSecErrorsDefaultCallback (const char *file,
                                 int line,
                                 const char *func,
                                 const char *errorObject,
                                 const char *errorSubject,
                                 int reason,
                                 const char *msg);

The default error reporting callback that utilizes LibXML error reporting xmlGenericError function.

#### Parameters

file | the error location file name (__FILE__ macro). |
line | the error location line number (__LINE__ macro). |
func | the error location function name (__FUNCTION__ macro). |
errorObject | the error specific error object |
errorSubject | the error specific error subject. |
reason | the error code. |
msg | the additional error message. |

### xmlSecErrorsDefaultCallbackEnableOutput ()

    void
    xmlSecErrorsDefaultCallbackEnableOutput
                                   (int enabled);

Enables or disables calling LibXML2 callback from the default errors callback.

#### Parameters

enabled | the flag. |

### xmlSecErrorsGetCode ()

    int
    xmlSecErrorsGetCode (xmlSecSize pos);

Gets the known error code at position `pos` .

#### Parameters

pos | the error position. |

#### Returns

the known error code or 0 if `pos` is greater than total number of known error codes.

### xmlSecErrorsGetMsg ()

    const char *
    xmlSecErrorsGetMsg (xmlSecSize pos);

Gets the known error message at position `pos` .

#### Parameters

pos | the error position. |

#### Returns

the known error message or NULL if `pos` is greater than total number of known error codes.

### xmlSecErrorsSafeString()

    #define             xmlSecErrorsSafeString(str)

Macro. Returns `str` if it is not NULL or pointer to "NULL" otherwise.

#### Parameters

str | the string. |

### xmlSecError ()

    void
    xmlSecError (const char *file,
                 int line,
                 const char *func,
                 const char *errorObject,
                 const char *errorSubject,
                 int reason,
                 const char *msg,
                 ...);

Reports an error to the default (xmlSecErrorsDefaultCallback) or application specific callback installed using xmlSecErrorsSetCallback function.

#### Parameters

file | the error location filename (__FILE__). |
line | the error location line number (__LINE__). |
func | the error location function (__FUNCTION__). |
errorObject | the error specific error object (e.g. transform, key data, etc). |
errorSubject | the error specific error subject (e.g. failed function name). |
reason | the error code. |
msg | the error message in printf format. |
... | the parameters for the `msg` . |

### xmlSecAssert()

    #define             xmlSecAssert( p )

Macro. Verifies that `p` is true and calls `return()` otherwise.

#### Parameters

p | the expression. |

### xmlSecAssert2()

    #define             xmlSecAssert2( p, ret )

Macro. Verifies that `p` is true and calls return(`ret` ) otherwise.

#### Parameters

p | the expression. |
ret | the return value. |

## Types and Values

### XMLSEC_ERRORS_R_XMLSEC_FAILED

    #define XMLSEC_ERRORS_R_XMLSEC_FAILED                   1

An XMLSec function failed.

### XMLSEC_ERRORS_R_MALLOC_FAILED

    #define XMLSEC_ERRORS_R_MALLOC_FAILED                   2

Failed to allocate memory error.

### XMLSEC_ERRORS_R_STRDUP_FAILED

    #define XMLSEC_ERRORS_R_STRDUP_FAILED                   3

Failed to duplicate string error.

### XMLSEC_ERRORS_R_CRYPTO_FAILED

    #define XMLSEC_ERRORS_R_CRYPTO_FAILED                   4

Crypto (e.g. OpenSSL) function failed.

### XMLSEC_ERRORS_R_XML_FAILED

    #define XMLSEC_ERRORS_R_XML_FAILED                      5

LibXML function failed.

### XMLSEC_ERRORS_R_XSLT_FAILED

    #define XMLSEC_ERRORS_R_XSLT_FAILED                     6

LibXSLT function failed.

### XMLSEC_ERRORS_R_IO_FAILED

    #define XMLSEC_ERRORS_R_IO_FAILED                       7

IO operation failed.

### XMLSEC_ERRORS_R_DISABLED

    #define XMLSEC_ERRORS_R_DISABLED                        8

The feature is disabled during compilation. Check './configure --help' for details on how to enable it.

### XMLSEC_ERRORS_R_NOT_IMPLEMENTED

    #define XMLSEC_ERRORS_R_NOT_IMPLEMENTED                 9

Feature is not implemented.

### XMLSEC_ERRORS_R_INVALID_CONFIG

    #define XMLSEC_ERRORS_R_INVALID_CONFIG                  10

The configuration is invalid.

### XMLSEC_ERRORS_R_INVALID_SIZE

    #define XMLSEC_ERRORS_R_INVALID_SIZE                    11

Invalid size.

### XMLSEC_ERRORS_R_INVALID_DATA

    #define XMLSEC_ERRORS_R_INVALID_DATA                    12

Invalid data.

### XMLSEC_ERRORS_R_INVALID_RESULT

    #define XMLSEC_ERRORS_R_INVALID_RESULT                  13

Invalid result.

### XMLSEC_ERRORS_R_INVALID_TYPE

    #define XMLSEC_ERRORS_R_INVALID_TYPE                    14

Invalid type.

### XMLSEC_ERRORS_R_INVALID_OPERATION

    #define XMLSEC_ERRORS_R_INVALID_OPERATION               15

Invalid operation.

### XMLSEC_ERRORS_R_INVALID_STATUS

    #define XMLSEC_ERRORS_R_INVALID_STATUS                  16

Invalid status.

### XMLSEC_ERRORS_R_INVALID_FORMAT

    #define XMLSEC_ERRORS_R_INVALID_FORMAT                  17

Invalid format.

### XMLSEC_ERRORS_R_DATA_NOT_MATCH

    #define XMLSEC_ERRORS_R_DATA_NOT_MATCH                  18

The data do not match our expectation.

### XMLSEC_ERRORS_R_INVALID_VERSION

    #define XMLSEC_ERRORS_R_INVALID_VERSION                 19

Version mismatch.

### XMLSEC_ERRORS_R_INVALID_NODE

    #define XMLSEC_ERRORS_R_INVALID_NODE                    21

Invalid node.

### XMLSEC_ERRORS_R_INVALID_NODE_CONTENT

    #define XMLSEC_ERRORS_R_INVALID_NODE_CONTENT            22

Invalid node content.

### XMLSEC_ERRORS_R_INVALID_NODE_ATTRIBUTE

    #define XMLSEC_ERRORS_R_INVALID_NODE_ATTRIBUTE          23

Invalid node attribute.

### XMLSEC_ERRORS_R_MISSING_NODE_ATTRIBUTE

    #define XMLSEC_ERRORS_R_MISSING_NODE_ATTRIBUTE          25

Missing node attribute.

### XMLSEC_ERRORS_R_NODE_ALREADY_PRESENT

    #define XMLSEC_ERRORS_R_NODE_ALREADY_PRESENT            26

Node already present,

### XMLSEC_ERRORS_R_UNEXPECTED_NODE

    #define XMLSEC_ERRORS_R_UNEXPECTED_NODE                 27

Unexpected node.

### XMLSEC_ERRORS_R_NODE_NOT_FOUND

    #define XMLSEC_ERRORS_R_NODE_NOT_FOUND                  28

Node not found.

### XMLSEC_ERRORS_R_INVALID_TRANSFORM

    #define XMLSEC_ERRORS_R_INVALID_TRANSFORM               31

This transform is invalid.

### XMLSEC_ERRORS_R_INVALID_TRANSFORM_KEY

    #define XMLSEC_ERRORS_R_INVALID_TRANSFORM_KEY           32

Key is invalid for this transform.

### XMLSEC_ERRORS_R_INVALID_URI_TYPE

    #define XMLSEC_ERRORS_R_INVALID_URI_TYPE                33

Invalid URI type.

### XMLSEC_ERRORS_R_TRANSFORM_SAME_DOCUMENT_REQUIRED

    #define XMLSEC_ERRORS_R_TRANSFORM_SAME_DOCUMENT_REQUIRED        34

The transform requires the input document to be the same as context.

### XMLSEC_ERRORS_R_TRANSFORM_DISABLED

    #define XMLSEC_ERRORS_R_TRANSFORM_DISABLED              35

The transform is disabled.

### XMLSEC_ERRORS_R_INVALID_KEY_DATA

    #define XMLSEC_ERRORS_R_INVALID_KEY_DATA                41

Key data is invalid.

### XMLSEC_ERRORS_R_KEY_DATA_NOT_FOUND

    #define XMLSEC_ERRORS_R_KEY_DATA_NOT_FOUND              42

Data is not found.

### XMLSEC_ERRORS_R_KEY_DATA_ALREADY_EXIST

    #define XMLSEC_ERRORS_R_KEY_DATA_ALREADY_EXIST          43

The key data is already exist.

### XMLSEC_ERRORS_R_INVALID_KEY_DATA_SIZE

    #define XMLSEC_ERRORS_R_INVALID_KEY_DATA_SIZE           44

Invalid key size.

### XMLSEC_ERRORS_R_KEY_NOT_FOUND

    #define XMLSEC_ERRORS_R_KEY_NOT_FOUND                   45

Key not found.

### XMLSEC_ERRORS_R_KEYDATA_DISABLED

    #define XMLSEC_ERRORS_R_KEYDATA_DISABLED                46

The key data type disabled.

### XMLSEC_ERRORS_R_MAX_RETRIEVALS_LEVEL

    #define XMLSEC_ERRORS_R_MAX_RETRIEVALS_LEVEL            51

Max allowed retrievals level reached.

### XMLSEC_ERRORS_R_MAX_RETRIEVAL_TYPE_MISMATCH

    #define XMLSEC_ERRORS_R_MAX_RETRIEVAL_TYPE_MISMATCH     52

The retrieved key data type does not match the one specified in the <dsig:RetrievalMethod/> node.

### XMLSEC_ERRORS_R_MAX_ENCKEY_LEVEL

    #define XMLSEC_ERRORS_R_MAX_ENCKEY_LEVEL                61

Max EncryptedKey level reached.

### XMLSEC_ERRORS_R_CERT_VERIFY_FAILED

    #define XMLSEC_ERRORS_R_CERT_VERIFY_FAILED              71

Certificate verification failed.

### XMLSEC_ERRORS_R_CERT_NOT_FOUND

    #define XMLSEC_ERRORS_R_CERT_NOT_FOUND                  72

Requested certificate is not found.

### XMLSEC_ERRORS_R_CERT_REVOKED

    #define XMLSEC_ERRORS_R_CERT_REVOKED                    73

The certificate is revoked.

### XMLSEC_ERRORS_R_CERT_ISSUER_FAILED

    #define XMLSEC_ERRORS_R_CERT_ISSUER_FAILED              74

Failed to get certificate issuer.

### XMLSEC_ERRORS_R_CERT_NOT_YET_VALID

    #define XMLSEC_ERRORS_R_CERT_NOT_YET_VALID              75

"Not valid before" verification failed.

### XMLSEC_ERRORS_R_CERT_HAS_EXPIRED

    #define XMLSEC_ERRORS_R_CERT_HAS_EXPIRED                76

"Not valid after" verification failed.

### XMLSEC_ERRORS_R_DSIG_NO_REFERENCES

    #define XMLSEC_ERRORS_R_DSIG_NO_REFERENCES              81

The <dsig:Reference/> nodes not found.

### XMLSEC_ERRORS_R_DSIG_INVALID_REFERENCE

    #define XMLSEC_ERRORS_R_DSIG_INVALID_REFERENCE          82

The <dsig:Reference/> validation failed.

### XMLSEC_ERRORS_R_ASSERTION

    #define XMLSEC_ERRORS_R_ASSERTION                       100

Invalid assertion.

### XMLSEC_ERROR_R_CAST_IMPOSSIBLE

    #define XMLSEC_ERROR_R_CAST_IMPOSSIBLE                  101

### XMLSEC_ERRORS_MAX_NUMBER

    #define XMLSEC_ERRORS_MAX_NUMBER                        256

The maximum xmlsec errors number.

### XMLSEC_ERRORS_HERE

    #define XMLSEC_ERRORS_HERE                      __FILE__,__LINE__,__XMLSEC_FUNCTION__

The macro that specifies the location (file, line and function) for the `xmlSecError()` function.

### XMLSEC_ERRORS_NO_MESSAGE

    #define XMLSEC_ERRORS_NO_MESSAGE                " "

Empty error message " ".