dc_Epx.h File Reference

Streaming XML processing API using the pull-parsing approach. More...

#include <stdlib.h>
#include "dc/dc_XMLTypes.h"

Defines

#define EPX_OK   0
 No error.
#define EPX_ERR_UNKNOWN_OPTION   -1
 The option is not recognized by the implementation.
#define EPX_ERR_NOT_SUPPORTED   -2
 Call not supported by the parser or for the current event.
#define EPX_ERR_INVALID_REPRESENTATION   -3
 Typed API could not convert XML to native data.
#define EPX_ERR_OUT_OF_RANGE   -4
 Typed API could convert XML to native data but the value is out of the target type range.
#define EPX_ERR_IMPLEMENTATION   -5
 Implementation-specific error to retrieve using a dedicated API.
#define EPX_ERR_INVALID_PARAMETER   -6
 A parameter passed to the API is incorrect.
#define EPX_OPT_COALESCING   0x01
 Returns all consecutive char data ignoring comments in one event (PI are excluded for SOAP 1.2).
#define EPX_OPT_IGNORE_COMMENTS   0x02
 Parsing will not produce COMMENT events.
#define EPX_OPT_UTF8_OUTPUT   0x04
 output are in multi-byte UTF-8, else UCS-4 cast to char (i.e.
#define EPX_OPT_PARSER_STREAMING   0x08
 Streaming on data buffers is supported.
#define EPX_OPT_GENERATE_PREFIX_DEFINITIONS   0x10
 Prefix definition will be generated instead of ordinary attribute events.
#define EPX_OPT_FRAGMENT_PARSING   0x20
 Fragment feature supported.

Enumerations

enum  epx_event {
  EPX_EVT_ERROR = -1, EPX_EVT_IDLE = 0, EPX_EVT_START_DOCUMENT = 1, EPX_EVT_END_DOCUMENT = 2,
  EPX_EVT_START_ELEMENT = 3, EPX_EVT_PREFIX_DEFINITION = 4, EPX_EVT_ATTRIBUTE = 5, EPX_EVT_END_ELEMENT = 6,
  EPX_EVT_CHARACTERS = 7, EPX_EVT_COMMENT = 8, EPX_EVT_START_CDATA = 9, EPX_EVT_END_CDATA = 10,
  EPX_EVT_END_FRAGMENT = 11
}
 XML events definition which is fundamental for API usage. More...

Functions

Parsing API
DC_RT_FMAC1 int epx_get_parser_options (void *implementation)
 Gets the parser default options settings.
DC_RT_FMAC1 int epx_is_parser_option_settable (void *implementation, int option)
 Test if a parser option can be enabled of disabled.
DC_RT_FMAC1 void * epx_new_parser (void *implementation, void *impl_data)
 Creates a new parser from a given EPX implementation.
DC_RT_FMAC1 int epx_start_parsing (void *context, void *source, int options)
 Start the XML parsing for the implementation opaque id.
DC_RT_FMAC1 int epx_set_parsing_options (void *context, int options)
 Set parsing options while parsing is running.
DC_RT_FMAC1 int epx_get_parsing_options (void *context)
 Get the current parsing options.
DC_RT_FMAC1 int epx_start_fragment_parsing (void *context, epx_boolean_t gen_all_pfx_events)
 Start the parsing of an XML fragment when an XML parsing is running, meaning that the parsing will stop after the child elements have been completely parsed.
DC_RT_FMAC1 int epx_reset_fragment_parsing (void *context)
 Resume a document parsing when the parsing of an XML fragment has been initiated or achieved.
DC_RT_FMAC1 int epx_get_parser_error (void *context)
 Returns the last the implementation dependent error code.
DC_RT_FMAC1 void epx_delete_parser (void *context)
 Allows the implementation to free parsing resources.
DC_RT_FMAC1 epx_event epx_next (void *context)
 Makes the parser to process the next XML event.
DC_RT_FMAC1 epx_event epx_get_event (void *context)
 Get the current XML event.
DC_RT_FMAC1 char * epx_get_characters (void *context)
 Reads character data for ATTRIBUTE, CHARACTERS an COMMENT events in a row.
DC_RT_FMAC1 size_t epx_read_characters (void *context, char *dest, size_t length)
 Streaming access to the CHARACTERS event data.
DC_RT_FMAC1 char * epx_get_ns_prefix (void *context)
 Get the namespace prefix for an element.
DC_RT_FMAC1 char * epx_get_ns_uri (void *context)
 Get the namespace URI for an element.
DC_RT_FMAC1 char * epx_get_lname (void *context)
 Get the local name for an element.
DC_RT_FMAC1 int epx_get_att_nb (void *context)
 Get the number of attributes for an element.
DC_RT_FMAC1 char * epx_get_att_ns_prefix (void *context, int index)
 Get an attribute namespace prefix.
DC_RT_FMAC1 char * epx_get_att_ns_uri (void *context, int index)
 Get an attribute namespace URI.
DC_RT_FMAC1 char * epx_get_att_lname (void *context, int index)
 Get an attribute local name.
DC_RT_FMAC1 char * epx_get_att_value (void *context, int index)
 Get an attribute value.
DC_RT_FMAC1 char * epx_get_prefix_uri (void *context, char *prefix)
 Get a namespace URI for a particular prefix.
DC_RT_FMAC1 char * epx_get_uri_prefix (void *context, char *uri)
 Get a namespace prefix for a particular URI.
Typed parsing API
DC_RT_FMAC1 unsigned char * epx_get_base64_binary (void *context, size_t *length)
 Reads base 64-encoded binary data for CHARACTERS or ATTRIBUTE events in a row.
DC_RT_FMAC1 size_t epx_read_base64_binary (void *context, unsigned char *dest, size_t length)
 Streaming access to the CHARACTERS event base 64-encoded binary data.
DC_RT_FMAC1 unsigned char * epx_get_hex_binary (void *context, size_t *length)
 Reads hexadecimal-encoded binary data for CHARACTERS or ATTRIBUTE events in a row.
DC_RT_FMAC1 size_t epx_read_hex_binary (void *context, unsigned char *dest, size_t length)
 Streaming access to the CHARACTERS event hexadecimal-encoded binary data.
DC_RT_FMAC1 int epx_get_boolean (void *context, epx_boolean_t *b)
 Reads the data for CHARACTERS or ATTRIBUTE events as a boolean.
DC_RT_FMAC1 int epx_get_long (void *context, long *l)
 Reads the data for CHARACTERS or ATTRIBUTE events as a long int.
DC_RT_FMAC1 int epx_get_ulong (void *context, unsigned long *ul)
 Reads the data for CHARACTERS or ATTRIBUTE events as a unsigned long int.
DC_RT_FMAC1 int epx_get_float (void *context, float *f)
 Reads the data for CHARACTERS or ATTRIBUTE events as a float.
DC_RT_FMAC1 int epx_get_double (void *context, double *d)
 Reads the data for CHARACTERS or ATTRIBUTE events as a double.
DC_RT_FMAC1 int epx_get_qname (void *context, epx_qname_t *qn)
 Reads the data for CHARACTERS or ATTRIBUTE events as a qualified name.
Typed serialization API
DC_RT_FMAC1 int epx_write_base64_binary (void *context, unsigned char *buffer, size_t length)
 Writes a CHARACTER event with base64 binary data into the XML stream.
DC_RT_FMAC1 int epx_write_hex_binary (void *context, unsigned char *buffer, size_t length)
 Writes hexadecimal-encoded binary data into the XML stream.
DC_RT_FMAC1 int epx_put_boolean (void *context, epx_boolean_t b)
 Produces a CHARACTER event from a boolean.
DC_RT_FMAC1 int epx_put_long (void *context, long l)
 Produces a CHARACTER event from a long integer.
DC_RT_FMAC1 int epx_put_ulong (void *context, unsigned long ul)
 Produces a CHARACTER event from a unsigned long integer.
DC_RT_FMAC1 int epx_put_float (void *context, float f)
 Produces a CHARACTER event from a float.
DC_RT_FMAC1 int epx_put_double (void *context, double d)
 Produces a CHARACTER event from a double.
DC_RT_FMAC1 int epx_put_qname (void *context, epx_qname_t *qn)
 Produces a CHARACTER event from a qualified name.
DC_RT_FMAC1 int epx_add_base64_attribute (void *context, char *ns_uri, char *local_name, unsigned char *buffer, size_t length)
 Writes a base64 binary ATTRIBUTE event into the XML stream.
DC_RT_FMAC1 int epx_add_hex_attribute (void *context, char *ns_uri, char *local_name, unsigned char *buffer, size_t length)
 Writes hexadecimal-encoded binary ATTRIBUTE event into the XML stream.
DC_RT_FMAC1 int epx_add_boolean_attribute (void *context, char *ns_uri, char *local_name, epx_boolean_t b)
 Produces an ATTRIBUTE event from a boolean.
DC_RT_FMAC1 int epx_add_long_attribute (void *context, char *ns_uri, char *local_name, long l)
 Produces an ATTRIBUTE event from a long integer.
DC_RT_FMAC1 int epx_add_ulong_attribute (void *context, char *ns_uri, char *local_name, unsigned long ul)
 Produces an ATTRIBUTE event from a unsigned long integer.
DC_RT_FMAC1 int epx_add_float_attribute (void *context, char *ns_uri, char *local_name, float f)
 Produces an ATTRIBUTE event from a float.
DC_RT_FMAC1 int epx_add_double_attribute (void *context, char *ns_uri, char *local_name, double d)
 Produces an ATTRIBUTE event from a double.
DC_RT_FMAC1 int epx_add_qname_attribute (void *context, char *ns_uri, char *local_name, epx_qname_t *qn)
 Produces an ATTRIBUTE event from a qualified name.

Serialization API

#define EPX_OPT_UTF8_INPUT   0x01
 Inputs are supposed in multi-byte UTF-8, else UCS-4 cast to char (i.e.
#define EPX_OPT_GENERATE_PREFIXES   0x02
 Generate automatically namespace prefixes when not specified using the serialization API.
#define EPX_OPT_GENERATE_UTF16   0x04
 The XML generated is encoded using UTF-16.
#define EPX_OPT_SERIALIZER_STREAMING   0x08
 Streaming on data buffers is supported.
#define EPX_OPT_SUPPORTS_COMMENTS   0x10
 The serializer implementation supports comment events.
#define EPX_OPT_INDENT   0x20
 If enabled, output will be indented automatically.
DC_RT_FMAC1 int epx_get_serializer_options (void *implementation)
 Gets the serializer default options settings.
DC_RT_FMAC1 int epx_is_serializer_option_settable (void *implementation, int option)
 Test if a parser option can be enabled of disabled.
DC_RT_FMAC1 void * epx_new_serializer (void *implementation, void *impl_data)
 Creates a new serializer from a given EPX implementation.
DC_RT_FMAC1 int epx_get_serializer_error (void *context)
 Returns the last the implementation dependent error code.
DC_RT_FMAC1 void epx_delete_serializer (void *context)
 Allows the implementation to free serialization resources.
DC_RT_FMAC1 int epx_start_document (void *context, void *dest, int options)
 Start the XML serialization for the implementation opaque id.
DC_RT_FMAC1 int epx_end_document (void *context)
 Ends the XML document serialization.
DC_RT_FMAC1 int epx_start_element (void *context, char *ns_uri, char *local_name)
 Generates a START_ELEMENT event.
DC_RT_FMAC1 int epx_define_prefix (void *context, char *prefix, char *ns_uri)
 Generates a PREFIX_DEFINITION event.
DC_RT_FMAC1 int epx_add_attribute (void *context, char *ns_uri, char *local_name, char *value)
 Generates an ATTRIBUTE event.
DC_RT_FMAC1 int epx_end_element (void *context, char *ns_uri, char *local_name)
 Generates an END_ELEMENT event.
DC_RT_FMAC1 int epx_put_characters (void *context, char *value)
 Writes character data using a string.
DC_RT_FMAC1 int epx_write_characters (void *context, char *buffer, size_t length)
 Writes character data using buffer copy (direct access).
DC_RT_FMAC1 int epx_start_cdata (void *context)
 Generates a START_CDATA event.
DC_RT_FMAC1 int epx_end_cdata (void *context)
 Generates a END_CDATA event.
DC_RT_FMAC1 int epx_comment (void *context, char *value)
 Generates a COMMENT event.


Detailed Description

Streaming XML processing API using the pull-parsing approach.

NOTES:

  1. This XML parsing API is currently focused and optimised for the XML subset used by SOAP 1.2. This is why for instance, processing instructions are not considered. Entities are also supposed to be resolved by the parser. As a low-level API with no validation, whitespaces are processed like any other character data.
  2. The typed API is still experimental and may change in subsequent versions.

Define Documentation

#define EPX_OK   0

No error.

#define EPX_ERR_UNKNOWN_OPTION   -1

The option is not recognized by the implementation.

#define EPX_ERR_NOT_SUPPORTED   -2

Call not supported by the parser or for the current event.

#define EPX_ERR_INVALID_REPRESENTATION   -3

Typed API could not convert XML to native data.

#define EPX_ERR_OUT_OF_RANGE   -4

Typed API could convert XML to native data but the value is out of the target type range.

#define EPX_ERR_IMPLEMENTATION   -5

Implementation-specific error to retrieve using a dedicated API.

#define EPX_ERR_INVALID_PARAMETER   -6

A parameter passed to the API is incorrect.

#define EPX_OPT_COALESCING   0x01

Returns all consecutive char data ignoring comments in one event (PI are excluded for SOAP 1.2).

#define EPX_OPT_IGNORE_COMMENTS   0x02

Parsing will not produce COMMENT events.

#define EPX_OPT_UTF8_OUTPUT   0x04

output are in multi-byte UTF-8, else UCS-4 cast to char (i.e.

ISO-LATIN-1).

#define EPX_OPT_PARSER_STREAMING   0x08

Streaming on data buffers is supported.

#define EPX_OPT_GENERATE_PREFIX_DEFINITIONS   0x10

Prefix definition will be generated instead of ordinary attribute events.

#define EPX_OPT_FRAGMENT_PARSING   0x20

Fragment feature supported.

#define EPX_OPT_UTF8_INPUT   0x01

Inputs are supposed in multi-byte UTF-8, else UCS-4 cast to char (i.e.

ISO-LATIN-1).

#define EPX_OPT_GENERATE_PREFIXES   0x02

Generate automatically namespace prefixes when not specified using the serialization API.

#define EPX_OPT_GENERATE_UTF16   0x04

The XML generated is encoded using UTF-16.

The default that must be supported is UTF-8.

#define EPX_OPT_SERIALIZER_STREAMING   0x08

Streaming on data buffers is supported.

#define EPX_OPT_SUPPORTS_COMMENTS   0x10

The serializer implementation supports comment events.

#define EPX_OPT_INDENT   0x20

If enabled, output will be indented automatically.


Enumeration Type Documentation

enum epx_event

XML events definition which is fundamental for API usage.

Note that among available events, some of them have an order that is not obvious and are specific to the EPX API. These are the events related to element tag parsing which order must be:

  1. EPX_EVT_START_ELEMENT
  2. EPX_EVT_PREFIX_DEFINITION
  3. EPX_EVT_ATTRIBUTE (xsi:type, then xsi:nil should be first)
Enumerator:
EPX_EVT_ERROR  The processor stopped because of an error.
EPX_EVT_IDLE  No parsing running.
EPX_EVT_START_DOCUMENT  XML document prolog event.
EPX_EVT_END_DOCUMENT  The XML file processing is finished.
EPX_EVT_START_ELEMENT  Element start-tag event.
EPX_EVT_PREFIX_DEFINITION  Prefix definition event (xmlns attributes).
EPX_EVT_ATTRIBUTE  Attribute event.
EPX_EVT_END_ELEMENT  Element end-tag event.
EPX_EVT_CHARACTERS  Characters events that may occur several time consecutively if the parser decides it.

Coalescing is not required.

EPX_EVT_COMMENT  Comment event.
EPX_EVT_START_CDATA  Some implementations like the EPX/gSOAP may not be able to produce CDATA events.

EPX_EVT_END_CDATA  Some implementations like the EPX/gSOAP may not be able to produce CDATA events.

EPX_EVT_END_FRAGMENT  Generated when a fragment end has been reached.

A fragment is started using epx_start_fragment_parsing.


Function Documentation

DC_RT_FMAC1 int epx_get_parser_options ( void *  implementation  ) 

Gets the parser default options settings.

Parameters:
implementation A pointer on the EPX implementation. Reserved for later use (set NULL).
Returns:
An integer describing the default behavior of the parser during parsing. The default options values maybe the only one supported. This can be established by calling the is_processor_option_settable API for a particular option.

DC_RT_FMAC1 int epx_is_parser_option_settable ( void *  implementation,
int  option 
)

Test if a parser option can be enabled of disabled.

Parameters:
implementation A pointer on the EPX implementation. Reserved for later use (set NULL).
option The option to test.
Returns:
1 if settable, 0 if not and EPX_ERR_UNKNOWN_OPTION if the option is not recognized.

DC_RT_FMAC1 void* epx_new_parser ( void *  implementation,
void *  impl_data 
)

Creates a new parser from a given EPX implementation.

Parameters:
implementation A pointer on the EPX implementation. Reserved for later use (setting NULL will select the implementation over gSOAP).
impl_data Custom data that may be required by the implementation for instance to avoid dynamic allocation for the parser context. If NULL is provided as implementation, this should point to a soap structure.
Returns:
An implementation dependent parsing context. If an error occurred the implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 int epx_start_parsing ( void *  context,
void *  source,
int  options 
)

Start the XML parsing for the implementation opaque id.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
source Data identifying in an implementation-dependent way the XML file or stream. If the implementation is gSOAP, may be NULL (current message processing).
options Which capabilities should be used for XML processing.
Returns:
An implementation-dependent error code.

DC_RT_FMAC1 int epx_set_parsing_options ( void *  context,
int  options 
)

Set parsing options while parsing is running.

May not be supported by the implementation.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
options Which capabilities should be used for XML processing.
Returns:
An implementation-dependent error code, especially EPX_ERR_NOT_SUPPORTED

DC_RT_FMAC1 int epx_get_parsing_options ( void *  context  ) 

Get the current parsing options.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
Which capabilities should be used for XML processing.

DC_RT_FMAC1 int epx_start_fragment_parsing ( void *  context,
epx_boolean_t  gen_all_pfx_events 
)

Start the parsing of an XML fragment when an XML parsing is running, meaning that the parsing will stop after the child elements have been completely parsed.

Note that all applicable prefix definitions (potentially defined on any element from the root of the document to the root of the fragment) can be sent in a row when starting to parse the fragment in order to provide all the information available to the XML stream handler.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
gen_all_pfx_events If EPX_TRUE, all event (minus doubles) should be sent at the root of the fragment. Relevant only if prefix generation is enabled.
Returns:
An implementation-dependent error code.

DC_RT_FMAC1 int epx_reset_fragment_parsing ( void *  context  ) 

Resume a document parsing when the parsing of an XML fragment has been initiated or achieved.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
An implementation-dependent error code.

DC_RT_FMAC1 int epx_get_parser_error ( void *  context  ) 

Returns the last the implementation dependent error code.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
An implementation-dependent error code.

DC_RT_FMAC1 void epx_delete_parser ( void *  context  ) 

Allows the implementation to free parsing resources.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.

DC_RT_FMAC1 epx_event epx_next ( void *  context  ) 

Makes the parser to process the next XML event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
The event that was processed. IDLE is returned if no more events are expected. ERROR if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 epx_event epx_get_event ( void *  context  ) 

Get the current XML event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
The current parsing XML event.

DC_RT_FMAC1 char* epx_get_characters ( void *  context  ) 

Reads character data for ATTRIBUTE, CHARACTERS an COMMENT events in a row.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The data is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 size_t epx_read_characters ( void *  context,
char *  dest,
size_t  length 
)

Streaming access to the CHARACTERS event data.

With this API, data can be accessed block by block by the application.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
dest The destination address for the copied character data. The data is either UTF-8 or ISO-LATIN-1 (according to the option set for parsing).
length The size of the destination buffer and then the length of the data that must be copied.
Returns:
The size of the data actually read or an EPX error code.

DC_RT_FMAC1 char* epx_get_ns_prefix ( void *  context  ) 

Get the namespace prefix for an element.

Callable on the START_ELEMENT, PREFIX_DEFINITION, ATTRIBUTE and END_ELEMENT events.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The namespace prefix is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_ns_uri ( void *  context  ) 

Get the namespace URI for an element.

Callable on the START_ELEMENT, PREFIX_DEFINITION, ATTRIBUTE and END_ELEMENT events.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The namespace URI is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_lname ( void *  context  ) 

Get the local name for an element.

Callable on the START_ELEMENT, ATTRIBUTE and END_ELEMENT events.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The local name is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 int epx_get_att_nb ( void *  context  ) 

Get the number of attributes for an element.

Callable on the START_ELEMENT event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
Deprecated:
May be removed in next version.
Returns:
The number of attributes. -1 if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_att_ns_prefix ( void *  context,
int  index 
)

Get an attribute namespace prefix.

Callable on the START_ELEMENT event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
index The index of the attribute.
Deprecated:
May be removed in next version.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The namespace prefix is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_att_ns_uri ( void *  context,
int  index 
)

Get an attribute namespace URI.

Callable on the START_ELEMENT event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
index The index of the attribute.
Deprecated:
May be removed in next version.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The namespace URI is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_att_lname ( void *  context,
int  index 
)

Get an attribute local name.

Callable on the START_ELEMENT event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
index The index of the attribute.
Deprecated:
May be removed in next version.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The local name is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_att_value ( void *  context,
int  index 
)

Get an attribute value.

Callable on the START_ELEMENT event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
index The index of the attribute.
Deprecated:
May be removed in next version.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The value is supposed to be valid and accessible from the moment the API is called until next() is called. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_prefix_uri ( void *  context,
char *  prefix 
)

Get a namespace URI for a particular prefix.

Should be callable on any "parsing" event.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
prefix The prefix which namespace must be retrieved.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The value is supposed to be valid and accessible from the moment the API is called until the next xxxx_ELEMENT occurs. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 char* epx_get_uri_prefix ( void *  context,
char *  uri 
)

Get a namespace prefix for a particular URI.

Should be callable on any "parsing" event. Note that if multiple prefixes are available the latest defined should be returned.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
uri The namespace URI for which a prefix must be retrieved.
Returns:
A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for parsing). The value is supposed to be valid and accessible from the moment the API is called until the next xxxx_ELEMENT occurs. NULL if an error occured. The implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 unsigned char* epx_get_base64_binary ( void *  context,
size_t *  length 
)

Reads base 64-encoded binary data for CHARACTERS or ATTRIBUTE events in a row.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] length The size of the returned buffer.
Returns:
A character buffer containing binary data. If NULL, check for an implementation error code.

