SOAP Message Handles

Functions

Function Documentation

globus_result_t globus_soap_message_handle_init_from_dom ( globus_soap_message_handle_t *  new_handle,
xmlDocPtr  dom 
)

Create a handle usable for deserializing XML from a DOM tree to C Bindings

Creates a handle which can be used to deserialize an XML DOM tree into a C bindings structure.

XML deserializers can be used to extract elements and attributes into C data structures from the new_handle.

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for read-only operations to extract the DOM tree into C data structures related to an XML schema definition.
dom A libxml2 DOM tree. The DOM must not be accessed while the handle pointed to by new_handle exists. The caller is responsible for freeing the DOM after the handle is destroyed.
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

globus_result_t globus_soap_message_handle_init_from_file ( globus_soap_message_handle_t *  new_handle,
const char *  file_contact 
)

Create a handle usable for deserializing XML from a file

Creates a handle which can be used to deserialize an XML document located in a local file into a C bindings structure.

XML deserializers can be used to extract elements and attributes into C data structures from the new_handle.

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for read-only operations to read the XML document in the named file into C data structures related to an XML schema definition.
file_contact An xio file contact (path or file:// URL) which contains an XML document.
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

globus_result_t globus_soap_message_handle_init_from_memory ( globus_soap_message_handle_t *  new_handle,
const char *  buffer,
int  size 
)

Create a handle usable for deserializing XML from a memory block

Creates a handle which can be used to deserialize an XML document located in memory into a C bindings structure.

XML deserializers can be used to extract elements and attributes into C data structures from the new_handle. The memory block buffer must not be freed until @ new_handle is destroyed.

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for read-only operations to deserialize the XML document from the memory block into C data structures.
buffer A memory block containing an XML document.
size Size of the buffer block.
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

globus_result_t globus_soap_message_handle_init_to_dom ( globus_soap_message_handle_t *  new_handle,
xmlDocPtr *  new_dom 
)

Create a handle usable for serializing C bindings structures to a libxml2 DOM tree

Creates a handle which can be used to serialize an XML document from a C bindings structure and its subelements.

XML serializers can be used to serialize the root and child elements and attributes to the DOM. The caller must free both the DOM (by calling xmlFreeDoc()) and the SOAP handle (by calling globus_soap_message_handle_destroy()).

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for write-only operations to serialize the XML document to the DOM.
new_dom Pointer to a DOM pointer to be initialized. As elements are serialized on the new_handle, they will be added to the DOM.
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

globus_result_t globus_soap_message_handle_init_to_memory ( globus_soap_message_handle_t *  new_handle,
xmlBufferPtr  buffer 
)

Create a handle usable for serializing C bindings structures to a memory block

Creates a handle which can be used to serialize an XML document from a C bindings structure and its subelements.

XML serializers can be used to serialize the root and child elements and attributes to the memory block. The caller must free both the memory (by calling xmlFreeBuffer()) and the SOAP handle (by calling globus_soap_message_handle_destroy()).

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for write-only operations to serialize the XML document to the memory block.
buffer Pointer to a libXML2 buffer. As elements are serialized on the new_handle, they will be added to the buffer.
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

globus_result_t globus_soap_message_handle_init_to_file ( globus_soap_message_handle_t *  new_handle,
const char *  file_contact,
globus_xio_file_flag_t  open_flags 
)

Create a handle usable for serializing XML to a file

Creates a handle which can be used to serialize an XML document from a C bindings structure and its subelements.

XML serializers can be used to serialize the root and child elements and attributes to the named file. The file may not be flushed until the globus_soap_message_handle_destroy() function is called.

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for write-only operations to serialize the XML document into the named file.
file_contact Path to a file to serialize XML content into.
open_flags Desired flags to use to open the file.
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

globus_result_t globus_soap_message_handle_init ( globus_soap_message_handle_t *  new_handle,
globus_xio_handle_t  xio_handle 
)

Create a handle usable for processing SOAP message exchanges

Creates a handle which can be used to process SOAP message exchanges.

The XIO handle should be created with a suitable XIO stack for processing a SOAP messages. This should probably only be called by the GLOBUS_SERVICE_ENGINE module.

Parameters:
new_handle Pointer to a new SOAP message handle which will be initialized. This handle will be usable for processing SOAP messages.
xio_handle XIO handle to send SOAP messages on
Return values:
GLOBUS_SUCCESS Handle created successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to create the handle.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_INIT_FAILED Error initializing some part of the handle.

void globus_soap_message_handle_reset ( globus_soap_message_handle_t  handle  ) 

Reinitialize a SOAP message handle

This is used internally by the globus_service_engine to prepare a SOAP handle for another SOAP message on a SOAP handle.

This occurs when it processes a persistent connection.

Parameters:
handle Handle to reset

void globus_soap_message_handle_destroy ( globus_soap_message_handle_t  handle  ) 

Destroy a SOAP message handle

Frees memory and closes open files associated with a SOAP message handle.

Parameters:
handle Handle to destroy

void globus_soap_message_handle_register_destroy ( globus_soap_message_handle_t  handle,
globus_callback_func_t  destroy_callback,
void *  destroy_args 
)

Destroy a SOAP message handle with a callback

This behaves similar to globus_soap_message_handle_destroy() but will call the user's callback function after the handle has been destroyed and all xio handled associated with it are destroyed.

Parameters:
handle SOAP message handle to destroy.
destroy_callback Callback function to call when the handle has been completely destroyed.
destroy_args Application-specific parameter to destroy_callback.

globus_result_t globus_soap_message_set_marker ( globus_soap_message_handle_t  handle,
const char *  marker 
)

Add a named maker location to an XML input or output stream

If the handle is currently being used to read an XML message, this function will create a new marker in the XML stream which can be used to later extract the content of the XML buffer at the marked point.

If the handle is being used to write an XML message, this function will create a new marker in the XML stream which can be used to later insert XML content at the marked point.

Parameters:
handle SOAP message handle to mark.
marker Null-terminated string containing the name of the marker. A copy of the string will be made and used internally.
Return values:
GLOBUS_SUCCESS Marker set successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or marker is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_WITH_MARKER Unable to flush write buffers or create the marker.

globus_result_t globus_soap_message_get_marked_buffer ( globus_soap_message_handle_t  handle,
const char *  marker,
char **  out_buffer,
size_t *  out_length 
)

Extract a copy of the content of a portion of an XML message

This function will create a copy of the data between the location indicated by marker and the next marker in the stream.

The buffer's contents and length will be returned in out_buffer and out_length.

Parameters:
handle SOAP message handle to extract the marked buffer from.
marker Null-terminated string containing the name of the marker.
out_buffer Pointer to be set to a copy of the marked buffer's data. The caller is responsible for freeing the value pointed to by this.
out_length Length of the data in the marked area.
Return values:
GLOBUS_SUCCESS Marked buffer retrieved successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle, marker, out_buffer or out_length was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_WITH_MARKER Marker not found or out of memory occurred while processing the marker.

globus_result_t globus_soap_message_get_marked_buffers ( globus_soap_message_handle_t  handle,
const char *  begin_marker,
const char *  end_marker,
char **  out_buffer,
size_t *  out_length 
)

Extract a copy of the content of a portion of an XML message

This function will create a copy of the data between the location indicated by begin_marker and end_marker in the stream.

The buffer's contents and length will be returned in out_buffer and out_length.

Parameters:
handle SOAP message handle to extract the marked buffer from.
begin_marker Null-terminated string containing the name of the marker. If NULL, extract from beginning of the buffered data.
end_marker Null-terminated string containing the name of the marker. If NULL, extract to the end of the buffered data.
out_buffer Pointer to be set to a copy of the marked buffer's data. The caller is responsible for freeing the value pointed to by this.
out_length Length of the data in the marked area.
Return values:
GLOBUS_SUCCESS Marked buffer retrieved successfully.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle, marker, out_buffer or out_length was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_WITH_MARKERS Marker not found or out of memory occurred while processing the marker.

globus_result_t globus_soap_message_set_write_position_to_marker ( globus_soap_message_handle_t  handle,
const char *  marker 
)

Set the write position of an SOAP message handle to the location of a marker

Flushes the XML buffer and then sets the SOAP message handle to write after the named marker location.

This can be used to fill in the content of an XML element after the rest of the message has been serialized.

Parameters:
handle SOAP message handle to update.
marker Name of the marker to set the write position to. This marker must be previously created by calling globus_soap_message_set_marker().
Return values:
GLOBUS_SUCCESS Write position updated.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or marker was NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_WITH_MARKER Marker not found.

globus_result_t globus_soap_message_get_handler_chain ( globus_soap_message_handle_t  handle,
globus_handler_chain_t *  chain 
)

Get the handler chain associated with a SOAP message handle

Get the current handler chain associated with handle.

This chain is used when processing SOAP messages.

Parameters:
handle SOAP message handle to get the value from.
chain Pointer to be set to the current handler chain.

globus_result_t globus_soap_message_set_handler_chain ( globus_soap_message_handle_t  handle,
globus_handler_chain_t  chain 
)

Set the handler for a SOAP message handle

Set the handler registry to use when using processing SOAP messages.

Handlers deal with SOAP envelope elements and perform special processing, such as adding WS-Secure Message signature elements, or using WS-Addressing headers to dispatch a SOAP operation.

Parameters:
handle SOAP message handle to update.
chain New value of the handler chain to use. This must not be freed while any handle exists which uses this chain.

globus_result_t globus_soap_message_get_transport_handle ( globus_soap_message_handle_t  message,
globus_xio_handle_t *  handle 
)

Get the XIO handle associated with a SOAP message handle

Get the current XIO handle associated with handle.

This XIO handle is used to send or receieve SOAP messages.

Parameters:
message SOAP message handle to get the value from.
handle Pointer to be set to the current XIO handle.

globus_result_t globus_soap_message_add_callout ( globus_soap_message_handle_t  message,
const xsd_QName *  element_qname,
globus_soap_message_callout_func_t  begin_callout,
globus_soap_message_callout_func_t  end_callout,
globus_soap_message_callout_func_t  attr_callout 
)

Add callout functions to process an element

Callouts are functions which are called when an element is serialized or deserialized.

Three types of callouts can be registred by this function:

GLOBUS_SOAP_MESSAGE_CALLOUT_BEGIN
Called when the open tag element is serialized or deserialized.
GLOBUS_SOAP_MESSAGE_CALLOUT_END
Called when the close element tag is serialized.
GLOBUS_SOAP_MESSAGE_CALLOUT_ATTR
Called after the last attribute for an element is serialized.
For each element name, multiple callouts may be registered. Any of the callouts passed to this function may be NULL.

Parameters:
message SOAP message handle to register the callouts on.
element_qname Name of the XML element to trigger this set of callouts.
begin_callout Pointer to the GLOBUS_SOAP_MESSAGE_CALLOUT_BEGIN callout function.
end_callout Pointer to the GLOBUS_SOAP_MESSAGE_CALLOUT_END callout function.
attr_callout Pointer to the GLOBUS_SOAP_MESSAGE_CALLOUT_ATTR callout function.
Return values:
GLOBUS_SUCCESS Callouts successfully added.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of message or element_qname is NULL.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY Insufficent memory to add the callouts.

globus_result_t globus_soap_message_invoke_callouts ( globus_soap_message_handle_t  handle,
const xsd_QName *  element_qname,
globus_soap_message_callout_type_t  type 
)

Invoke callout functions when processing an element

This function is called as the SOAP message is processed and calls out to each callout of type matching type associated with the element in the handle.

If any callout returns a non-GLOBUS_SUCCESS result, processing will finish with an error. The order of callout invocation is not specified.

Parameters:
handle SOAP message handle currently processing the message.
element_qname Name of the XML element trigger for the callouts.
type One of GLOBUS_SOAP_MESSAGE_CALLOUT_BEGIN, GLOBUS_SOAP_MESSAGE_CALLOUT_END, or GLOBUS_SOAP_MESSAGE_CALLOUT_ATTR, indicating the type of callout to invoke.
Return values:
GLOBUS_SUCCESS Callouts successfully invoked.
GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM One of handle or element_qname is NULL.
Other return values indicate an error generated by a callout function.

void globus_soap_message_remove_callouts ( globus_soap_message_handle_t  message,
const xsd_QName *  element_qname 
)

Remove callouts associated with an element name from a SOAP message handle.

Parameters:
message SOAP message handle to remove callouts from.
element_qname Name of the XML element indicating which callouts to remove.

about globus | grid research | globus toolkit | software development

Comments? webmaster@globus.org