An XML pull-parser works by allowing a user to "pull" selected events from an XML stream as it is parsed. This differs from the SAX model which is sometimes referred to as a "push" parser because event callbacks are executed (pushed) as the stream is parsed. The pull model offers significant advantages for a data binding type application because it is easier to maintain state between operations. This results in less required code to do the decoding which in turn leads to improved performance. It is also conceptually easier to understand because the function call model more closely approximates the model used for encoding.
Generated C pull-parser decode functions are written to a .c file with a name of the following format:
<xsdFileName>Dec.c or
<wsdlFileName>WSDLDec.c
where <xsdFileName> is the base name of the XSD file being parsed; and <wsdlFileName> is the base name of the WSDL file being parsed. For example, if code is being generated for file x.xsd, decode functions for each type and global element defined in the specification will be written to xDec.c . If the file being processed is a WSDL file, the suffix would be WSDLDec.c (for example, x.wsdl would produce xWSDLDec.c ).
The format of the name of each generated XML decode function is as follows:
[<ns>]XmlDT_<typeName>
where <typeName>is the name of the
C type for which the function is being generated and
<ns>is an optional namespace
setting that can be used to disambiguate element names from
multiple sources (note: this should not be confused with XML
namespaces which are different).
The calling sequence for each decode function is as follows:
stat = <decodeFunc> (OSCTXT* pctxt, <typeName>* pvalue);
In this definition, <decodeFunc> denotes the decode function name defined above.
The pctxtargument is used to hold a context
pointer to keep track of decode 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 p valueargument is a pointer to a variable of
the decode function type to receive the decoded data.
The function result variable statreturns the
status of the decode operation. Status code 0 (zero) indicates
the function was successful. A negative value indicates decoding
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.
A key difference between SAX-based functions and pull-parser based is that a decode function is not generated for all types in the SAX case. That is because of the overhead invlolved in setting up the SAX parser to decode simple types. Most simple types are decoded inline as part of more complex types. This is an example of a case where the pull-parser model more closely follows the encode model.
The generated C function format for global elements is identical to that of the SAX case:
[<ns>]XmlD_<elemName>
The calling arguments are also the same:
stat = <decodeFunc> (OSCTXT* pctxt, <typeName>* pvalue);
This allows pull-parser or SAX-based decoding to be interchanged with minimal code changes.
The procedure for calling this type of decode function is described below in the section entitled "Procedure for Calling C Decode Functions". The procedure for calling pull-parser based functions is the same as was the case for SAX-based functions.
The generated C factory decode function format is similar to that of the global element decode function:
[<ns>]XmlD_Project_<prjName>
The calling arguments are :
stat = <decodeFunc> (OSCTXT* pctxt, <prjName>_message*
pvalue);
The procedure for calling this factory decode function is described below in the section entitled "Procedure for Calling C Decode Functions".
Web service description language (WSDL) documents may contain operation definitions in portType and binding sections. A decode function is generated for each operation input and output in the following format:
[<ns>]XmlD_<operName>_Input
[<ns>]XmlD_<operName>_Output
where <operName>is the name of the
WSDL operation name and <ns>is an
optional namespace setting that can be used to disambiguate
element names from multiple sources (note: this should not be
confused with XML namespaces which are different). Note: if there
are duplicate operation names in one WSDL source file, the first
operation uses only the operation name, and other operation(s)
with the duplicate names use a fully qualified name which is
consist of operation name, input name and output name.
When Request-response primitives are used, the calling sequence for a WSDL input operation decode function is as follows:
status = <decodeFunc> (OSCTXT* pctxt, <name>* pvalue);
The calling sequence for a WSDL output operation decode function is as follows:
status = <decodeFunc> (OSCTXT* pctxt, <name>* pvalue,
<fault name>* pfault);
In this definition, <decodeFunc> denotes the
decode function name defined above. The
pctxtargument is used to hold a context pointer to
keep track of decode 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 pvalue argument is a pointer to a variable of the decode function type (either operation input or output) to receive the decoded input/output data. The pfault argument is a pointer to a variable of the operation fault type to receive the decoded SOAP Fault data.
The WSDL output operation decode function is used to decode a response from a Web Service server. If the response is a SOAP Fault message, the returned value status is RTERR_SOAPFAULT, and the decoded data is saved in pfault . If the response is a normal SOAP message, the returned status value is zero and the decoded data is saved in pvalue . A negative return value indicates decoding 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.