The format of the name of each generated XML encode function is as follows:
[<namespace>]XmlEnc_[<prefix>]<prodName>
where <namespace>
is an optional C namespace prefix,
<prodName>
is the name of the ASN.1 production for which the function
is being generated and <prefix>
is an optional prefix that can be set
via a configuration file setting. The configuration setting used to set the prefix is
the <typePrefix> element. This element specifies a prefix that will be applied to all
generated typedef names and function names for the production. <namespace> is set
using the ASN1C -namespace command-line argument.
Note that this should not be confused with the notion of an XML namespace.
The calling sequence for each encode function is as follows:
status = <ns>XmlEnc_<name> (OSCTXT* pctxt, <name>[*] value, const OSUTF8CHAR* elemName, const OSUTF8CHAR* nsPrefix);
In this definition, <ns> is short for <namespace> and <name> denotes the prefixed production name defined above.
The pctxt
argument is used to hold a context pointer to keep track of
encode parameters. This is a basic "handle" variable that is used to make the function
reentrant so it can be used in an asynchronous or threaded application. The user is
required to supply a pointer to a variable of this type declared somewhere in his or her
program.
The value
argument contains the value to be encoded or holds a pointer
to the value to be encoded. This variable is of the type generated from the ASN.1
production. The object is passed by value if it is a primitive ASN.1 data type such as
BOOLEAN, INTEGER, ENUMERATED, etc.. It is passed using a pointer reference if it is a
structured ASN.1 type value (in this case, the name will be pvalue instead of value).
Check the generated function prototype in the header file to determine how this argument
is to be passed for a given function.
The elemName and nsPrefix arguments are used to pass the XML element name and namespace prefix respectively. The two arguments are combined to form a qualified name (QName) of the form <nsPrefix:elemName>. If elemName is null or empty, then no element tag is added to the encoded content. If nsPrefix is null or empty, the element name is applied as a local name only without a prefix.
The function result variable stat
returns the status of the encode
operation. Status code zero indicates the function was successful. A negative value
indicates encoding failed. Return status values are defined in the rtxErrCodes.h include file. The error text and a stack trace
can be displayed using the rtxErrPrint
function.
In addition to the XML encode function generated for types, a different type of encode function is generated for Protocol Data Units (PDU’s). These are types in an ASN.1 specification that are not referenced by any other types. In an XML schema specification, these are global elements that are not reference within any other types or global elements.
The format of the a PDU encode function is the same name format as above with the suffix _PDU. This function does not contain the elemName and nsPrefix arguments - these are built into the function as defined in the schema. For this reason, calling PDU functions is usually more convenient than calling the equivalent function for the referenced type.