Error

NAME: Error - SET Error message data structures and routines

SYNOPSIS

#include <set_msg.h>

/* use errorTBS for both the unsigned and signed Error message */
typedef struct Error_ {
    asn1set__MessageWrapper      messageWrapper;
    asn1set__ErrorTBS            errorTBS;

    /* only for signed case */
    cert_identity                eeSignatureCID;

#define                          Error__eeSignatureCID      0
    UCHAR                        _present[1];
} *Error;

Error safe_cast_Error(msg)
    set_msg            msg;             /* IN */

DESCRIPTION: Error contains the data from a SET Error message in native C form. See the asn_types.h and asn1set.h header files for the declarations of the various types. See SET documentation for a description of each field.
Error message objects of type set_msg can be cast to type Error using the safe_cast_Error() routine.

FIELDS

Before calling make_set_msg(), applications must insert the following state into the cache_ctx:

 *      STATE_ERROR_RRPID

STATE_ERROR_RRPID must be set to the RRPID of the message that generated the error.

A call to make_set_msg() results in the protocol layer filling in the following fields:

 *    messageWrapper.messageHeader.version
 *    messageWrapper.messageHeader.date
 *    messageWrapper.messageHeader.messageIDs (optional)
 *    messageWrapper.messageHeader.rrPID (optional)
 *    messageWrapper.message._choice
 *    errorTBS.errorNonce

It is unwise for users to change the contents of the fields filled in by the protocol layer.

After calling make_set_msg(), software must fill in at least the following required field:

 *    errorTBS.errorCode
 *    errorTBS.errorMsg

CACHING

      STATE_ERROR_RRPID              get
      STATE_LOCALID_C                get
      STATE_LOCALID_M                get
      STATE_TRANSIDS                 get
      STATE_XID                      get

RETURN VALUES: On success, safe_cast_Error() returns a pointer to an Error data structure. Objects of type set_msg that were not created with message type asn1set__Message__error will cause safe_cast_Error() to fail. On failure, safe_cast_Error() returns a 0 pointer.

SEE ALSO: set_msg

NOTES: There is a difference between non-required and optional. Non-required fields may be omitted according to the SET protocol. Optional fields may be omitted according to ASN.1 encoding rules. In some messages, a field may be optional according to ASN.1, but required by the SET protocol. In these cases, it is incumbent on the application to fill in these fields.
Optional fields that are filled in require an application of the SET_PRESENT() macro. See documentation on ASN.1/DER runtime types for additional information.

EXAMPLE

A more complete, explicated example is provided in the Implementor's Guide.

    /* 'msg' is the message that generated the error */

    status = create_set_msg(&error, app_ctx, heap);
    assert(status == NO_ERROR);

    status = CACHE_put(msg_cache, STATE_ERROR_RRPID, &msg->messageWrapper.messageHeader.rrPID);
    assert(status == NO_ERROR);

    msg_type = asn1set__Message__error;
    status = make_set_msg(error, app_ctx, msg_cache, msg_type);
    assert(status == NO_ERROR);

    safe_cast_Error(error)->errorTBS.errorCode = SOME_ERROR_CODE;

    status = send_set_msg(error, app_ctx, msg_cache, outstream);
    assert(status == NO_ERROR);

    status = delete_set_msg(&error);
    assert(status == NO_ERROR);

    status = delete_set_msg(&msg);
    assert(status == NO_ERROR);

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.