DC_RT_FMAC1 size_t epx_read_base64_binary ( void *  context,
unsigned char *  dest,
size_t  length 
)

Streaming access to the CHARACTERS event base 64-encoded binary data.

With this API, data can be accessed block by block by the application.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
dest The destination address for the copied binary data.
length The size of the destination buffer and then the length of the data that must be copied.
Returns:
The size of the data actually copied or an EPX error code.

DC_RT_FMAC1 unsigned char* epx_get_hex_binary ( void *  context,
size_t *  length 
)

Reads hexadecimal-encoded binary data for CHARACTERS or ATTRIBUTE events in a row.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] length The size of the returned buffer.
Returns:
A character buffer containing binary data. If NULL, check for an implementation error code.

DC_RT_FMAC1 size_t epx_read_hex_binary ( void *  context,
unsigned char *  dest,
size_t  length 
)

Streaming access to the CHARACTERS event hexadecimal-encoded binary data.

With this API, data can be accessed block by block by the application.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
dest The destination address for the copied binary data.
length The size of the destination buffer and then the length of the data that must be copied.
Returns:
The size of the data actually copied or an EPX error code.

DC_RT_FMAC1 int epx_get_boolean ( void *  context,
epx_boolean_t b 
)

Reads the data for CHARACTERS or ATTRIBUTE events as a boolean.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] b A pointer to a boolean supplied by the caller.
Returns:
An EPX error code, especially EPX_ERR_INVALID_REPRESENTATION if the XML value is not a valid XML schema boolean.

