SOAP deserialization support functions

These functions are used by XML deserializers to deserialize the various element and attribute strings from an XML handle. More...

Functions

Detailed Description

These functions are used by XML deserializers to deserialize the various element and attribute strings from an XML handle.

Function Documentation

void globus_soap_message_deserialize_push_element ( globus_soap_message_handle_t  handle  ) 

Push the current XML element onto the deserialization stack

This causes the next attempt to deserialize an element to return the current element.

This is used by functions which want to know the name of the next element before calling the appropriate deserializer for it.

Parameters:
handle SOAP message handle which is deserializing the XML content.

globus_result_t globus_soap_message_deserialize_element_end ( globus_soap_message_handle_t  handle,
const xsd_QName *  qname 
)

Deserialize the end tag for the named element

Deserialize the closing tag for the current element.

If qname is non-NULL, then the element name must match it.

Parameters:
handle SOAP message handle which is deserializing the XML element.
qname If non-NULL, The name of the element which is being deserialized.
Return values:
GLOBUS_SUCCESS Element close tag deserialized successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM The handle parameter was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_FAILED_END_ELEMENT The next XML node was not an end element that matches qname.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_FAILED_NEXT_NODE The XML document ended before an end element could be parsed.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_FAILED_WITH_TEXT The next XML node contained unexpected text content.
GLOBUS_SOAP_MESSAGE_STATUS_FAILED_ELEMENT (This is a constant value, not a globus_result_t)
Other return values may indicate an error generated by a callout function.

globus_result_t globus_soap_message_deserialize_skip ( globus_soap_message_handle_t  handle  ) 

Advance the XML parsing state to the end of the current element's closing tag.

Parameters:
handle SOAP message handle to advance.
Return values:
GLOBUS_SUCCESS XML parsing state advanced successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_FAILED_NEXT_NODE Unable to read another XML node.

globus_result_t globus_soap_message_deserialize_envelope ( globus_soap_message_handle_t  handle  ) 

Deserialize a SOAP envelope element

Deserializes the current element and is successfully only if the element is a SOAP envelope element.

Additionally the marker named GLOBUS_SOAP_MESSAGE_MARKER_ENVELOPE will be set at the beginning of the envelope open element.

Parameters:
handle SOAP message handle to deserialize the envelope from.
Return values:
GLOBUS_SUCCESS Envelope successfully deserialized.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM Handle was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Error deserializing envelope element.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_ELEMENT_NOT_FOUND The next XML element is not a SOAP envelope element.

globus_result_t globus_soap_message_deserialize_envelope_end ( globus_soap_message_handle_t  handle  ) 

Deserialize the end tag for a SOAP envelope element

Deserializes the end tag of the element currently being processed and is successfully only if the element is a SOAP envelope element.

Additionally the marker named GLOBUS_SOAP_MESSAGE_MARKER_ENVELOPE_END will be set at the end of the envelope close tag.

Parameters:
handle SOAP message handle to deserialize the envelope from.
Return values:
GLOBUS_SUCCESS Envelope successfully deserialized.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM Handle was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Error deserializing envelope end tag.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_WITH_MARKER Error setting end-of-envelope marker in the XML stream.

globus_result_t globus_soap_message_deserialize_header ( globus_soap_message_handle_t  handle  ) 

Deserialize a SOAP header element

Deserializes the current element and is successfully only if the element is a SOAP header.

Parameters:
handle SOAP message handle to deserialize the header from.
Return values:
GLOBUS_SUCCESS Header successfully deserialized.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM Handle was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Error deserializing header element.

globus_result_t globus_soap_message_deserialize_header_end ( globus_soap_message_handle_t  handle  ) 

Deserialize the end tag for a SOAP header element

Deserializes the end tag of the element currently being processed and is successfully only if the element is a SOAP header element.

Parameters:
handle SOAP message handle to deserialize the header from.
Return values:
GLOBUS_SUCCESS Header successfully deserialized.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM Handle was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Error deserializing header end tag.

globus_result_t globus_soap_message_add_required_header_element ( globus_soap_message_handle_t  handle,
const xsd_QName *  qn 
)

Add the QName of a header which must be understood

This is used internally by the SOAP processor to require that some trigger handles the named header element.

The function globus_soap_message_check_required_headers() is called after processing all headers to determine that all necessary headers have been parsed.

Parameters:
handle SOAP message handle to add the processing requirement to.
qn Name of the element which must be processed
Return values:
GLOBUS_SUCCESS Header element QName added to the mustUnderstand list successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or qn is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficient memory to add the header element QName to the mustUnderstand list.

globus_result_t globus_soap_message_remove_required_header_element ( globus_soap_message_handle_t  handle,
const xsd_QName *  qn 
)

Remove the QName of a header which must be understood from the list after processing it

This is used by header element triggers to indicate that they've processed a required SOAP header element.

Parameters:
handle SOAP message handle to remove the processing requirement from.
qn Name of the element which was processed.
Return values:
GLOBUS_SUCCESS Header element QName removed from the mustUnderstand list successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or qn is NULL.

