Procedure for Calling C Encode Functions

---

This section describes the step-by-step procedure for calling C XER encode functions. This procedure is similar to that for the other encoding methods except that some of the functions used are specific to XER.

Before an XER encode function can be called, the user must first initialize an encoding context block structure. The context block is initialized by calling the rtInitContext function. This routine allows a message buffer to be specified to receive the encoded message. Specification of a message buffer is optional. If not specified, the encoder will allocate memory automatically for the encoded message.

An encode function can then be called to encode the message. If the return status indicates success (ASN_OK), then the message will have been encoded in the given buffer. XER encoding starts from the beginning of the buffer and proceeds from low memory to high memory until the message is complete. This differs from BER where encoding was done from back-to-front. Therefore, the buffer start address is where the encoded XER message begins. The length of the encoded message can be obtained by calling the xerGetMsgLen run-time function. If dynamic encoding was specified (i.e., a buffer start address and length were not given), the run-time routine xerGetMsgPtr can be used to obtain the start address of the message. This routine will also return the length of the encoded message.

A program fragment that could be used to encode an employee record is as follows:

    #include employee.h         /* include file generated by ASN1C */
 

 
    main ()
 
    {
 
        ASN1OCTET msgbuf[1024];
 
        int       msglen, stat;
 
        ASN1CTXT  ctxt;
 
        ASN1BOOL  cxer = FALSE;  /* canonical XER flag */
 
        ASN1BOOL  aligned = TRUE;
 
        Employee  employee;	/* typedef generated by ASN1C */
 

 
        /* Initialize context and set encode buffer pointer */
 
        if (rtInitContext (&ctxt) != ASN_OK) return -1;
 

 
        xerSetEncBufPtr (&ctxt, msgbuf, sizeof(msgbuf), cxer);
 

 
        /* Populate variable with data to be encoded */
 
        employee.name.givenName = "John";
 
        ...
 

 
        /* Encode data */
 
        stat = asn1XE_Employee (&ctxt, &employee, 0, 0);
 

 
        if (stat) == ASN_OK) {
 
          msglen = xerGetMsgLen (&ctxt);
 
          ...
 
        }
 
        else
 
          error processing...
 
    }
 

 
    rtFreeContext (&ctxt);  /* release the context pointer */
 

 

After encoding is complete, msgbuf contains the XML textual representation of the data. By default, a UTF-8 encoding is used. For the ASCII character set, this results in a buffer containing normal textual data. Therefore, the contents of the buffer are represented as a normal text string and can be displayed using the C printf run-time function or any other function capable of displaying text.