DC_RT_FMAC1 int epx_get_long ( void *  context,
long *  l 
)

Reads the data for CHARACTERS or ATTRIBUTE events as a long int.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] l A pointer to a long integer supplied by the caller.
Returns:
An EPX error code, especially EPX_ERR_INVALID_REPRESENTATION if the XML value is not a valid XML schema integer or EPX_ERR_OUT_OF_RANGE if it exceeds the output capacity.

DC_RT_FMAC1 int epx_get_ulong ( void *  context,
unsigned long *  ul 
)

Reads the data for CHARACTERS or ATTRIBUTE events as a unsigned long int.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] ul A pointer to a unsigned long integer supplied by the caller.
Returns:
An EPX error code, especially EPX_ERR_INVALID_REPRESENTATION if the XML value is not a valid XML schema integer or EPX_ERR_OUT_OF_RANGE if it exceeds the output capacity.

DC_RT_FMAC1 int epx_get_float ( void *  context,
float *  f 
)

Reads the data for CHARACTERS or ATTRIBUTE events as a float.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] f A pointer to a float supplied by the caller.
Returns:
An EPX error code, especially EPX_ERR_INVALID_REPRESENTATION if the XML value is not a valid XML schema float or EPX_ERR_OUT_OF_RANGE if it exceeds the output capacity.