globus_result_t globus_soap_message_check_required_headers ( globus_soap_message_handle_t  handle  ) 

Verify that all headers which must be understood have been processed

This is used internally by the SOAP processor to check that all headers which had the mustUnderstand attribute have been processed by a handler.

Parameters:
handle SOAP message handle to check.
Return values:
GLOBUS_SUCCESS All required headers have been processed.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM Handle is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_MUST_UNDERSTAND Some required header was not processed.

globus_result_t globus_soap_message_deserialize_body ( globus_soap_message_handle_t  handle  ) 

Deserialize a SOAP body element

Deserializes the current element and is successfully only if the element is a SOAP body.

Parameters:
handle SOAP message handle to deserialize the body from.
Return values:
GLOBUS_SUCCESS Header successfully deserialized.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM Handle was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Error deserializing body element.

globus_result_t globus_soap_message_deserialize_fault ( globus_soap_message_handle_t  handle,
globus_soap_message_fault_t *  soap_fault_handle,
globus_soap_fault_callback_func_t  fault_callback,
xsd_any **  fault_any,
int *  fault_type 
)

Deserialize a SOAP fault

Deserializes a SOAP fault element, calling fault_callback to convert the fault element type to the service-specific fault type enumeration value.

Parameters:
handle SOAP message handle to deserialize the fault from.
soap_fault_handle Pointer to the fault implementation.
fault_callback Service-specific callback function to invoke
fault_any Pointer to be set to the value of the fault detail.
fault_type Pointer to be set to the service-specific fault enumeration value by the fault_callback.

globus_result_t globus_soap_message_deserialize_element_unknown ( globus_soap_message_handle_t  handle,
xsd_QName *  qname 
)

Deserialize the next element and return its QName

Deserializes the opening tag of the next element.

If the parser is able to read an element, qname will be populated with the contents of the element's QName. The caller is responsible for freeing the QName.

Parameters:
handle The SOAP message handle to parse the next element on.
qname Pointer to an xsd_QName. If parsing is successful, the Namespace and local fields of this will be modified to contain information about the element's QName.
Return values:
GLOBUS_SUCCESS The element was successfully deserialized.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or qname is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficient memory to set the fields of qname.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Unable to parse the next XML element.

globus_result_t globus_soap_message_deserialize_element ( globus_soap_message_handle_t  handle,
const xsd_QName *  qname 
)

Deserialize the next element from a SOAP message handle

Deserializes the next open element tag on a SOAP message handle.

Returns success only if the next node in the XML stream is an element tag and the element's name matches qname (provided qname is non-NULL).

Parameters:
handle The SOAP message handle to parse the next element on.
qname QName of the expected element.
Return values:
GLOBUS_SUCCESS Element deserialized successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM The handle parameter is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_DESERIALIZE_FAILED Unable to deserialize the next element.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_ELEMENT_NOT_FOUND The next XML element does not match qname.

globus_result_t globus_soap_message_deserialize_attribute ( globus_soap_message_handle_t  handle,
const xsd_QName *  attr_qname,
xmlChar **  content 
)

Deserialize an XML attribute of the current element

Attempts to deserialize an XML attribute (named attr_qname) of the current element being deserialized.

If it is present, its NULL-terminated string value will be copied into a newly allocated buffer and content will be updated to point to the value.

Parameters:
handle SOAP message handle to deserialize the attribute from.
attr_qname QName of the attribute to deserialize.
content Pointer to be set to the value of the attribute. If this is set to point to a non-NULL value, the caller must free the buffer by calling xmlFree().
Return values:
GLOBUS_SUCCESS Attribute deserialized successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle, attr_qname, or content is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_ATTRIBUTE_NOT_FOUND The attrbute is not present.

globus_result_t globus_soap_message_deserialize_mark ( globus_soap_message_handle_t  handle,
const char *  idval 
)

Set a named deserialization marker at the current location in the XML stream.

Parameters:
handle SOAP message handle to mark.
idval Name of the marker.
Return values:
GLOBUS_SUCCESS Marker set successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or idval is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_WITH_MARKER Unable to set the marker.

globus_result_t globus_soap_message_deserialize_get_prefixes ( globus_soap_message_handle_t  handle,
xsd_string_array *  namespace_prefixes 
)

Get the namespace prefixes defined in the current XML deserialization context

Modifies the contents of the namespace_prefixes parameter to have an entry of the form "prefix=namespace" for each namespace prefix defined in the current XML deserialization context.

Parameters:
handle SOAP message handle to get the namespaces list from.
namespace_prefixes Pointer to an uninitialized xsd_string_array. After successful completion, this will be updated to include an array entry for each namespace.
Return values:
GLOBUS_SUCCESS Namespace prefixes successfully copied to namespace_prefixes.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or namespace_prefixes is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficient memory to copy namespace prefix definitions into the namespace_prefixes array.

about globus | grid research | globus toolkit | software development

Comments? webmaster@globus.org