|  | Home | Documentation | Context with engine state updated Sat Apr 25 2026 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Classes | Typedefs | Functions
Context with engine state

This module describes the `soap` context structure with the engine state (see its info page) with API 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 allocated and managed by the specified `soap` context, this block of heap memory should be released explicitly later by the application. More...
void | soap_destroy (struct soap *soap)
| Delete all dynamically-allocated C++ objects managed by the specified `soap` context (deprecated since 2.8.140 and greater, `soap_end` also deletes managed C++ objects) More...
int | 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...
int | soap_delete (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 is idential to the `soap_dealloc` function. More...
void | soap_free_temp (struct soap *soap)
| Delete temporary data. More...
int | 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...

## Detailed Description

This module describes the `soap` context structure with the engine state (see its info page) with API functions to allocate, initialize, copy, and delete contexts.

View the context structure with the engine state (see its info page) for more details on the context structure member variables. The member variables used in this page and elsewhere in the documentation are hyperlinked. Most structure member variables may be changed directly as is documented with illustrative examples.

## Typedef Documentation

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.

## Function Documentation

void soap_clr_imode | ( | struct soap * | soap,
|  | soap_mode | input_mode
| ) |  |

Clear input `soap_mode` flags of the given `soap` context.

Parameters

  soap | `soap` context
  input_mode | input `soap_mode` flags

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.

Parameters

  soap | `soap` context
  input_and_output_mode | input and output `soap_mode` flags

void soap_clr_omode | ( | struct soap * | soap,
|  | soap_mode | output_mode
| ) |  |

Clear output `soap_mode` flags of the given `soap` context.

Parameters

  soap | `soap` context
  output_mode | output `soap_mode` flags

struct soap* soap_copy | ( | struct soap * | soap | ) |

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 source context, except heap-allocated data managed by the specified source context, such as deserialized data. To delegate and move managed data from one context to another, use `soap_delegate_deletion`. Data is deleted with `soap_destroy` and `soap_end` in that order, then `soap_free` to delete the allocated context. After the copy the contexts do not share any data and can therefore be safely used by separate threads without requiring synchronization or mutex locking.

Note
  C++ proxy and service classes generated by `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:
  #include "soapexampleService.h" // generated by soapcpp2 option -j
  int main()
  {
  exampleService service(SOAP_XML_INDENT);
  service.soap->bind_flags = SO_REUSEADDR; // immediate port reuse
  service.soap->accept_timeout = 3600; // let soap_accept time out after 1 hour
  ... // further initialize service.soap
  if (soap_valid_socket(service.bind(NULL, PORTNUM, BACKLOG)))
  {
  while (1)
  {
  if (soap_valid_socket(service.accept()))
  {
  THREAD_TYPE tid;
  exampleService *tservice = service.copy();
  if (!tservice)
  soap_closesock(service.soap);
  else
  while (THREAD_CREATE(&tid, (void*(*)(void*))&process_request, (void*)tservice))
  sleep(1); // failed, try again
  }
  else if (service.soap->errnum) // accept failed, try again after 1 second
  {
  service.soap_print_fault(stderr);
  sleep(1);
  }
  else // accept timed out, quit looping
  {
  break;
  }
  service.destroy();
  }
  }
  }
  void *process_request(exampleService *service)
  {
  THREAD_DETACH(THREAD_ID);
  service.serve();
  service.destroy();
  delete service;
  return NULL;
  }

Example:

#include "soapH.h"
#include "plugin/threads.h"
int main()
{
struct soap *soap = soap_new1(SOAP_XML_INDENT);
soap->bind_flags = SO_REUSEADDR; // immediate port reuse
soap->accept_timeout = 3600; // exit loop when no request arrives in one hour
soap->send_timeout = soap_recv_timeout = 5; // 5 seconds max socket stall time (unlimited by default)
soap->transfer_timeout = 30; // 30 seconds max message transfer time (unlimited by default)
soap->recv_maxlength = 1048576; // limit messages received to 1MB (2GB by default)
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
{
while (1)
{
if (soap_valid_socket(soap_accept(soap)))
{
THREAD_TYPE tid;
struct soap *tsoap = soap_copy(soap);
if (!tsoap)
soap_force_closesock(soap);
else
while (THREAD_CREATE(&tid, (void*(*)(void*))&process_request, (void*)tsoap))
sleep(1); // failed, try again
}
else // accept failed, try again after 1 second
{
soap_print_fault(soap, stderr);
sleep(1);
}
else // accept timed out, quit looping
{
break;
}
soap_destroy(soap);
soap_end(soap);
}
}
soap_free(soap);
}
void *process_request(struct soap *soap)
{
THREAD_DETACH(THREAD_ID);
soap_serve(soap);
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
return NULL;
}

See also
  `soap_copy_context`, `soap_copy_stream`, `soap_free_stream`, `soap_delegate_deletion`, `soap_destroy`, `soap_end`, `soap_free`.

Returns
  pointer to allocated and initialized `soap` context or NULL when out of heap memory

Parameters

  soap | `soap` context to copy

void soap_copy_context | ( | struct soap * | soap_destination,
|  | struct soap * | soap_source
| ) |  |

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.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // send and receive messages etc.
struct soap temp;
soap_copy_context(&temp, soap);
...

See also
  `soap_copy`, `soap_copy_stream`, `soap_free_stream`, `soap_delegate_deletion`, `soap_destroy`, `soap_end`, `soap_free`.

Parameters

  soap_destination | destination `soap` context to initialize
  soap_source | source `soap` context to copy

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.

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.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
struct soap *temp = soap_new();
... // send and receive messages etc.
// move the input/output state to another context
soap_copy_stream(temp, soap);
soap_free_stream(soap);
soap_closesock(soap); // has no effect
... // send and receive messages etc.
soap_closesock(temp); // closes socket, if open

See also
  `soap_free_stream`.

Parameters

  soap_destination | destination `soap` context
  soap_source | source `soap` context

int 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.

Returns
  `SOAP_OK` when successful or `SOAP_MOE` when a memory error is detected during deallocation

Parameters

  soap | `soap` context
  ptr | pointer to the block of managed heap memory to deallocate

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.

This function delegates management of 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` in that order. Any pointers to the data remain valid (until deletion later) and can be safely used by an application. Only the management of the data is moved to the target context and is combined with any existing managed data.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
struct soap *temp = soap_new(); // temp context to manage data
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
{
soap_print_fault(soap, stderr);
}
else
{
// success, response contains deserialized data
soap_delegate_deletion(soap, temp); // deserialized data is managed by temp context
}
soap_destroy(soap); // clean up 'soap' context
soap_end(soap); // clean up 'soap' context
... // use deserialized data managed by 'temp' context, reuse 'soap' context as needed
soap_destroy(temp); // clean up 'temp' context, deletes deserialized data
soap_end(temp); // clean up 'temp' context, deletes deserialized data
soap_free(temp);
soap_free(soap);

See also
  `soap_copy`, `soap_copy_context`, `soap_destroy`, `soap_end`.

Parameters

  soap | source `soap` context
  soap_to | target `soap` context

int soap_delete | ( | 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 is idential to the `soap_dealloc` function.

Returns
  `SOAP_OK` when successful or `SOAP_MOE` when a memory error is detected during deallocation

Parameters

  soap | `soap` context
  ptr | pointer to the block of managed heap memory to deallocate

void soap_destroy | ( | struct soap * | soap | ) |

Delete all dynamically-allocated C++ objects managed by the specified `soap` context (deprecated since 2.8.140 and greater, `soap_end` also deletes managed C++ objects)

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.

Note
  C++ proxy and service classes generated by `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:
  #include "soapexampleProxy.h"
  exampleProxy proxy(SOAP_XML_INDENT);
  ... // use proxy or proxy.soap (option -j)
  proxy.destroy(); // delete managed C++ objects and memory
  #include "soapexampleService.h"
  exampleService service(SOAP_XML_INDENT);
  ... // use service or service.soap (option -j)
  service.destroy(); // delete managed C++ objects and memory

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects (deprecated since 2.8.140 and greater, `::soap_end` also deletes managed C++ objects)
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

See also
  `soap_malloc`, `soap_end`, `soap::destroy`.

Parameters

  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.

Example:

#include "soapH.h"
struct soap soap;
soap_init(&soap);
... // send and receive messages etc.
soap_destroy(&soap);
soap_end(&soap);
soap_done(&soap);

See also
  `soap_free`, `soap_destroy`, `soap_end`, `soap::destroy`.

Parameters

  soap | `soap` context to finalize

int 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.

Normally returns `SOAP_OK`. Returns `SOAP_MOE` when a memory error is detected, which should never happen; note that memory leaks, double frees, and overruns are always reported by `soap_done` when compiled with `DEBUG` or `SOAP_MEM_DEBUG`.

Note
  C++ proxy and service classes generated by `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:
  #include "soapexampleProxy.h"
  exampleProxy proxy(SOAP_XML_INDENT);
  ... // use proxy or proxy.soap (option -j)
  proxy.destroy(); // delete managed C++ objects and memory
  #include "soapexampleService.h"
  exampleService service(SOAP_XML_INDENT);
  ... // use service or service.soap (option -j)
  service.destroy(); // delete managed C++ objects and memory

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects (deprecated since 2.8.140 and greater, `::soap_end` also deletes managed C++ objects)
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

See also
  `soap_malloc`, `soap_destroy`.

Returns
  `SOAP_OK` when successful or `SOAP_MOE` when a memory error is detected

Parameters

  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.

Note
  C++ proxy and service classes generated by `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:
  #include "soapexampleProxy.h"
  exampleProxy proxy(SOAP_XML_INDENT);
  ... // use proxy or proxy.soap (option -j)
  proxy.destroy(); // delete managed C++ objects and memory
  #include "soapexampleService.h"
  exampleService service(SOAP_XML_INDENT);
  ... // use service or service.soap (option -j)
  service.destroy(); // delete managed C++ objects and memory

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // send and receive messages etc.
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also
  `soap_new`, `soap_new1`, `soap_new2`, `soap_done`, `soap_destroy`, `soap_end`, `soap::destroy`.

Parameters

  soap | `soap` context to free

void soap_free_stream | ( | struct soap * | soap | ) |

Free the input/output stream state of the given `soap` context.

See also
  `soap_copy_stream`.

Parameters

  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.

Parameters

  soap | `soap` context

void soap_init | ( | struct soap * | soap | ) |

Initialize a stack-allocated `soap` context.

This function initializes a context.

Examples:

#include "soapH.h"
struct soap soap;
soap_init(&soap);
... // send and receive messages etc.
soap_destroy(&soap); // delete managed C++ objects
soap_end(s&oap); // delete managed memory
soap_done(&soap); // finalize the context

The context can be re-initialized for reuse after `soap_done` by calling `soap_init`.

Note
  Initialization should be done at most once before calling `soap_done`. To change the input/output mode flags, use `soap_set_mode` and `soap_clr_mode`.

See also
  `soap_init1`, `soap_new`, `soap_copy`, `soap_destroy`, `soap_end`, `soap_done`.

Parameters

  soap | `soap` context to initialize

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.

This function initializes a context with the specified input and output `soap_mode` flags.

Examples:

#include "soapH.h"
struct soap soap;
soap_init1(&soap, SOAP_XML_INDENT);
... // send and receive messages etc.
soap_destroy(&soap); // delete managed C++ objects
soap_end(s&oap); // delete managed memory
soap_done(&soap); // finalize the context

The context can be re-initialized for reuse after `soap_done` by calling `soap_init`.

Note
  Initialization should be done at most once before calling `soap_done`. To change the input/output mode flags, use `soap_set_mode` and `soap_clr_mode`.

See also
  `soap_init`, `soap_new`, `soap_copy`, `soap_destroy`, `soap_end`, `soap_done`.

Parameters

  soap | `soap` context to initialize
  input_and_output_mode | input and output `soap_mode` flags

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.

This function initializes a context with the specified input and output `soap_mode` flags.

Note
  Initialization should be done at most once before calling `soap_done`. To change the input/output mode flags, use `soap_set_mode` and `soap_clr_mode`.

See also
  `soap_init`, `soap_new`, `soap_copy`, `soap_destroy`, `soap_end`, `soap_done`.

Parameters

  soap | `soap` context to initialize
  input_mode | input `soap_mode` flags
  output_mode | output `soap_mode` flags

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`.

Note
  The soapcpp2 tool generates `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:
  #include "soapH.h"
  struct soap *soap = soap_new();
  struct ns__someElement *data = soap_new_ns__someElement(soap); // allocate managed object
  struct ns__someElement *array = soap_new_ns__someElement(soap, 100); // allocate array of 100 managed objects
  ... // send and receive messages etc.
  soap_destroy(soap); // deletes data, array, and other managed C++ objects
  soap_end(soap); // delete managed memory
  soap_free(soap); // free the context
  The soapcpp2 tool also generates `soap_default_T` functions to default initialize the type `T`. For example:
  #include "soapH.h"
  struct soap *soap = soap_new();
  struct ns__someElement data;
  soap_default_ns__someElement(soap, &data); // default initializes all public members
  ...
  but objects of classes should use their `soap_default` method instead of the `soap_default_T` function.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
char *s = (char*)soap_malloc(soap, 80); // allocate 80 bytes of memory managed by the context
strcpy(s, "Hello"); // copy a string into it
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

See also
  `soap_strdup`, `soap_wstrdup`, `soap_unlink`, `soap_delegate_deletion`, `soap_destroy`, `soap_end`, and the C and C++ XML data bindings documentation.

Returns
  pointer to the allocated block of memory or NULL on failure to allocate (out of memory)

Parameters

  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`.

Note
  C++ proxy and service classes generated by `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:
  #include "soapexampleProxy.h"
  exampleProxy proxy(SOAP_XML_INDENT);
  ... // use proxy or proxy.soap (option -j)
  proxy.destroy(); // delete managed C++ objects and memory
  #include "soapexampleService.h"
  exampleService service(SOAP_XML_INDENT);
  ... // use service or service.soap (option -j)
  service.destroy(); // delete managed C++ objects and memory

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

See also
  `soap_new1`, `soap_new2`, `soap_copy`, `soap_destroy`, `soap_end`, `soap_free`.

Returns
  pointer to allocated and initialized `soap` context or NULL when out of heap memory

struct soap* soap_new1 | ( | soap_mode | input_and_output_mode | ) |

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.

Example:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_XML_INDENT);
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

Note
  There is no need to call `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`.

See also
  `soap_new`, `soap_new2`, `soap_copy`, `soap_destroy`, `soap_end`, `soap_free`.

Returns
  pointer to allocated and initialized `soap` context or NULL when out of heap memory

Parameters

  input_and_output_mode | input and output `soap_mode` flags

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.

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.

Note
  There is no need to call `soap_init` to initialize the context allocated with `soap_new2`.

See also
  `soap_new`, `soap_new1`, `soap_copy`, `soap_destroy`, `soap_end`, `soap_free`.

Returns
  pointer to allocated and initialized `soap` context or NULL when out of heap memory

Parameters

  input_mode | input `soap_mode` flags
  output_mode | output `soap_mode` flags

void soap_set_imode | ( | struct soap * | soap,
|  | soap_mode | input_mode
| ) |  |

Set input `soap_mode` flags of the given `soap` context.

Parameters

  soap | `soap` context
  input_mode | input `soap_mode` flags

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.

Parameters

  soap | `soap` context
  input_and_output_mode | input and output `soap_mode` flags

void soap_set_omode | ( | struct soap * | soap,
|  | soap_mode | output_mode
| ) |  |

Set output `soap_mode` flags of the given `soap` context.

Parameters

  soap | `soap` context
  output_mode | output `soap_mode` flags

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.

Parameters

  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.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
// allocate and assign a string in memory managed by the context
char *s = soap_strdup(soap, "Hello");
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

See also
  `soap_malloc`, `soap_wstrdup`, `soap_unlink`, `soap_delegate_deletion`, `soap_destroy`, `soap_end`.

Returns
  copy of string or NULL when the specified string is NULL or on failure to allocate (out of memory)

Parameters

  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 allocated and managed by the specified `soap` context, this block of heap memory should be released explicitly later by the application.

This function unlinks a managed block of memory from the managing `soap` context. This block of memory should be released explicitly later by the application logic by using `free` for regular C data types or by using `delete` for C++ objects. Returns `SOAP_OK` when successful or `SOAP_ERR` when the block is not managed by the specified context. This operation is time consuming prior to version 2.8.140 (since version 2.8.140 implements an updated memory management approach.)

Returns
  `SOAP_OK` when successful or `SOAP_ERR` when the block is not managed by the specified context

Parameters

  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.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
// allocate and assign a wide string in memory managed by the context
wchar_t *s = soap_wstrdup(soap, L"Hello");
... // send and receive messages etc.
soap_destroy(soap); // delete managed C++ objects
soap_end(soap); // delete managed memory
soap_free(soap); // free the context

See also
  `soap_malloc`, `soap_strdup`, `soap_unlink`, `soap_delegate_deletion`, `soap_destroy`, `soap_end`.

Returns
  copy of wide string or NULL when the specified wide string is NULL or on failure to allocate (out of memory)

Parameters

  soap | `soap` context
  string | wide string to copy to managed memory or NULL