SOAP Handler Chains

Handler chains are lists of functions which are invoked at various times during SOAP message processing as a way to extend functionality of the SOAP messaging stack. More...

Functions

void globus_handler_chain_destroy (globus_handler_chain_t chain)
globus_result_t globus_handler_chain_copy (globus_handler_chain_t *dest, globus_handler_chain_t src)
globus_result_t globus_handler_chain_push (globus_handler_chain_t chain, globus_handler_type_t type, const char *endpoint)
globus_bool_t globus_handler_chain_has_trigger (globus_handler_chain_t chain, const xsd_QName *element)

Detailed Description

Handler chains are lists of functions which are invoked at various times during SOAP message processing as a way to extend functionality of the SOAP messaging stack.

Functionality such as adding WS-Addressing headers or providing debug information may be done via handlers. Applications may add additional message handling functionality by pushing handlers onto a handler chain associated with a service engine, client handle, or SOAP message handle.

Two types of handlers are supported: those which are called during particular stages of the SOAP message processing, and those which are triggered by the presence of certain elements within a SOAP header.

The first type of handlers are called by the SOAP processing at

Handler type Handler descriptor field Description

GLOBUS_HANDLER_TYPE_REQUEST_INIT request_init On the client, this is called before the HTTP handle which will be used to serialize the SOAP message has been opened. On the server, it is called after the SOAP request has been read but before it has been parsed.

GLOBUS_HANDLER_TYPE_REQUEST request On the client, this is called after the SOAP body has been serialized but before the SOAP envelope headers have been serialized. On the server, it is called after the SOAP envelope headers triggers have been called to parse the envelope before the operation has been invoked.

GLOBUS_HANDLER_TYPE_REQUEST_DESTROY request_destroy On the client, this is called after the SOAP request message has been sent. On the server, it is called after the GLOBUS_HANDLER_TYPE_REQUEST handlers.

GLOBUS_HANDLER_TYPE_RESPONSE_INIT response_init On the client, this is called after the SOAP request message has been sent. On the server, it is called after the GLOBUS_HANDLER_TYPE_REQUEST handlers.

GLOBUS_HANDLER_TYPE_RESPONSE response On the client, this is called after the SOAP header triggers have been called to process SOAP envelope header elements. On the server, this is called after the operation has completed and serialized its response. The SOAP message handle will be set to write to the SOAP envelope headers.

GLOBUS_HANDLER_TYPE_RESPONSE_DESTROY response_destroy On the client, this is not called. On the server, this is called after the GLOBUS_HANDLER_TYPE_RESPONSE handlers just prior to the response message being sent.

Function Documentation

void globus_handler_chain_destroy ( globus_handler_chain_t chain )

Destroy all state associated with a handler chain

Destroys the handler chain and frees all memory associated with it.

The chain referred to by chain should not be used after this function returns.

Parameters:

chain

The handler chain to destroy.

globus_result_t globus_handler_chain_copy	(	globus_handler_chain_t *	dest,
		globus_handler_chain_t	src
	)

Create a copy of a handler chain.

Parameters:

	dest	Pointer to hold the location of the new handler chain. This must be destroyed by the caller.
	src	Handler chain to copy.

Return values:

	GLOBUS_SUCCESS	Handler chain successfully copied.
	GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM	One of src or dest was NULL.

globus_result_t globus_handler_chain_push	(	globus_handler_chain_t	chain,
		globus_handler_type_t	type,
		const char *	endpoint
	)

Add a new handler to a handler chain

Append the handler located in endpoint to handle the type sequence of the handling processing to the given handler chain chain.

Parameters:

	chain	Handler chain to update.
	type	Type of processing to be associated with this handler.
	endpoint	Name of the shared library containing the handler.

Return values:

	GLOBUS_SUCCESS	Handler successfully added to the handler chain.
	GLOBUS_SOAP_MESSAGE_ERROR_TYPE_NULL_PARAM	One of chain or endpoint was NULL.
	GLOBUS_HANDLER_ERROR_TYPE_REGISTRY_LOOKUP_FAILED	Unable to load the handler module.
	GLOBUS_SOAP_MESSAGE_ERROR_TYPE_OUT_OF_MEMORY	Insufficient memory to add the handler to the chain.

globus_bool_t globus_handler_chain_has_trigger	(	globus_handler_chain_t	chain,
		const xsd_QName *	element
	)

Determine if a handler exists for a given element.

Parameters:

	chain	Handler chain to check.
	element	QName of the element to check for a handler for.

Return values:

	GLOBUS_TRUE	The handler chain has a handler for element.
	GLOBUS_FALSE	The handler chain does not have a handler for element.

Handler type	Handler descriptor field	Description
GLOBUS_HANDLER_TYPE_REQUEST_INIT	request_init	On the client, this is called before the HTTP handle which will be used to serialize the SOAP message has been opened. On the server, it is called after the SOAP request has been read but before it has been parsed.
GLOBUS_HANDLER_TYPE_REQUEST	request	On the client, this is called after the SOAP body has been serialized but before the SOAP envelope headers have been serialized. On the server, it is called after the SOAP envelope headers triggers have been called to parse the envelope before the operation has been invoked.
GLOBUS_HANDLER_TYPE_REQUEST_DESTROY	request_destroy	On the client, this is called after the SOAP request message has been sent. On the server, it is called after the GLOBUS_HANDLER_TYPE_REQUEST handlers.
GLOBUS_HANDLER_TYPE_RESPONSE_INIT	response_init	On the client, this is called after the SOAP request message has been sent. On the server, it is called after the GLOBUS_HANDLER_TYPE_REQUEST handlers.
GLOBUS_HANDLER_TYPE_RESPONSE	response	On the client, this is called after the SOAP header triggers have been called to process SOAP envelope header elements. On the server, this is called after the operation has completed and serialized its response. The SOAP message handle will be set to write to the SOAP envelope headers.
GLOBUS_HANDLER_TYPE_RESPONSE_DESTROY	response_destroy	On the client, this is not called. On the server, this is called after the GLOBUS_HANDLER_TYPE_RESPONSE handlers just prior to the response message being sent.