DC_RT_FMAC1 int epx_get_double ( void *  context,
double *  d 
)

Reads the data for CHARACTERS or ATTRIBUTE events as a double.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] d A pointer to a double supplied by the caller.
Returns:
An EPX error code, especially EPX_ERR_INVALID_REPRESENTATION if the XML value is not a valid XML schema double or EPX_ERR_OUT_OF_RANGE if it exceeds the output capacity.

DC_RT_FMAC1 int epx_get_qname ( void *  context,
epx_qname_t qn 
)

Reads the data for CHARACTERS or ATTRIBUTE events as a qualified name.

Parameters:
context The implementation dependent parsing context returned by epx_new_parser.
[out] qn A pointer to a qualified name structure supplied by the caller.
Returns:
An EPX error code, especially EPX_ERR_INVALID_REPRESENTATION if the XML value is not a valid XML schema QName.

DC_RT_FMAC1 int epx_get_serializer_options ( void *  implementation  ) 

Gets the serializer default options settings.

Parameters:
implementation A pointer on the EPX implementation. Reserved for later use (set NULL).
Returns:
An integer describing the default behavior of the serializer during processing. The default options values maybe the only one supported. This can be established by calling the is_serializer_option_settable API for a particular option.

DC_RT_FMAC1 int epx_is_serializer_option_settable ( void *  implementation,
int  option 
)

