Encode/Decode Function Prototypes

If BER or DER encoding is specified, a BER encode and decode function prototype is generated for each production (DER uses the same form – there are only minor differences between the two types of generated functions). These prototypes are of the following general form:

   int asn1E_<ProdName> (OSCTXT* pctxt,
      <ProdName>* pvalue, ASN1TagType tagging);

   int asn1D_<ProdName> (OSCTXT* pctxt,
      <ProdName>* pvalue, ASN1TagType tagging, int length);

The prototype with the asn1E_ prefix is for encoding and the one with asn1D_ is for decoding. The first parameter is a context variable used for reentrancy. This allows the encoder/decoder to keep track of what it is doing between function invocations.

The second parameter is for passing the actual data variable to be encoded or decoded. This is a pointer to a variable of the generated type.

The third parameter specifies whether implicit or explicit tagging should be used. In practically all cases, users of the generated function should set this parameter to ASN1EXPL (explicit). This tells the encoder to include an explicit tag around the encoded result. The only time this would not be used is when the encoder or decoder is making internal calls to handle implicit tagging of elements.

The final parameter (decode case only) is length. This is ignored when tagging is set to ASN1EXPL (explicit), so users can ignore it for the most part and set it to zero. In the implicit case, this specifies the number of octets to be extracted from the byte stream. This is necessary because implicit indicates no tag/length pair precedes the data; therefore it is up to the user to indicate how many bytes of data are present.

If PER encoding is specified, the format of the generated prototypes is different. The PER prototypes are of the following general form:

   int asn1PE_<ProdName> (OSCTXT* pctxt, <ProdName>[*] value);

   int asn1PD_<ProdName> (OSCTXT* pctxt, <ProdName>* pvalue);

In these prototypes, the prefixes are different (a ‘P’ character is added to indicate they are PER encoders/decoders), and the tagging argument variables are omitted. In the encode case, the value of the production to be encoded may be passed by value if it is a simple type (for example, BOOLEAN or INTEGER). Structured values will still be passed using a pointer argument.

If XER encoding is specified, function prototypes are generated with the following format:

   int asn1XE_<ProdName> (OSCTXT* pctxt, <ProdName>[*] value,
                          const char* elemName,
                          const char* attributes);
   
   int asn1XD_<ProdName> (OSCTXT* pctxt, <ProdName>* pvalue);

The encode function signature includes arguments for the context and value as in the other cases. It also has an element name argument (elemName) that contains the name of the element to be encoded and an attributes argument (attributes) that can be used to encode an attributes string. The decode function is generated for PDU-types only - decoding of internally referenced types is accomplished through generated SAX handler callback functions which are invoked by an XML parser.

If XML functions are generated using the -xml switch, the function prototypes are as follows:

   int XmlEnc_<ProdName> (OSCTXT* pctxt, <ProdName> value,
      const OSUTF8CHAR* elemName, const OSUTF8CHAR* nsPrefix);

   int XmlDec_<ProdName> (OSCTXT* pctxt, <ProdName>* pvalue);

In this case, the encode function contains an argument for XML element name (elemName) and also namespace prefix (nsPrefix).