![]() |
Home | Documentation |
Context with engine state
updated Sat Sep 23 2023 by Robert van Engelen
|
This module defines the soap context structure with the engine state and functions to allocate, initialize, copy and delete contexts.
More...
Classes | |
| struct | soap |
| Context with the engine state. More... | |
Typedefs | |
| typedef char * | _XML |
| A built-in string type containing literal XML content in UTF-8 format. More... | |
| typedef char * | _QName |
| A built-in string type containing normalized QName contents. More... | |
Functions | |
| struct soap * | soap_new () |
Allocate and initialize a new soap context. More... | |
| struct soap * | soap_new1 (soap_mode input_and_output_mode) |
Allocate and initialize a new soap context with input and output soap_mode flags. More... | |
| struct soap * | soap_new2 (soap_mode input_mode, soap_mode output_mode) |
Allocate and initialize a new soap context with separate input and output soap_mode flags. More... | |
| void | soap_init (struct soap *soap) |
Initialize a stack-allocated soap context. More... | |
| void | soap_init1 (struct soap *soap, soap_mode input_and_output_mode) |
Initialize a stack-allocated soap context with input and output soap_mode flags. More... | |
| void | soap_init2 (struct soap *soap, soap_mode input_mode, soap_mode output_mode) |
Initialize a stack-allocated soap context with input and output soap_mode flags. More... | |
| void | soap_set_mode (struct soap *soap, soap_mode input_and_output_mode) |
Set input and output soap_mode flags of the given soap context. More... | |
| void | soap_set_imode (struct soap *soap, soap_mode input_mode) |
Set input soap_mode flags of the given soap context. More... | |
| void | soap_set_omode (struct soap *soap, soap_mode output_mode) |
Set output soap_mode flags of the given soap context. More... | |
| void | soap_clr_mode (struct soap *soap, soap_mode input_and_output_mode) |
Clear input and output soap_mode flags of the given soap context. More... | |
| void | soap_clr_imode (struct soap *soap, soap_mode input_mode) |
Clear input soap_mode flags of the given soap context. More... | |
| void | soap_clr_omode (struct soap *soap, soap_mode output_mode) |
Clear output soap_mode flags of the given soap context. More... | |
| struct soap * | soap_copy (struct soap *soap) |
Allocate and initialize a new soap context as a copy of the given soap context. More... | |
| void | soap_copy_context (struct soap *soap_destination, struct soap *soap_source) |
Copy a given soap context to an uninitialized destination soap context. More... | |
| void | soap_copy_stream (struct soap *soap_destination, struct soap *soap_source) |
Copy the input/output stream state of the given soap context to another context. More... | |
| void | soap_free_stream (struct soap *soap) |
Free the input/output stream state of the given soap context. More... | |
| void | soap_free (struct soap *soap) |
Finalize and free the given soap context from unmanaged heap memory. More... | |
| void | soap_done (struct soap *soap) |
Finalize the given soap context, i.e. when the soap context is stack allocated, automatically invoked in C++ by the soap destructor on the soap context to delete. More... | |
| void * | soap_malloc (struct soap *soap, size_t len) |
Allocate a block of heap memory managed by the specified soap context. More... | |
| char * | soap_strdup (struct soap *soap, const char *string) |
| Copy a string to managed memory. More... | |
| wchar_t * | soap_wstrdup (struct soap *soap, const wchar_t *string) |
| Copy a wide string to managed memory. More... | |
| int | soap_unlink (struct soap *soap, const void *ptr) |
Unlink a block of heap memory managed by the specified soap context, to release the memory explicitly later. More... | |
| void | soap_destroy (struct soap *soap) |
Delete all dynamically-allocated C++ objects managed by the specified soap context. More... | |
| void | soap_dealloc (struct soap *soap, void *ptr) |
Explicitly dealllocates a block of managed memory that is managed by the specified soap context and release the free memory back to the heap. More... | |
| void | soap_free_temp (struct soap *soap) |
| Delete temporary data. More... | |
| void | soap_end (struct soap *soap) |
Delete all data from heap memory managed by the specified soap context and release the freed memory back to the heap. More... | |
| void | soap_delegate_deletion (struct soap *soap, struct soap *soap_to) |
Delegate the deletion of all managed objects and data from the specified soap context to another soap context. More... | |
| void | soap_set_version (struct soap *soap, short version) |
| Set SOAP version (0 = no SOAP, 1 = SOAP 1.1, 2 = SOAP 1.2) More... | |
This module defines the soap context structure with the engine state and functions to allocate, initialize, copy and delete contexts.
| typedef char* _QName |
A built-in string type containing normalized QName contents.
| typedef char* _XML |
A built-in string type containing literal XML content in UTF-8 format.
Allocate and initialize a new soap context as a copy of the given soap context.
This function allocates a new context and copies the state of the specified context except for the heap-allocated data managed by the specified context. After the copy the contexts do not share any data and can therefore be used by separate threads without requiring synchronization or mutex locking.
soapcpp2 -j option -j or option -i have an internal soap context that is either a base class (option -i) or a member variable pointing to a soap context (option -j). For convenience, use the copy member function instead of soap_copy and delete the copied instance with delete. For example: soap_copy_context, soap_copy_stream, soap_free_stream, soap_delegate_deletion, soap_destroy, soap_end, soap_free.soap context or NULL when out of heap memory | soap | soap context to copy |
Copy a given soap context to an uninitialized destination soap context.
This function copies the state of the specified context to another uninitialized context (i.e. overriding it). If the destination context is initialized or active then call soap_done first to clean it up before overriding it. The entire state is copied except for the heap-allocated data managed by the specified context. After the copy the contexts do not share any data and can therefore be used by separate threads without requiring synchronization or mutex locking.
Copy the input/output stream state of the given soap context to another context.
This function copies the input/output state of the specified source context to the specified destination context. Both contexts will share the same input/output streams , i.e. soap::is, soap::os, soap::socket, soap::recvfd and soap::sendfd are shared and the current message buffer soap::buf content is copied. The destination context is set to the source context soap_mode flags and timeouts. To move the input/output state of one context to another, use this function and then call soap_free_stream on the source context to clear its input/output state.
soap_free_stream. | void soap_dealloc | ( | struct soap * | soap, |
| void * | ptr | ||
| ) |
Explicitly dealllocates a block of managed memory that is managed by the specified soap context and release the free memory back to the heap.
This function deallocates a managed block of memory from the managing soap context and releases the free memory back to the heap. This frees data allocated with soap_malloc and C++ objects allocated and instantiated with the soap_new_T functions. Normally this function should not be used to individually deallocate managed objects and data but rather soap_destroy and soap_end should be used to deallocate all objects and data managed by the context, which is much more efficient.
| soap | soap context |
| ptr | pointer to the block of managed heap memory to deallocate |
Delegate the deletion of all managed objects and data from the specified soap context to another soap context.
This function moves all dynamically-allocated data managed by the specified soap context to the target context soap_to for deletion by the target context using soap_destroy and soap_end.
soap_copy, soap_copy_context, soap_destroy, soap_end. | void soap_destroy | ( | struct soap * | soap | ) |
Delete all dynamically-allocated C++ objects managed by the specified soap context.
This function deletes all dynamically-allocated C++ objects managed by the specified soap context, i.e. data allocated with soap_new_T calls. This call should be followed by soap_end to delete all other dynamically-allocated data managed by the soap context. Or just invoke soap::destroy to delete objects and data and release the freed memory back to the heap.
soapcpp2 -j option -j or option -i have an internal soap context that is either a base class (option -i) or a member variable pointing to a soap context (option -j). For convenience, use the destroy member function instead of soap_destroy and soap_end. For example: soap_malloc, soap_end, soap::destroy. | soap | soap context |
| void soap_done | ( | struct soap * | soap | ) |
Finalize the given soap context, i.e. when the soap context is stack allocated, automatically invoked in C++ by the soap destructor on the soap context to delete.
This function finalizes the specified context. This function does not free memory managed by the context. To free memory managed by the context use soap_destroy and soap_end, or soap::destroy to call both.
soap_free, soap_destroy, soap_end, soap::destroy. | soap | soap context to finalize |
| void soap_end | ( | struct soap * | soap | ) |
Delete all data from heap memory managed by the specified soap context and release the freed memory back to the heap.
This function deletes all dynamically-allocated data managed by the specified soap context, i.e. data allocated with soap_malloc. This call suffices to delete all managed data from C applications and release the freed memory back to the heap. C++ applications however should call soap_destroy first before soap_end or just invoke soap::destroy (or C++ proxy and service class member function destroy) to delete objects and data and release the freed memory back to the heap.
soapcpp2 -j option -j or option -i have an internal soap context that is either a base class (option -i) or a member variable pointing to a soap context (option -j). For convenience, use the destroy member function instead of soap_destroy and soap_end. For example: soap_malloc, soap_destroy, soap::destroy. | soap | soap context |
| void soap_free | ( | struct soap * | soap | ) |
Finalize and free the given soap context from unmanaged heap memory.
This function finalizes and frees the specified context. The finalization is done with soap_done before releasing its memory. This function does not free memory managed by the context. To free memory managed by the context use soap_destroy and soap_end, or soap::destroy to call both.
soapcpp2 -j option -j or option -i have an internal soap context that is either a base class (option -i) or a member variable pointing to a soap context (option -j). The C++ proxy and service classes allocate and deallocate this context, which means that soap_new and soap_free are not required. For example: soap_new, soap_new1, soap_new2, soap_done, soap_destroy, soap_end, soap::destroy. | soap | soap context to free |
| void soap_free_stream | ( | struct soap * | soap | ) |
Free the input/output stream state of the given soap context.
soap_copy_stream. | soap | soap context |
| void soap_free_temp | ( | struct soap * | soap | ) |
Delete temporary data.
This function deallocates temporary data such as buffers and hash tables but leaves deserialized managed data intact.
| soap | soap context |
| void soap_init | ( | struct soap * | soap | ) |
Initialize a stack-allocated soap context.
This function initializes a context.
The context can be re-initialized for reuse after soap_done by calling soap_init.
soap_done. To change the input/output mode flags, use soap_set_mode and soap_clr_mode.soap_init1, soap_new, soap_copy, soap_destroy, soap_end, soap_done. | soap | soap context to initialize |
Initialize a stack-allocated soap context with input and output soap_mode flags.
This function initializes a context with the specified input and output soap_mode flags.
The context can be re-initialized for reuse after soap_done by calling soap_init.
soap_done. To change the input/output mode flags, use soap_set_mode and soap_clr_mode.Initialize a stack-allocated soap context with input and output soap_mode flags.
This function initializes a context with the specified input and output soap_mode flags.
soap_done. To change the input/output mode flags, use soap_set_mode and soap_clr_mode.| void* soap_malloc | ( | struct soap * | soap, |
| size_t | len | ||
| ) |
Allocate a block of heap memory managed by the specified soap context.
This function allocates a block of memory from the heap managed by the specified soap context. All such blocks allocated are deleted with a single call to soap_end. Returns a pointer to the allocated block of memory or NULL when out of memory without setting soap::error.
soap_new_T functions for all serialiable types T. The soap_new_T functions allocate and default initializes the type T or an array of items of type T. Recommended is to use these more powerful soap_new_T functions instead of soap_malloc. For example: soap_default_T functions to default initialize the type T. For example: soap_default method instead of the soap_default_T function.soap_strdup, soap_wstrdup, soap_unlink, soap_delegate_deletion, soap_destroy, soap_end, and the C and C++ XML data bindings documentation.| soap | soap context |
| len | length of the block to allocate in number of bytes |
| struct soap* soap_new | ( | ) |
Allocate and initialize a new soap context.
This function allocates and initializes a new context.
There is no need to call soap_init to initialize the context allocated with soap_new, since soap_new initializes the allocated context. To change the input/output mode flags, use soap_set_mode and soap_clr_mode.
soapcpp2 -j option -j or option -i have an internal soap context that is either a base class (option -i) or a member variable pointing to a soap context (option -j). The C++ proxy and service classes allocate and deallocate this context, which means that soap_new and soap_free are not required. For example: soap context or NULL when out of heap memory Allocate and initialize a new soap context with input and output soap_mode flags.
This function allocates and initializes a new context with the specified input and output soap_mode flags.
soap_init to initialize the context allocated with soap_new1. To change the input/output mode flags, use soap_set_mode and soap_clr_mode.soap context or NULL when out of heap memory | input_and_output_mode | input and output soap_mode flags |
Allocate and initialize a new soap context with separate input and output soap_mode flags.
This function allocates and initializes a new context with the specified input and output soap_mode flags. The separation of input and output mode flags is only useful for the SOAP_XML_TREE flag that affects both input and output behaviors.
soap context or NULL when out of heap memory | void soap_set_version | ( | struct soap * | soap, |
| short | version | ||
| ) |
Set SOAP version (0 = no SOAP, 1 = SOAP 1.1, 2 = SOAP 1.2)
This function sets (or overrides) the SOAP version to use when sending a message. This function can be used prior to a client-side call to select the SOAP version to use for the request message (assuming the generated code does not fix the version already) or in a service operation to select the SOAP version of the response message. The response message of a service operation normally uses the same SOAP version of the SOAP request message received.
| soap | soap contexr |
| version | SOAP version (0 = REST (no SOAP), 1 = SOAP 1.1, 2 = SOAP 1.2) |
| char* soap_strdup | ( | struct soap * | soap, |
| const char * | string | ||
| ) |
Copy a string to managed memory.
This function copies the specified wide string to memory managed by the specified context. Returns a copy of the string or NULL when the specified string is NULL or when the function failed to allocate memory.
soap_malloc, soap_wstrdup, soap_unlink, soap_delegate_deletion, soap_destroy, soap_end.| soap | soap context |
| string | string to copy to managed memory |
| int soap_unlink | ( | struct soap * | soap, |
| const void * | ptr | ||
| ) |
Unlink a block of heap memory managed by the specified soap context, to release the memory explicitly later.
This function removes a managed block of memory from the managing soap context. This memory is not released but rather should be released explicitly later by the application logic using free or delete. Returns SOAP_OK when successful or SOAP_ERR when the block is not managed by the specified context.
| soap | soap context |
| ptr | pointer to the block of managed heap memory to unlink |
| wchar_t* soap_wstrdup | ( | struct soap * | soap, |
| const wchar_t * | string | ||
| ) |
Copy a wide string to managed memory.
This function copies the specified wide string to managed memory. Returns a copy of the wide string or NULL when the specified wide string is NULL or when the function failed to allocate memory.
soap_malloc, soap_strdup, soap_unlink, soap_delegate_deletion, soap_destroy, soap_end.| soap | soap context |
| string | wide string to copy to managed memory or NULL |