Test if a parser option can be enabled of disabled.

Parameters:
implementation A pointer on the EPX implementation. Reserved for later use (set NULL).
option The option to test.
Returns:
1 if settable, 0 if not and EPX_ERR_UNKNOWN_OPTION if the option is not recognized.

DC_RT_FMAC1 void* epx_new_serializer ( void *  implementation,
void *  impl_data 
)

Creates a new serializer from a given EPX implementation.

Parameters:
implementation A pointer on the EPX implementation. Reserved for later use (setting NULL will select the implementation over gSOAP).
impl_data Custom data that may be required by the implementation for instance to avoid dynamic allocation for the serializer context. If NULL is provided as implementation, this should point to a soap structure.
Returns:
An implementation dependent serialization context. If an error occurred the implementation is responsible for supplying an error code through the parsing context.

DC_RT_FMAC1 int epx_get_serializer_error ( void *  context  ) 

Returns the last the implementation dependent error code.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
Returns:
An implementation-dependent error code.

DC_RT_FMAC1 void epx_delete_serializer ( void *  context  ) 

Allows the implementation to free serialization resources.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.

DC_RT_FMAC1 int epx_start_document ( void *  context,
void *  dest,
int  options 
)

Start the XML serialization for the implementation opaque id.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
dest Data identifying somehow the XML file or stream. If the implementation is gSOAP, may be NULL (current message processing).
options Which capabilities should be used for XML processing.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_end_document ( void *  context  ) 

