PCertReq

NAME: PCertReq - SET PCertReq message data structures and routines

SYNOPSIS

#include <set_msg.h>

typedef struct PCertReq_ {
    asn1set__MessageWrapper    messageWrapper;
    asn1set__PCertReqData      pCertReqData;
    cert_identity              merchantSignatureCID;
} *PCertReq;

PCertReq safe_cast_PCertReq(msg)
    set_msg            msg;             /* IN */

DESCRIPTION: PCertReq contains the data from a SET PCertReq message in native C form. See the asn_types.h and asn1set.h header files for the declarations of the various types. See the SET specification for a description of individual fields.
PCertReq message objects of type set_msg can be cast to type PCertReq using the safe_cast_PCertReq() routine.

FIELDS

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
 *    messageWrapper.messageHeader.rrPID
 *    messageWrapper.messageHeader.swIdent
 *    messageWrapper.message._choice
 *    pCertReqData.pCertRRTags.rrpid
 *    pCertReqData.pCertRRTags.currentDate
 *    pCertReqData.mThumbs

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

After calling make_set_msg(), merchant software must fill in the following required fields:

 *    pCertReqData.pCertRRTags.merTermIDs.merchantID
 *    pCertReqData.brandAndBINSeq
 *    merchantSignatureCID

Non-required fields may be left empty at the discretion of the merchant application.

CACHING

Payment Gateway

      STATE_PCERTREQ_RRPID           put
      STATE_RRTAGS                   put
      STATE_THUMBS                   put

Merchant

      STATE_PCERTREQ_RRPID           put

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

SEE ALSO: set_msg, PCertRes, CapReq, CapRes, PInitReq, PInitRes, PReq, PRes

NOTES

Since the RRPID is unknown before calling make_set_msg(), no cache can be opened and hence 0 is passed as the cache parameter to make_set_msg().

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 still 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.


    status = create_set_msg(&request, app_ctx, heap);
    ASSERT(status == NO_ERROR);

    /* since the RRPID is unknown at this point, no cache can
     * be opened and hence 0 is passed as the cache parameter
     * to make_set_msg() */

    msg_type = asn1set__Message__pCertReq;
    status = make_set_msg(request, app_ctx, 0, msg_type);
    ASSERT(status == NO_ERROR);

    pCertReq = safe_cast_PCertReq(request);
    assert(pCertReq != 0);
   
    /* agentNum is an optional INTEGER */         
    pCertReq->pCertReqData.pCertRRTags.merTermIDs.agentNum = N_AGENT;
    SET_PRESENT(pCertReq->pCertReqData.pCertRRTags.merTermIDs,
                asn1set__MerTermIDs__agentNum);
                
    /* ... */

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