Ends the XML document serialization.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_start_element ( void *  context,
char *  ns_uri,
char *  local_name 
)

Generates a START_ELEMENT event.

Implementation should start to serialize the start tag but should wait for the attributes and prefix events to be sent and to be able to close the tag or generate an empty element tag.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the element. If NULL, the element is considered to have no namespace. If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the element.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_define_prefix ( void *  context,
char *  prefix,
char *  ns_uri 
)

Generates a PREFIX_DEFINITION event.

The prefix definition will be attached to the previous start element event.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
prefix The prefix name. If NULL, the default prefix is being defined.
ns_uri The namespace URI for which the prefix is defined.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
char *  value 
)

Generates an ATTRIBUTE event.

Attributes will be attached to the previous start element event.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
value The value of the attribute.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_end_element ( void *  context,
char *  ns_uri,
char *  local_name 
)

Generates an END_ELEMENT event.

Implementation should generate an end tag or close the pending empty element tag.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the element. If NULL, the element is considered to have no namespace. If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the element.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_put_characters ( void *  context,
char *  value 
)

Writes character data using a string.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
value A string containing UTF-8 or ISO-LATIN-1 (according to the option set for serialization).
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_write_characters ( void *  context,
char *  buffer,
size_t  length 
)

Writes character data using buffer copy (direct access).

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
buffer A character buffer containing UTF-8 or ISO-LATIN-1 (according to the option set for serialization).
length The size of character data contained in the buffer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_start_cdata ( void *  context  ) 

Generates a START_CDATA event.

A CDATA start tag is generated.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_end_cdata ( void *  context  ) 

Generates a END_CDATA event.

A CDATA end tag is generated.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_comment ( void *  context,
char *  value 
)

Generates a COMMENT event.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
value The comment string.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise especially EPX_ERR_NOT_SUPPORTED if option SUPPORTS_COMMENTS is not supported or activated.

DC_RT_FMAC1 int epx_write_base64_binary ( void *  context,
unsigned char *  buffer,
size_t  length 
)

Writes a CHARACTER event with base64 binary data into the XML stream.

Note that no more that one CHARACTER event should be sent consecutively because of base64 padding.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
buffer A character buffer containing binary data.
length The size of binary data contained in the buffer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise especially EPX_ERR_NOT_SUPPORTED if option PARSER_STREAMING is not supported or activated.

DC_RT_FMAC1 int epx_write_hex_binary ( void *  context,
unsigned char *  buffer,
size_t  length 
)

Writes hexadecimal-encoded binary data into the XML stream.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
buffer A character buffer containing binary data.
length The size of binary data contained in the buffer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise especially EPX_ERR_NOT_SUPPORTED if option PARSER_STREAMING is not supported or activated.

DC_RT_FMAC1 int epx_put_boolean ( void *  context,
epx_boolean_t  b 
)

Produces a CHARACTER event from a boolean.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
b A boolean value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_put_long ( void *  context,
long  l 
)

Produces a CHARACTER event from a long integer.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
l A long integer value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_put_ulong ( void *  context,
unsigned long  ul 
)

Produces a CHARACTER event from a unsigned long integer.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ul A unsigned long integer value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_put_float ( void *  context,
float  f 
)

Produces a CHARACTER event from a float.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
f A float value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_put_double ( void *  context,
double  d 
)

Produces a CHARACTER event from a double.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
d A double value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_put_qname ( void *  context,
epx_qname_t qn 
)

Produces a CHARACTER event from a qualified name.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
qn A qualified name value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_base64_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
unsigned char *  buffer,
size_t  length 
)

Writes a base64 binary ATTRIBUTE event into the XML stream.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
buffer A character buffer containing binary data.
length The size of binary data contained in the buffer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise especially EPX_ERR_NOT_SUPPORTED if option PARSER_STREAMING is not supported or activated.

DC_RT_FMAC1 int epx_add_hex_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
unsigned char *  buffer,
size_t  length 
)

Writes hexadecimal-encoded binary ATTRIBUTE event into the XML stream.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
buffer A character buffer containing binary data.
length The size of binary data contained in the buffer.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise especially EPX_ERR_NOT_SUPPORTED if option PARSER_STREAMING is not supported or activated.

DC_RT_FMAC1 int epx_add_boolean_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
epx_boolean_t  b 
)

Produces an ATTRIBUTE event from a boolean.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
b A boolean value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_long_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
long  l 
)

Produces an ATTRIBUTE event from a long integer.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
l A long integer value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_ulong_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
unsigned long  ul 
)

Produces an ATTRIBUTE event from a unsigned long integer.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
ul A unsigned long integer value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_float_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
float  f 
)

Produces an ATTRIBUTE event from a float.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
f A float value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_double_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
double  d 
)

Produces an ATTRIBUTE event from a double.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
d A double value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.

DC_RT_FMAC1 int epx_add_qname_attribute ( void *  context,
char *  ns_uri,
char *  local_name,
epx_qname_t qn 
)

Produces an ATTRIBUTE event from a qualified name.

Parameters:
context The implementation dependent serialization context returned by epx_new_serializer.
ns_uri The namespace URI of the attribute. If NULL, the attribute is considered element local (no namespace). If no prefix was defined for the namespace the implementation will either generate a prefix or raise an error according to the GENERATE_PREFIXES option.
local_name The namespace URI of the attribute.
qn A qualified name value.
Returns:
EPX_OK if no error occurred. An EPX error code otherwise.


Generated on Fri Apr 17 15:18:25 2009 for DPWSCore by  doxygen 1.5.8