|  | Home | Documentation | soap Struct Reference updated Mon Mar 24 2025 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

- Class List
- Class Members

Public Member Functions | Public Attributes | List of all members
soap Struct Reference
Context with engine state

Context with the engine state. More...

## Public Member Functions
| soap ()
| Construct a `soap` context (C++ only, in C use `soap_new` or `soap_init`) More...
| soap (soap_mode input_and_output_mode)
| Construct a `soap` context with the specified input and output `soap_mode` flags (C++ only, in C use `soap_new1` or `soap_init1`)) More...
| soap (soap_mode input_mode, soap_mode output_mode)
| Construct a `soap` context with the specified input and output `soap_mode` flags (C++ only, in C use `soap_new2` or `soap_init2`)) More...
| soap (const struct soap &)
| Copy constructor (C++ only, in C use `soap_copy` or `soap_copy_context`) More...
struct soap & | operator= (const struct soap &)
| Assignment constructor (C++ only, in C use `soap_copy` or `soap_copy_context`) More...
void | destroy ()
| Delete all dynamically-allocated objects and data managed by this `soap` context (C++ only, in C use `soap_end`) More...
| ~soap ()
| Finalize and delete the `soap` context by finalizing with soap_done(this) (C++ only, in C use `soap_free` or `soap_done`) More...

## Public Attributes
soap_mode | imode
| The `soap` context input `soap_mode` flags that are set at context initialization and set or cleared with `soap_set_imode` or `soap_clr_imode`, respectively. More...
soap_mode | omode
| The `soap` context output `soap_mode` flags that are set at context initialization and set or cleared with `soap_set_omode` or `soap_clr_omode`, respectively. More...
SSL_CTX * | ctx
| OpenSSL context pointer. More...
short | version
| SOAP version (0 = no SOAP, 1 = SOAP 1.1, 2 = SOAP 1.2) More...
const char * | encodingStyle
| User-definable `SOAP-ENV:encodingStyle` URI value. More...
const char * | actor
| User-definable `SOAP-ENV:actor` (SOAP 1.1) or `SOAP-ENV:role` (SOAP 1.2) attribute value of all `SOAP-ENV:mustUnderstand` attributed header elements. More...
const char * | lang
| User-definable `xml:lang` attribute value of `SOAP-ENV:Text` to output the SOAP Fault string/reason (the value is `en` by default) More...
int | max_keep_alive
| User-definable maximum number of keep-alive message exchanges per connection (the value is `SOAP_MAXKEEPALIVE` by default) More...
int | keep_alive
| HTTP keep-alive flag (try to enable when -1, disabled when 0) and counter (enabled when >0) More...
const char * | c14ninclude
| User-definable string to control the XML namespace prefixes that are subject to XML canonicalization with the `SOAP_XML_CANONICAL` output mode flag, specified by space-separated prefixes in the string, or `*` to specify that all prefixes are inclusive, or NULL when unused. More...
const char * | c14nexclude
| User-definable string to control the XML namespace prefixes that are subject to XML canonicalization with `SOAP_XML_CANONICAL` output mode flag, specified by space-separated prefixes in the string, or NULL when unused. More...
int | status
| The `soap` context HTTP status code received at the client side (100 to 599), HTTP header method received at the server side (`SOAP_POST`, `SOAP_PATCH`, `SOAP_GET`, `SOAP_PUT`, `SOAP_DEL`, `SOAP_HEAD`, `SOAP_OPTIONS`), or the HTTP method to use for sending a message with `soap_connect_command` or with `soap_response` (`SOAP_POST`, `SOAP_POST_FILE`, `SOAP_PATCH`, `SOAP_GET`, `SOAP_PUT`, `SOAP_PUT`, `SOAP_DEL`, `SOAP_CONNECT`, `SOAP_HEAD`, `SOAP_OPTIONS`) More...
int | error
| The `soap` context `soap_status` (int) error code of the last operation or `SOAP_OK` (zero) More...
int | errnum
| The `errno` value of the last failed IO operation. More...
struct SOAP_ENV__Header * | header
| The `soap::header` points to a `SOAP_ENV__Header` structure with the SOAP Header that was received or that can be populated by the user to be sent, or NULL when no SOAP Header is present. More...
struct SOAP_ENV__Fault * | fault
| The `soap::fault` points to a `SOAP_ENV__Fault` structure with the SOAP Fault that was received or that can be populated by the user to be sent, or NULL when no SOAP Fault is present. More...
void * | user
| User-definable variable that may point to user-specified data of any type to pass the data through to callbacks and plugins. More...
short | mustUnderstand
| The `soap::mustUnderstand` flag is set when a SOAP Header element carries a `SOAP-ENV:mustUnderstand` attribute that is true. More...
short | null
| The `soap::null` flag is set when an element carries a `xsi:nil` attribute that is true. More...
short | body
| The `soap::body` flag is set when an element has element content during XML parsing or when a HTTP message has a body when parsing an HTTP header. More...
const char * | prolog
| User-definable XML declaration prolog (`<?xml version="1.0" encoding="UTF-8"?>` by default) More...
const char * | cookie_domain
| User-definable string that specifies the HTTP cookie domain of the running server. More...
const char * | cookie_path
| User-definable string that specifies the HTTP cookie path of the running server. More...
int | cookie_max
| User-definable maximum number of active cookies allowed to be set with `soap_set_cookie` before cookie memory is reused (the value is 32 by default) More...
struct soap_cookie * | cookies
| The cookie store is a linked list of cookies. More...
const char * | http_content
| String with HTTP content type header value received, can also be assigned to specify a content type header for `soap_connect_command` with `SOAP_POST_FILE`, `SOAP_PUT` and `SOAP_PATCH` or for `soap_response` with `SOAP_FILE` or for `soap_PUT`, `soap_PATCH`, `soap_POST`. The `soap::http_content` string is reset to NULL after each HTTP invocation and has to be set again when required. More...
const char * | http_extra_header
| User-definable string that specifies an extra HTTP header or multiple HTTP headers when separated by CRLF in the specified string, to include in the next HTTP request (client side) or to include with the HTTP response (server side). The specified headre or headers are checked by the engine to conform to HTTP header formats or otherwise will be ignored and not output. More...
SOAP_SOCKET | master
| The socket set by `soap_bind` (or the C++ service class `bind` method) to serve as the master socket bound to a specified port, or `SOAP_INVALID_SOCKET` when unassigned. More...
SOAP_SOCKET | socket
| The socket set by `soap_accept` (or the C++ service class `accept` method) or `soap_connect` or `soap_connect_command` (or the C++ proxy methods) when successful, or `SOAP_INVALID_SOCKET` when unassigned. More...
int | recvfd
| The file descriptor to read data from when no socket communications are set (`soap::socket` == `SOAP_INVALID_SOCKET`) and `soap:is` == NULL, default value is 0 (stdin) More...
int | sendfd
| The file descriptor to write data to when no socket communications are set (`soap::socket` == `SOAP_INVALID_SOCKET`) and `soap:os` == NULL, default value is 1 (stdout) More...
SOAP_SOURCE * | is
| The source to read data from when non-NULL, which in C++ is a `std::istream` object and in C is a 0-terminated string to be read, default value is NULL. More...
SOAP_SINK * | os
| The sink to write data to when non-NULL, which in C++ is a `std::ostream` object and in C is a pointer to a `char*` string variable that will be set to point to a managed 0-terminated string with the data, default value is NULL. More...
ULONG64 | recv_maxlength
| User-definable maximum message length that is permitted to be received, zero means unlimited (the value is 2GB by default) More...
int | transfer_timeout
| User-definable timeout to send or receive an entire message, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default) More...
int | recv_timeout
| User-definable timeout to receive a packet of data, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default) More...
int | send_timeout
| User-definable timeout to send a packet of data, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default) More...
int | accept_timeout
| User-definable timeout when waiting to accept a request from a client at the server-side with `soap_accept` (or the C++ service class `accept` method), positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default) More...
int | connect_timeout
| User-definable timeout when waiting to connect to a server at the client-side, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default) More...
int | connect_retry
| User-definable number of retries to attempt at the client side when connecting to a server fails with `SOAP_TCP_ERROR`, using exponential backoff delays between reconnects, maxed at 32 seconds: 1, 2, 4, 8, 16, 32, 32, 32, ... seconds for retry values 1 to 8 respectively (the retry value is 0 by default, meaning no retry) More...
unsigned int | maxlevel
| User-definable maximum XML and JSON nesting level permitted, initially set to `SOAP_MAXLEVEL` (the value is 10000 by default) More...
long | maxlength
| User-definable maximum string length parsed from XML and JSON, initially set to `SOAP_MAXLENGTH`, zero or negative means unlimited (0 by default) More...
size_t | maxoccurs
| User-definable maximum array and container size (maximum item occurrence constraint) as parsed from XML and JSON, except when specifie XML schema validation constraints permit greater sizes, initially set to `SOAP_MAXOCCURS` (the value is 100000 by default) More...
int | socket_flags
| User-definable socket `send` and `recv` flags, for example assign `MSG_NOSIGNAL` to disable sigpipe (the value is 0 by default) More...
int | connect_flags
| User-definable `setsockopt` level `SOL_SOCKET` flags when connecting `soap::socket` to a server (the value is 0 by default) More...
int | bind_flags
| User-definable `setsockopt` level `SOL_SOCKET` flags when binding `soap::master` socket (the value is 0 by default) More...
short | bind_inet6
| User-definable flag, when nonzero uses `AF_INET6` instead of `PF_UNSPEC` when binding the `soap::master` socket in `soap_bind` (or the C++ service class `bind` method), to remap IPv4 to IPv6 addresses, meaningful only when used with `WITH_IPV6` More...
short | bind_v6only
| User-definable flag, when nonzero enables `IPPROTO_IPV6` `setsockopt` `IPV6_V6ONLY` when binding the `soap::master` socket with `soap_bind` (or the C++ service class `bind` method), meaningful only when used with `WITH_IPV6` More...
int | accept_flags
| User-definable `setsockopt` level `SOL_SOCKET` flags (0 by default), when nonzero sets the `soap::socket` flags when accepting a request with `soap_accept` (or the C++ service class `accept` method) More...
unsigned short | linger_time
| User-definable linger time value, requires the `SO_LINGER` `setsockopt` flag value to be assigned to `soap::socket_flags` More...
int | rcvbuf
| User-definable value to set `SO_RCVBUF` `setsockopt` (the value is `SOAP_BUFLEN` by default) More...
int | sndbuf
| User-definable value to set `SO_SNDBUF` `setsockopt` (the value is `SOAP_BUFLEN` by default) More...
int | tcp_keep_alive
| User-definable value to set `SO_KEEPALIVE` `setsockopt` (0 by default unless the `SOAP_IO_KEEPALIVE` mode flag is set) More...
unsigned int | tcp_keep_idle
| User-definable value to set `TCP_KEEPIDLE` `setsockopt` (the value is 0 by default) More...
unsigned int | tcp_keep_intvl
| User-definable value to set `TCP_KEEPINTVL` `setsockopt` (the value is 0 by default) More...
unsigned int | tcp_keep_cnt
| User-definable value to set `TCP_KEEPCNT` `setsockopt` (the value is 0 by default) More...
unsigned int | ipv6_multicast_if
| User-definable value to set `sockaddr_in6::sin6_scope_id` when nonzero. More...
char * | ipv4_multicast_if
| User-definable value to set `setsockopt` level `IPPROTO_IP` to `IP_MULTICAST_IF` when non-NULL. More...
unsigned char | ipv4_multicast_ttl
| User-definable value to set `setsockopt` level `IPPROTO_IP` to `IP_MULTICAST_TTL` when nonzero. More...
const char * | client_addr
| User-definable client address to bind to before connecting to a server, when non-NULL (Windows: n/a) More...
const char * | client_addr_ipv6
| User-definable client address to bind to before connecting to a server, when non-NULL, requires `WITH_IPV6` More...
int | client_port
| User-definable client port to bind to before connecting to a server, when non-negative. More...
const char * | client_interface
| User-definable client interface address to override when connecting to a server, when non-NULL (Windows: n/a) More...
unsigned short | z_level
| User-definable compression level for gzip compression (0=none, 1=fast to 9=best) default level is 6. More...
float | z_ratio_in
| The compression ratio = compressed.size/uncompressed.size of the compressed message received. More...
float | z_ratio_out
| The compression ratio = compressed.size/uncompressed.size of the compressed message sent. More...
const char * | bearer
| User-definable HTTP authorization bearer token value to be sent by the client, server side receives this string when the client sends authorization bearer. More...
const char * | userid
| User-definable HTTP and NTLM authorization user id string for HTTP basic and NTLM authentication by the client, server side receives this string when the client uses HTTP basic authentication, for HTTP digest authentication see the gSOAP HTTP digest authentication plugin. More...
const char * | passwd
| User-definable HTTP and NTLM authorization password string required for HTTP basic and NTLM authentication by the client, server side receives this string when the client uses HTTP basic authentication. More...
const char * | authrealm
| The HTTP and NTLM authorization realm/domain string received by the client with the `WWW-Authenticate` or `Proxy-Authenticate` HTTP headers, user-definable on the server side to send a `WWW-Authenticate` header to require authentication (service operation should return 401 to respond with "Unauthorized"), also serves as NTLM domain value. More...
const char * | ntlm_challenge
| User-definable NTLM authentication challenge key string. More...
const char * | proxy_host
| User-definable proxy host name string which should be set to connect through an HTTP proxy. More...
int | proxy_port
| User-definable proxy port which should be set to connect through an HTTP proxy (the value is 8080 by default) More...
const char * | proxy_userid
| User-definable proxy authorization user id string to authenticate and connect to an HTTP proxy. More...
const char * | proxy_passwd
| User-definable proxy authorization password string to authenticate and connect to an HTTP proxy. More...
const char * | proxy_from
| The `X-Forwarding-For` HTTP header string value received. More...
unsigned int | ip
| The IPv4 address in numeric form of the client as received on the server side by `soap_accept` (or the C++ service class `accept` method), possibly set to zero when `WITH_IPV6` is used. More...
unsigned int | ip6 [4]
| The IPv6 address in numeric form (upper ip6[0] to lower ip6[3]) of the client as received on the server side by `soap_accept` (or the C++ service class `accept` method), requires `WITH_IPV6` More...
int | port
| The client port connected to as received on the server side by `soap_accept` (or the C++ service class `accept` method) More...
char | endpoint [SOAP_TAGLEN]
| The endpoint URL as received on the server side. More...
char | host [SOAP_TAGLEN]
| The host IP address of the client, as received on the server side. More...
char | path [SOAP_TAGLEN]
| The client request path as received on the server side. More...
const char * | override_host
| User-definable string to override the host name or IP address in the HTTP header when connecting at the client side. More...
int | override_port
| User-definable port number to override the port address in the HTTP header when connecting at the client side. More...
const char * | origin
| The CORS Origin HTTP header string value received. More...
const char * | cors_origin
| The CORS Access-Control-Allow-Origin HTTP header string value received or the user-definable value to be returned by the server when set. More...
const char * | cors_allow
| User-definable CORS Access-Control-Allow-Origin HTTP header string default value (the value is `*` by default) More...
const char * | cors_method
| The CORS Access-Control-Request-Method HTTP header string received. More...
const char * | cors_header
| The CORS Access-Control-Request-Headers HTTP header string received. More...
const char * | cors_methods
| User-definable CORS Access-Control-Request-Methods HTTP header string to be returned by the server. More...
const char * | cors_headers
| User-definable CORS Access-Control-Request-Headers HTTP header string to be returned by the server. More...
const char * | float_format
| User-definable floating point format string (`%.9G` by default, the printed format must not exceed 1023 bytes) More...
const char * | double_format
| User-definable double floating point format string (`%.17lG` by default, the printed format must not exceed 1023 bytes) More...
const char * | long_double_format
| User-definable long double floating point format string (NULL by default and defined by the long_double.c custom serializer, the printed format must not exceed 1023 bytes) More...
const char * | dime_id_format
| User-definable format string to generate DIME content IDs. More...
struct soap_dom_element * | dom
| DOM tree received. More...
struct soap_dime | dime
| DIME attachments received. More...
struct soap_mime | mime
| MIME attachments received. More...
size_t | bufidx
| Internal index that keeps track of the current position in the `soap::buf` buffer after receiving data into the buffer. More...
size_t | buflen
| Internal index that keeps track of the length of the data available in the `soap::buf` buffer, does not exceed `SOAP_BUFLEN` More...
char | buf [SOAP_BUFLEN]
| Internal buffer with partial data received or partial data to be sent, where the data occupies `soap::buflen` bytes. More...
char | msgbuf [SOAP_TMPLEN]
| Internal buffer to hold short messages, URLs and HTTP/MIME header lines, must have at least `SOAP_TMPLEN` = 1024 bytes of space allocated. More...
char | tmpbuf [SOAP_TMPLEN]
| Internal buffer to hold temporary strings such as string representations of primitive values, XML tag names, HTTP header lines and so on, must have at least `SOAP_TMPLEN` = 1024 bytes of space allocated. More...
ULONG64 | count
| Message length counter value of the message received and counter value of the HTTP content length header to send a message. More...
ULONG64 | length
| The HTTP content length header value received or 0 when HTTP transfer encoding is chunked. More...
int(* | fpost )(struct soap *soap, const char *endpoint, const char *host, int port, const char *path, const char *action, ULONG64 count)
| Callback that populates and then sends HTTP headers from the client-side to a connected HTTP server. More...
int(* | fresponse )(struct soap *soap, int status, ULONG64 count)
| Callback that populates and then sends HTTP headers from the server-side to a connected client. More...
int(* | fposthdr )(struct soap *soap, const char *key, const char *val)
| Callback that sends a single HTTP header given a key-value pair. More...
int(* | fparse )(struct soap *soap)
| Callback that reads and parses HTTP and MIME headers. More...
int(* | fparsehdr )(struct soap *soap, const char *key, const char *val)
| Callback that consumes an HTTP header that consists of a key-value pair. More...
int(* | fget )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP GET requests from clients. More...
int(* | fput )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP PUT requests from clients. More...
int(* | fpatch )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP PATCH requests from clients. More...
int(* | fdel )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP DELETE requests from clients. More...
int(* | fopt )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP OPTION requests from clients. More...
int(* | fhead )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP HEAD requests from clients. More...
int(* | fform )(struct soap *soap)
| Callback to implement logic at the server-side to handle HTML forms, such as done by the callbacks provided by the HTTP FORM handler plugin. More...
int(* | fheader )(struct soap *soap)
| Callback to inspect the SOAP Header received before the rest of the message with the SOAP Body is consumed. More...
int(* | fencoding )(struct soap *soap, const char *encoding)
| Callback to catch unrecognized XML encoding formats. More...
int(* | fignore )(struct soap *soap, const char *tag)
| Callback to catch unrecognized XML elements and overrides `SOAP_XML_STRICT` validation errors for these. More...
int(* | fsvalidate )(struct soap *soap, const char *pattern, const char *string)
| Callback to validate strings against XML regex patterns. More...
int(* | fwvalidate )(struct soap *soap, const char *pattern, const wchar_t *string)
| Callback to validate wide strings against XML regex patterns. More...
void(* | fseterror )(struct soap *soap, const char **faultcode, const char **faultstring)
| Callback to inspect or override fault code or fault string messages. More...
SOAP_SOCKET(* | fopen )(struct soap *soap, const char *endpoint, const char *host, int port)
| Callback that opens a socket connection to a server endpoint. More...
SOAP_SOCKET(* | faccept )(struct soap *soap, SOAP_SOCKET sock, struct sockaddr *addr, int *len)
| Callback that waits for and accepts a socket connection requested by a client. More...
int(* | fclose )(struct soap *soap)
| Callback that closes the current socket connection. More...
int(* | fresolve )(struct soap *soap, const char *name, struct in_addr *inaddr)
| Callback that resolves a host name by address translation. More...
int(* | fconnect )(struct soap *soap, const char *endpoint, const char *host, int port)
| Callback that overrides the client-side connecting operations. More...
int(* | fdisconnect )(struct soap *soap)
| Callback that executes disconnect logic before closing. More...
int(* | fclosesocket )(struct soap *soap, SOAP_SOCKET sock)
| Callback that closes a given socket. More...
int(* | fshutdownsocket )(struct soap *soap, SOAP_SOCKET sock, int how)
| Callback that shuts down a given socket. More...
int(* | fpoll )(struct soap *soap)
| Callback that blocks until activity is detected on the `soap::socket` or `soap::master` socket, times out when `soap::send_timeout` or `soap::recv_timeout` are set. More...
size_t(* | frecv )(struct soap *soap, char *buf, size_t len)
| Callback that receives bytes of data into the given buffer. More...
int(* | fsend )(struct soap *soap, const char *data, size_t len)
| Callback that sends the given bytes of data. More...
int(* | fserveloop )(struct soap *soap)
| Callback executed by the engine at the server side immediately after a server operation successfully completed. More...
void *(* | fmalloc )(struct soap *soap, size_t size)
| Callback to override dynamic memory allocation and management. More...
void *(* | fdimereadopen )(struct soap *soap, void *handle, const char *id, const char *type, const char *options)
| Callback to open a streaming DIME attachment for reading. More...
size_t(* | fdimeread )(struct soap *soap, void *handle, char *buf, size_t len)
| Callback to read data in a DIME attachment stream. More...
void(* | fdimereadclose )(struct soap *soap, void *handle)
| Callback to close a DIME attachment stream after reading. More...
void *(* | fdimewriteopen )(struct soap *soap, const char *id, const char *type, const char *options)
| Callback to open a streaming DIME attachment for writing. More...
int(* | fdimewrite )(struct soap *soap, void *, const char *, size_t)
| Callback to write data in a DIME attachment stream. More...
void(* | fdimewriteclose )(struct soap *soap, void *handle)
| Callback to close a DIME attachment stream after writing. More...
void *(* | fmimereadopen )(struct soap *soap, void *, const char *, const char *, const char *)
| Callback to open a streaming MIME/MTOM attachment for reading. More...
size_t(* | fmimeread )(struct soap *soap, void *handle, char *buf, size_t len)
| Callback to read data in a MIME/MTOM attachment stream. More...
void(* | fmimereadclose )(struct soap *soap, void *handle)
| Callback to close a MIME/MTOM attachment stream after reading. More...
void *(* | fmimewriteopen )(struct soap *soap, void *handle, const char *id, const char *type, const char *description, enum soap_mime_encoding encoding)
| Callback to open a streaming MIME/MTOM attachment for writing. More...
int(* | fmimewrite )(struct soap *soap, void *handle, const char *buf, size_t len)
| Callback to write data in a MIME attachment stream. More...
void(* | fmimewriteclose )(struct soap *soap, void *handle)
| Callback to close a MIME/MTOM attachment stream after writing. More...
int(* | fsslauth )(struct soap *soap)
| Callback to initialize the OpenSSL library. More...
int(* | fsslverify )(int ok, X509_STORE_CTX *store)
| Callback to manage the verification of the certificate provided by a peer (typically a server) More...

## Detailed Description

Context with the engine state.

The `soap` context should be passed as the first parameter to all gSOAP functions and should only be used by a single thread at a time. Each thread should use a copy of the context created with `soap_copy` or with the `soap::soap` copy constructor.

To allocate a new `soap` context, use one of these three allocators that take `soap_mode` parameters:

struct soap *soap1 = soap_new();
struct soap *soap2 = soap_new1(input_and_output_mode);
struct soap *soap3 = soap_new2(input_mode, output_mode);

Alternatively, use constructors in C++ as follows:

struct soap *soap1();
struct soap *soap2(input_and_output_mode);
struct soap *soap3(input_mode, output_mode);

To copy the `soap` context, for example to be used by another thread, use:

struct soap *soap2 = soap_copy(soap1);

Alternatively, use the copy constructor in C++ as follows:

struct soap *soap2 = new soap(soap1);

To free the `soap` context or a copy of a `soap` context, use:

soap_free(soap1);

To stack-allocate a `soap` context (i.e. as opposed to heap-allocating it as shown above), initialize the `soap` context with one of these three initializers that take `soap_mode` parameters:

struct soap soap1, soap2, soap3;
soap_init(&soap1);
soap_init1(&soap2, input_and_output_mode);
soap_init2(&soap3, input_mode, output_mode);

Alternatively, use constructors in C++:

struct soap soap1();
struct soap soap2(input_and_output_mode);
struct soap soap3(input_mode, output_mode);

Finalization of the `soap` context is automatically done by the C++ destructor. In C, you should finalize a stack-allocated `soap` context before it is reclaimed by the stack:

soap_done(&soap1);

Before freeing or finalizating a `soap` context, you may want to delete all data allocated in managed heap memory with these two calls in this specific order:

soap_destroy(soap1);
soap_end(soap1);

Alternatively, in C++ you can simply invoke one method to perform both calls at once:

soap1.destroy();

## Constructor & Destructor Documentation

soap::soap | ( |  | ) |

Construct a `soap` context (C++ only, in C use `soap_new` or `soap_init`)

soap::soap | ( | soap_mode | input_and_output_mode | ) |

Construct a `soap` context with the specified input and output `soap_mode` flags (C++ only, in C use `soap_new1` or `soap_init1`))

Parameters

  input_and_output_mode | input and output `soap_mode` flags

soap::soap | ( | soap_mode | input_mode,
|  | soap_mode | output_mode
| ) |  |

Construct a `soap` context with the specified input and output `soap_mode` flags (C++ only, in C use `soap_new2` or `soap_init2`))

Parameters

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

soap::soap | ( | const struct soap & |  | ) |

Copy constructor (C++ only, in C use `soap_copy` or `soap_copy_context`)

soap::~soap | ( |  | ) |

Finalize and delete the `soap` context by finalizing with soap_done(this) (C++ only, in C use `soap_free` or `soap_done`)

## Member Function Documentation

void soap::destroy | ( |  | ) |

Delete all dynamically-allocated objects and data managed by this `soap` context (C++ only, in C use `soap_end`)

struct soap& soap::operator= | ( | const struct soap & |  | ) |

Assignment constructor (C++ only, in C use `soap_copy` or `soap_copy_context`)

Returns
  this `soap` context

## Member Data Documentation

int soap::accept_flags

User-definable `setsockopt` level `SOL_SOCKET` flags (0 by default), when nonzero sets the `soap::socket` flags when accepting a request with `soap_accept` (or the C++ service class `accept` method)

Example:

struct soap *soap = soap_new();
soap->accept_flags = SO_NOSIGPIPE; // no sigpipe (this is not portable)

Other ways to disable sigpipe:

struct soap *soap = soap_new();
soap->socket_flags = MSG_NOSIGNAL;
#include <signal.h>
void sigpipe_handle(int) { }
signal(SIGPIPE, sigpipe_handle);

See also
  `soap::socket_flags`, `soap::connect_flags`, `soap::bind_flags`.

int soap::accept_timeout

User-definable timeout when waiting to accept a request from a client at the server-side with `soap_accept` (or the C++ service class `accept` method), positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default)

Example:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
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)))
{
if (soap_serve(soap))
soap_print_fault(soap, stderr);
}
else if (soap->errnum) // 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);
}

See also
  `soap::error`, `soap::errnum`, `soap::connect_timeout`, `soap::recv_timeout`, `soap::send_timeout`, `soap::transfer_timeout`, `soap::recv_maxlength`.

const char* soap::actor

User-definable `SOAP-ENV:actor` (SOAP 1.1) or `SOAP-ENV:role` (SOAP 1.2) attribute value of all `SOAP-ENV:mustUnderstand` attributed header elements.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // context initializations
// add a SOAP Header to the message
SOAP_ENV__Header header;
header->ns__required_value = 123; // a header element marked mustUnderstand
soap->header = &header;
// add SOAP-ENV:role="http://www.w3.org/2002/06/soap-envelope/role/next";
soap->actor = "http://www.w3.org/2002/06/soap-envelope/role/next";
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also
  `SOAP_ENV__Header`.

const char* soap::authrealm

The HTTP and NTLM authorization realm/domain string received by the client with the `WWW-Authenticate` or `Proxy-Authenticate` HTTP headers, user-definable on the server side to send a `WWW-Authenticate` header to require authentication (service operation should return 401 to respond with "Unauthorized"), also serves as NTLM domain value.

See also
  `soap::userid`, `soap::passwd`.

const char* soap::bearer

User-definable HTTP authorization bearer token value to be sent by the client, server side receives this string when the client sends authorization bearer.

Example:

struct soap *soap = soap_new();
if (soap_ssl_client_context(soap, ...))
exit(EXIT_FAILURE);
soap->bearer = "bearer-token";
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
int main()
{
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap, ...))
exit(EXIT_FAILURE);
... // serve requests with soap_bind, soap_accept, soap_ssl_accept, and soap_serve
}
int ns__webmethod(struct soap *soap, ...)
{
if (!soap->bearer || strcmp(soap->bearer, "bearer-token"))
return 401; // Unauthorized
... // process the request data and populate the response data
return SOAP_OK;
}

See also
  `soap_ssl_client_context`, `soap_ssl_server_context`, `soap::userid`, `soap::passwd`, `soap::ntlm_challenge` and the HTTP digest plugin documentation.

int soap::bind_flags

User-definable `setsockopt` level `SOL_SOCKET` flags when binding `soap::master` socket (the value is 0 by default)

Example

struct soap *soap = soap_new();
soap->bind_flags = SO_REUSEADDR; // immediate port reuse when binding
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG))
... // success

See also
  `soap::socket_flags`, `soap::connect_flags`, `soap::accept_flags`, `WITH_IPV6`, `WITH_IPV6_V6ONLY`, `SOAP_IO_UDP`, `soap::bind_inet6`, `soap::bind_v6only`, `soap::rcvbuf`, `soap::sndbuf`, `soap::master`.

short soap::bind_inet6

User-definable flag, when nonzero uses `AF_INET6` instead of `PF_UNSPEC` when binding the `soap::master` socket in `soap_bind` (or the C++ service class `bind` method), to remap IPv4 to IPv6 addresses, meaningful only when used with `WITH_IPV6`

Example:

// requires compilation with compile-time flag -D WITH_IPV6
struct soap *soap = soap_new();
soap->bind_inet6 = 1;
soap->bind_v6only = 1;
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)) // IPv6 address binding
... // success

See also
  `soap::bind_v6only`.

Note
  Requires compilation with `WITH_IPV6`.

short soap::bind_v6only

User-definable flag, when nonzero enables `IPPROTO_IPV6` `setsockopt` `IPV6_V6ONLY` when binding the `soap::master` socket with `soap_bind` (or the C++ service class `bind` method), meaningful only when used with `WITH_IPV6`

Example:

// requires compilation with compile-time flag -D WITH_IPV6
struct soap *soap = soap_new();
soap->bind_inet6 = 1;
soap->bind_v6only = 1;
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)) // IPv6 address binding
... // success

See also
  `soap::bind_inet6`.

Note
  Requires compilation with `WITH_IPV6`.

short soap::body

The `soap::body` flag is set when an element has element content during XML parsing or when a HTTP message has a body when parsing an HTTP header.

char soap::buf[SOAP_BUFLEN]

Internal buffer with partial data received or partial data to be sent, where the data occupies `soap::buflen` bytes.

size_t soap::bufidx

Internal index that keeps track of the current position in the `soap::buf` buffer after receiving data into the buffer.

size_t soap::buflen

Internal index that keeps track of the length of the data available in the `soap::buf` buffer, does not exceed `SOAP_BUFLEN`

const char* soap::c14nexclude

User-definable string to control the XML namespace prefixes that are subject to XML canonicalization with `SOAP_XML_CANONICAL` output mode flag, specified by space-separated prefixes in the string, or NULL when unused.

const char* soap::c14ninclude

User-definable string to control the XML namespace prefixes that are subject to XML canonicalization with the `SOAP_XML_CANONICAL` output mode flag, specified by space-separated prefixes in the string, or `*` to specify that all prefixes are inclusive, or NULL when unused.

const char* soap::client_addr

User-definable client address to bind to before connecting to a server, when non-NULL (Windows: n/a)

When non-NULL, sets the client address specified as IPv4 or IPv6 or as a host address to bind to before connecting to a server. The value is reset to NULL after connecting successfully or unsuccessfully to the server.

Example:

struct soap *soap = soap_new();
soap->client_addr = "12.34.56.78"; // client binds to 12.34.56.78 when connecting to endpoint
soap->client_port = 8080; // optional, to also specify a port to bind to
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

Note
  Cannot be used on Windows platforms.

See also
  `soap::client_addr_ipv6`, `soap::client_port`, `soap::client_interface`.

const char* soap::client_addr_ipv6

User-definable client address to bind to before connecting to a server, when non-NULL, requires `WITH_IPV6`

When non-NULL and `soap::client_addr` is non-NULL and when connecting to a IPv6 server, sets the client address specified as IPv6 or as a host address to bind to before connecting to the server. The value is reset to NULL after connecting successfully or unsuccessfully to the server.

Example:

struct soap *soap = soap_new();
soap->client_addr = "12.34.56.78"; // client binds to 12.34.56.78 when connecting to a IPv4 endpoint
soap->client_addr_ipv6 = "2001:db8:0:1; // but the client binds 2001:db8:0:1 when connecting to a IPv6 endpoint
soap->client_port = 8080; // optional, to also specify a port to bind to
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

Note
  Requires compilation with `WITH_IPV6` or `WITH_IPV6_V6ONLY`.

See also
  `soap::client_addr`, `soap::client_port`, `soap::client_interface`.

const char* soap::client_interface

User-definable client interface address to override when connecting to a server, when non-NULL (Windows: n/a)

When non-NULL, sets the client address before connecting to a server. The value is reset to NULL after connecting successfully or unsuccessfully to the server. Does not bind the address, unlike `soap::client_addr` and `soap::client_addr_ipv6`.

Note
  Cannot be used on Windows platforms.

See also
  `soap::client_addr`, `soap::client_addr_ipv6`, `soap::client_addr_ipv6`.

int soap::client_port

User-definable client port to bind to before connecting to a server, when non-negative.

When non-negative, executes a `bind` with this port number before connecting to a server. The value is reset to -1 after connecting successfully or unsuccessfully to the server.

Example:

struct soap *soap = soap_new();
soap->client_port = 18000; // client binds to port 18000 when connecting to endpoint
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also
  `soap::client_addr`, `soap::client_addr_ipv6`, `soap::client_interface`.

int soap::connect_flags

User-definable `setsockopt` level `SOL_SOCKET` flags when connecting `soap::socket` to a server (the value is 0 by default)

Examples:

struct soap *soap = soap_new();
soap->connect_flags = SO_LINGER;
soap->linger_time = 5;
struct soap *soap = soap_new();
soap->connect_flags = SO_BROADCAST;

See also
  `soap::socket_flags`, `soap::bind_flags`, `soap::accept_flags`.

int soap::connect_retry

User-definable number of retries to attempt at the client side when connecting to a server fails with `SOAP_TCP_ERROR`, using exponential backoff delays between reconnects, maxed at 32 seconds: 1, 2, 4, 8, 16, 32, 32, 32, ... seconds for retry values 1 to 8 respectively (the retry value is 0 by default, meaning no retry)

Example:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
soap->connect_timeout = 30; // 30 seconds max connect stall time
soap->connect_retry = 4; // retry 4 more times (waiting 1, 2, 4, 8 seconds between retries)
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_call_ns__webmethod(soap, endpoint, NULL, ...))
{
soap_print_fault(soap, stderr);
if (soap->errnum == 0) // timed out, exit program
exit(EXIT_FAILURE);
}
else
{
... // success
}
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
}

See also
  `soap::error`, `soap::errnum`, `soap::connect_timeout`, `soap::recv_timeout`, `soap::send_timeout`, `soap::transfer_timeout`, `soap::recv_maxlength`, `SOAP_TCP_ERROR`.

int soap::connect_timeout

User-definable timeout when waiting to connect to a server at the client-side, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default)

Example:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
soap->connect_timeout = 30; // 30 seconds max connect stall time
soap->connect_retry = 4; // retry 4 more times (waiting 1, 2, 4, 8 seconds between retries)
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_call_ns__webmethod(soap, endpoint, NULL, ...))
{
soap_print_fault(soap, stderr);
if (soap->errnum == 0) // timed out, exit program
exit(EXIT_FAILURE);
}
else
{
... // success
}
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
}

See also
  `soap::error`, `soap::errnum`, `soap::connect_retry`, `soap::accept_timeout`, `soap::recv_timeout`, `soap::send_timeout`, `soap::transfer_timeout`, `soap::recv_maxlength`.

const char* soap::cookie_domain

User-definable string that specifies the HTTP cookie domain of the running server.

int soap::cookie_max

User-definable maximum number of active cookies allowed to be set with `soap_set_cookie` before cookie memory is reused (the value is 32 by default)

const char* soap::cookie_path

User-definable string that specifies the HTTP cookie path of the running server.

struct soap_cookie* soap::cookies

The cookie store is a linked list of cookies.

const char* soap::cors_allow

User-definable CORS Access-Control-Allow-Origin HTTP header string default value (the value is `*` by default)

CORS is automatic at the server side. At the client side, CORS requires the HTTP OPTIONS method with CORS headers.

See also
  `soap::origin`.

const char* soap::cors_header

The CORS Access-Control-Request-Headers HTTP header string received.

CORS is automatic at the server side. At the client side, CORS requires the HTTP OPTIONS method with CORS headers.

See also
  `soap::origin`.

const char* soap::cors_headers

User-definable CORS Access-Control-Request-Headers HTTP header string to be returned by the server.

CORS is automatic at the server side. At the client side, CORS requires the HTTP OPTIONS method with CORS headers.

See also
  `soap::origin`.

const char* soap::cors_method

The CORS Access-Control-Request-Method HTTP header string received.

CORS is automatic at the server side. At the client side, CORS requires the HTTP OPTIONS method with CORS headers.

See also
  `soap::origin`.

const char* soap::cors_methods

User-definable CORS Access-Control-Request-Methods HTTP header string to be returned by the server.

CORS is automatic at the server side. At the client side, CORS requires the HTTP OPTIONS method with CORS headers.

See also
  `soap::origin`.

const char* soap::cors_origin

The CORS Access-Control-Allow-Origin HTTP header string value received or the user-definable value to be returned by the server when set.

See also
  `soap::origin`.

ULONG64 soap::count

Message length counter value of the message received and counter value of the HTTP content length header to send a message.

See also
  `soap_begin_count`, `soap_end_count`, `SOAP_IO_LENGTH`, `SOAP_IO_CHUNK`.

SSL_CTX* soap::ctx

OpenSSL context pointer.

This pointer is non-NULL after calling `soap_ssl_server_context` or `soap_ssl_client_context` and points to the OpenSSL context which can be configured with OpenSSL API functions such as `SSL_CTX_set_cipher_list`.

Note
  Requires compilation with `WITH_OPENSSL`.

See also
  `soap_ssl_server_context`, `soap_ssl_client_context`.

struct soap_dime soap::dime

DIME attachments received.

This structure contains a linked list of DIME attachments received.

const char* soap::dime_id_format

User-definable format string to generate DIME content IDs.

The DIME ID format string should contain exactly one `d` or `x` field and no other fields. The default format string is "cid:id%d". Should not be changed unless required by protocol updates.

struct soap_dom_element* soap::dom

DOM tree received.

This pointer points to the DOM tree received when `SOAP_XML_DOM` mode is enabled and the engine is configured with `WITH_DOM`.

See also
  `WITH_DOM`, `SOAP_XML_DOM`.

const char* soap::double_format

User-definable double floating point format string (`%.17lG` by default, the printed format must not exceed 1023 bytes)

Example:

#include "soapH.h"
struct soap *soap = soap_new();
soap->float_format = "%g";
soap->double_format = "%g";
soap->long_double_format = "%Lg";

const char* soap::encodingStyle

User-definable `SOAP-ENV:encodingStyle` URI value.

This URI string value is pre-defined by the engine depending on the SOAP protocol version used, setting this to NULL means no SOAP encodingStyle. Setting this to an empty string "" means that the engine will set the encodingStyle URI according to the SOAP version used. However, the encodingStyle is always set if the interface header file for soappcpp2 explicitly specifies an encoding or literal.

See also
  `soap::version`, `soap_set_version`.

char soap::endpoint[SOAP_TAGLEN]

The endpoint URL as received on the server side.

On the server side, the URL endpoint string is extracted from the HTTP header by `soap::fparse` called by `soap_begin_recv` and consists of the concatenated string of `soap::host`, `soap::port`, and `soap::path` to form a valid URL.

See also
  `soap::ip`, `soap::ip6`, `soap::host`, `soap::port`, `soap::path`, `soap_query`.

int soap::errnum

The `errno` value of the last failed IO operation.

The `soap::errnum` value is set to the value or `errno` when a `SOAP_EOF` or `SOAP_TCP_ERROR` error occurred. This allows for reporting the error condition with `soap_print_fault`, `soap_stream_fault`, and `soap_sprint_fault`. For the `SOAP_EOF` error, `soap::errnum` is set to zero when IO operations timed out, when a client's connection attempt to a server timed out, or when a server-side `soap_accept` timed out.

See also
  `soap::error`, `soap::connect_timeout`, `soap::accept_timeout`, `soap::recv_timeout`, `soap::send_timeout`.

int soap::error

The `soap` context `soap_status` (int) error code of the last operation or `SOAP_OK` (zero)

See also
  `soap_status`, `soap::errnum`.

struct SOAP_ENV__Fault* soap::fault

The `soap::fault` points to a `SOAP_ENV__Fault` structure with the SOAP Fault that was received or that can be populated by the user to be sent, or NULL when no SOAP Fault is present.

const char* soap::float_format

User-definable floating point format string (`%.9G` by default, the printed format must not exceed 1023 bytes)

Example:

#include "soapH.h"
struct soap *soap = soap_new();
soap->float_format = "%g";
soap->double_format = "%g";
soap->long_double_format = "%Lg";

struct SOAP_ENV__Header* soap::header

The `soap::header` points to a `SOAP_ENV__Header` structure with the SOAP Header that was received or that can be populated by the user to be sent, or NULL when no SOAP Header is present.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
... // context initializations
// add a SOAP Header to the message
SOAP_ENV__Header header;
header->ns__someHeaderValue = 123;
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
{
soap_print_fault(soap, stderr);
}
else
{
if (soap->header) // received a SOAP_ENV__Header?
... // yes, inspect SOAP_ENV__Header headers
}
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also
  `SOAP_ENV__Header`, `soap::actor`.

char soap::host[SOAP_TAGLEN]

The host IP address of the client, as received on the server side.

On the server side, the host string is the IPv4 or IPv6 address, depending on `WITH_IPV6`. On the client side, the host string is extracted from `soap::endpoint`, i.e. the endpoint URL of the server.

See also
  `soap::ip`, `soap::ip6`, `soap::endpoint`, `soap::port`, `soap::path`, `soap_query`.

const char* soap::http_content

String with HTTP content type header value received, can also be assigned to specify a content type header for `soap_connect_command` with `SOAP_POST_FILE`, `SOAP_PUT` and `SOAP_PATCH` or for `soap_response` with `SOAP_FILE` or for `soap_PUT`, `soap_PATCH`, `soap_POST`. The `soap::http_content` string is reset to NULL after each HTTP invocation and has to be set again when required.

See also
  `soap_connect_command`, `soap_PUT`, `soap_PATCH`, `soap_POST`, `soap_response`.

const char* soap::http_extra_header

User-definable string that specifies an extra HTTP header or multiple HTTP headers when separated by CRLF in the specified string, to include in the next HTTP request (client side) or to include with the HTTP response (server side). The specified headre or headers are checked by the engine to conform to HTTP header formats or otherwise will be ignored and not output.

Examples:

#include "soapH.h"
struct soap *soap = soap_new();
... // context initializations
soap->http_extra_header = "X-CUSTOM-RequestMessageNumber: 1\r\nX-CUSTOM-TotalRequests: 5";
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap, ...))
exit(EXIT_FAILURE);
... // serve requests with soap_bind, soap_accept, soap_ssl_accept, and soap_serve
}
int ns__webmethod(struct soap *soap, ...)
{
... // process the request data and populate the response data
soap->http_extra_header = "X-CUSTOM-ResponseMessageNumber: 1";
return SOAP_OK;
}

See also
  `soap_GET`, `soap_PUT`, `soap_PATCH`, `soap_POST`, `soap_DELETE`, `soap::fparsehdr`.

soap_mode soap::imode

The `soap` context input `soap_mode` flags that are set at context initialization and set or cleared with `soap_set_imode` or `soap_clr_imode`, respectively.

See also
  `soap::omode`, `soap_set_omode`, `soap_set_mode`, `soap_clr_omode`, `soap_clr_mode`.

unsigned int soap::ip

The IPv4 address in numeric form of the client as received on the server side by `soap_accept` (or the C++ service class `accept` method), possibly set to zero when `WITH_IPV6` is used.

Example:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
soap->accept_timeout = 3600; // exit loop when no request arrives in one hour
... // context initializations
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
{
while (1)
{
if (soap_valid_socket(soap_accept(soap)))
{
printf("Client host = %s port = %d path = %s ip = %d.%d.%d.%d\n", soap->host, soap->port, soap->path, soap->ip >> 24, (soap->ip >> 16) & 0xFF, (soap->ip >> 8) & 0xFF, soap->ip & 0xFF);
if (soap_serve(soap))
soap_print_fault(soap, stderr);
}
else if (soap->errnum) // 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);
}

See also
  `soap::host`, `soap::port`, `soap::ip6`, `soap_bind`, `soap_accept`, `soap_ssl_accept`, `soap_serve`.

unsigned int soap::ip6[4]

The IPv6 address in numeric form (upper ip6[0] to lower ip6[3]) of the client as received on the server side by `soap_accept` (or the C++ service class `accept` method), requires `WITH_IPV6`

Example:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
soap->accept_timeout = 3600; // exit loop when no request arrives in one hour
... // context initializations
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
{
while (1)
{
if (soap_valid_socket(soap_accept(soap)))
{
printf("Client host = %s port = %d path = %s ", soap->host, soap->port, soap->path);
if (soap->ip)
printf("ip4 = %d.%d.%d.%d\n", soap->ip >> 24, (soap->ip >> 16) & 0xFF, (soap->ip >> 8) & 0xFF, soap->ip & 0xFF);
else
printf("ip6 = %.8x%.8x%.8x%.8x\n", soap->ip6[0], soap->ip6[1], soap->ip6[2], soap->ip6[3]);
if (soap_serve(soap))
soap_print_fault(soap, stderr);
}
else if (soap->errnum) // 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);
}

Note
  Requires compilation with `WITH_IPV6` or `WITH_IPV6_V6ONLY`.

See also
  `soap::host`, `soap::port`, `soap::ip`, `soap_bind`, `soap_accept`, `soap_ssl_accept`, `soap_serve`.

char* soap::ipv4_multicast_if

User-definable value to set `setsockopt` level `IPPROTO_IP` to `IP_MULTICAST_IF` when non-NULL.

This value is used by the engine for UDP multicast messaging at the client side, sets `setsockopt` level `IPPROTO_IP` to `IP_MULTICAST_IF` with value `soap::ipv4_multicast_if` when non-NULL.

See also
  `WITH_IPV6`, `SOAP_IO_UDP`, `soap::ipv6_multicast_if`, `soap::ipv4_multicast_ttl`.

unsigned char soap::ipv4_multicast_ttl

User-definable value to set `setsockopt` level `IPPROTO_IP` to `IP_MULTICAST_TTL` when nonzero.

This value is used by the engine for UDP multicast messaging at the client side, sets `setsockopt` level `IPPROTO_IP` to `IP_MULTICAST_TTL` with value `soap::ipv4_multicast_ttl` when nonzero. Requires `WITH_IPV6`.

Example:

struct soap *soap = soap_new();
in_addr_t addr = inet_addr("1.2.3.4"); // optional
soap->send_timeout = 5; // 5 seconds max socket delay
soap->connect_flags = SO_BROADCAST; // required for broadcast
soap->ipv4_multicast_if = &addr; // optional for IPv4, see setsockopt IPPROTO_IP IP_MULTICAST_IF
soap->ipv6_multicast_if = addr; // optional for IPv6 (requires WITH_IPV6), multicast sin6_scope_id
soap->ipv4_multicast_ttl = 1; // optional, see setsockopt IPPROTO_IP, IP_MULTICAST_TTL

Refer to the socket options for `IPPROTO_IP` `IP_MULTICAST_TTL` to limit the lifetime of the packet. Multicast datagrams are sent with a default value of 1, to prevent them to be forwarded beyond the local network. This parameter can be set between 1 to 255.

See also
  `WITH_IPV6`, `SOAP_IO_UDP`, `soap::ipv6_multicast_if`, `soap::ipv4_multicast_if`.

unsigned int soap::ipv6_multicast_if

User-definable value to set `sockaddr_in6::sin6_scope_id` when nonzero.

This value is used by the engine for UDP multicast messaging at the client side, sets `sockaddr_in6::sin6_scope_id` to `soap::ipv6_multicast_if` when nonzero. Requires `WITH_IPV6`.

See also
  `WITH_IPV6`, `SOAP_IO_UDP`, `soap::ipv4_multicast_if`, `soap::ipv4_multicast_ttl`.

SOAP_SOURCE* soap::is

The source to read data from when non-NULL, which in C++ is a `std::istream` object and in C is a 0-terminated string to be read, default value is NULL.

Examples:

// C example
#include "soapH.h"
struct soap *soap = soap_new1(SOAP_DOM_TREE);
struct ns__someElement data;
soap->is = "<ns:someElement xmlns:ns="urn:example"><text>example</text></ns:someElement>\n";
// parse and deserialize XML into a ns__someElement structure
if (soap_read_ns__someElement(soap, &data))
... // an error occurred
soap->is = NULL;
// C++ example
#include "soapH.h"
struct soap *soap = soap_new1(SOAP_DOM_TREE);
struct ns__someElement data;
std::stringstream ss("<ns:someElement xmlns:ns="urn:example"><text>example</text></ns:someElement>\n");
soap->is = &ss;
// parse and deserialize XML into a ns__someElement structure
if (soap_read_ns__someElement(soap, &data))
... // an error occurred
soap->is = NULL;

int soap::keep_alive

HTTP keep-alive flag (try to enable when -1, disabled when 0) and counter (enabled when >0)

See also
  `SOAP_IO_KEEPALIVE`, `soap_serve`, `soap_closesock`, `soap::max_keep_alive`.

const char* soap::lang

User-definable `xml:lang` attribute value of `SOAP-ENV:Text` to output the SOAP Fault string/reason (the value is `en` by default)

See also
  `SOAP_ENV__Reason`.

ULONG64 soap::length

The HTTP content length header value received or 0 when HTTP transfer encoding is chunked.

unsigned short soap::linger_time

User-definable linger time value, requires the `SO_LINGER` `setsockopt` flag value to be assigned to `soap::socket_flags`

Example:

struct soap *soap = soap_new();
soap->connect_flags = SO_LINGER;
soap->linger_time = 5;

const char* soap::long_double_format

User-definable long double floating point format string (NULL by default and defined by the long_double.c custom serializer, the printed format must not exceed 1023 bytes)

Example:

#include "soapH.h"
struct soap *soap = soap_new();
soap->float_format = "%g";
soap->double_format = "%g";
soap->long_double_format = "%Lg";

Note
  Requires `#import "custom/long_double.h" in the .h file for soapcpp2 to generate code that supports`long double`and compiling <i>`gsoap/custom/long_double.c`</i> to serialize`long double`.

SOAP_SOCKET soap::master

The socket set by `soap_bind` (or the C++ service class `bind` method) to serve as the master socket bound to a specified port, or `SOAP_INVALID_SOCKET` when unassigned.

See also
  `soap_bind`, `soap_valid_socket`.

int soap::max_keep_alive

User-definable maximum number of keep-alive message exchanges per connection (the value is `SOAP_MAXKEEPALIVE` by default)

Example:

struct soap *soap = soap_new1(SOAP_IO_KEEPALIVE); // enable HTTP keep-alive
soap->max_keep_alive = 50; // 50 max keep-alive exchanges (SOAP_MAXKEEPALIVE by default)

See also
  `SOAP_IO_KEEPALIVE`, `soap_serve`, `soap::keep_alive`.

long soap::maxlength

User-definable maximum string length parsed from XML and JSON, initially set to `SOAP_MAXLENGTH`, zero or negative means unlimited (0 by default)

The length of a string is the number of characters it contains. Multi-byte strings with UTF-8 content (enabled with `SOAP_C_UTFSTRING`) contain up to the specified number of multi-byte characters. The byte length depends on the UTF-8 encoding. The specified limit applies to strings that are not subject to string length schema validation constraints, to ensure that schema validation is not affected.

Example:

struct soap *soap = soap_new();
soap->maxlength = 256; // limit string lengths to 256 characters (unlimited by default)

See also
  `soap::recv_maxlength`, `soap::maxlevel`, `soap::maxoccurs`.

unsigned int soap::maxlevel

User-definable maximum XML and JSON nesting level permitted, initially set to `SOAP_MAXLEVEL` (the value is 10000 by default)

Example:

struct soap *soap = soap_new();
soap->maxlevel = 10; // limit XML nesting depth to 10 (10000 by default)

See also
  `soap::recv_maxlength`, `soap::maxlength`, `soap::maxoccurs`.

size_t soap::maxoccurs

User-definable maximum array and container size (maximum item occurrence constraint) as parsed from XML and JSON, except when specifie XML schema validation constraints permit greater sizes, initially set to `SOAP_MAXOCCURS` (the value is 100000 by default)

The specified occurrence limit applies to arrays and containers that are not subject to occurrence validation constraints (`minOccurs` and `maxOccurs`, to ensure that schema validation is not affected.

Example:

struct soap *soap = soap_new();
soap->maxoccurs = 100; // limit arrays and containers to 100 items (100000 by default)

See also
  `soap::recv_maxlength`, `soap::maxlevel`, `soap::maxlength`.

struct soap_mime soap::mime

MIME attachments received.

This structure contains a linked list of MIME attachments received.

char soap::msgbuf[SOAP_TMPLEN]

Internal buffer to hold short messages, URLs and HTTP/MIME header lines, must have at least `SOAP_TMPLEN` = 1024 bytes of space allocated.

short soap::mustUnderstand

The `soap::mustUnderstand` flag is set when a SOAP Header element carries a `SOAP-ENV:mustUnderstand` attribute that is true.

const char* soap::ntlm_challenge

User-definable NTLM authentication challenge key string.

Examples:

#include "soapH.h"
struct soap *soap = soap_new();
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...) == 401) // Unauthorized, got soap->authrealm with NTLM domain
{
soap->userid = "user-id"; // NTLM auth credential
soap->passwd = "user-pw"; // NTLM auth credential
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...)) // try again
soap_print_fault(soap, stderr);
else
... // success
}
else
{
... // success
}
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
#include "soapH.h"
struct soap *soap = soap_new();
soap->ntlm_challenge = ""; // pretend we've been challenged
soap->userid = "user-id"; // NTLM credential
soap->passwd = "user-pw"; // NTLM credential
soap->authrealm = "server-domain"; // NTLM domain
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

Note
  Requires compilation with `WITH_NTLM` and linking libntlm available at http://www.nongnu.org/libntlm for non-Windows platforms.

See also
  `soap::bearer`, `soap::userid`, `soap::passwd`, `soap::proxy_userid`, `soap::proxy_passwd`.

short soap::null

The `soap::null` flag is set when an element carries a `xsi:nil` attribute that is true.

soap_mode soap::omode

The `soap` context output `soap_mode` flags that are set at context initialization and set or cleared with `soap_set_omode` or `soap_clr_omode`, respectively.

See also
  `soap::imode`, `soap_set_omode`, `soap_set_mode`, `soap_clr_omode`, `soap_clr_mode`.

const char* soap::origin

The CORS Origin HTTP header string value received.

CORS is automatic at the server side. The server internally calls the `soap::fopt` callback to serve the OPTION method CORS request, which returns HTTP 200 OK with CORS headers. The default value of the CORS Access-Control-Allow-Origin header is "*".

At the client side, CORS requires the HTTP OPTIONS method with CORS headers. Use the following code to send HTTP OPTIONS with CORS headers to a server:

#include "soapH.h"
struct soap *soap = soap_new();
soap->origin = "http://example.com";
soap->cors_method = "POST"; // request method is POST
soap->cors_header = "..."; // list of comma-separated request headers (may be omitted)
if (soap_connect_command(soap, SOAP_OPTIONS, endpoint, NULL)
|| soap_end_send(soap)
|| soap_recv_empty_response(soap))
soap_print_fault(soap, stderr);
else if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success

See also
  `soap::cors_origin`, `soap::cors_allow`, `soap::cors_method`, `soap::cors_header`, `soap::cors_methods`, `soap::cors_header`.

SOAP_SINK* soap::os

The sink to write data to when non-NULL, which in C++ is a `std::ostream` object and in C is a pointer to a `char*` string variable that will be set to point to a managed 0-terminated string with the data, default value is NULL.

Examples:

// C example
#include "soapH.h"
struct soap *soap = soap_new1(SOAP_DOM_TREE);
struct ns__someElement data;
char *cs = NULL;
... // populate the data
soap->os = &cs;
// serialize ns__someElement structure as XML
if (soap_write_ns__someElement(soap, &data))
... // an error occurred
soap->os = NULL;
const char *xml = cs; // string allocated and managed by the context
// C++ example
#include "soapH.h"
struct soap *soap = soap_new1(SOAP_DOM_TREE);
struct ns__someElement data;
... // populate the data
std::stringstream ss;
soap->os = &ss;
// serialize ns__someElement structure as XML
if (soap_write_ns__someElement(soap, &data))
... // an error occurred
soap->os = NULL;
std::string xml = ss.str();

const char* soap::override_host

User-definable string to override the host name or IP address in the HTTP header when connecting at the client side.

Example:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_IO_CHUNK);
... // initializations
soap->override_host = "server-domain-or-IP";
soap->override_port = 1234;
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also
  `soap::override_port`.

int soap::override_port

User-definable port number to override the port address in the HTTP header when connecting at the client side.

See also
  `soap::override_host`.

const char* soap::passwd

User-definable HTTP and NTLM authorization password string required for HTTP basic and NTLM authentication by the client, server side receives this string when the client uses HTTP basic authentication.

See also
  `soap::userid`, `soap::authrealm`.

char soap::path[SOAP_TAGLEN]

The client request path as received on the server side.

The URL path string is extracted from the HTTP header by `soap::fparse` called by `soap_begin_recv` and starts with a "/".

See also
  `soap::ip`, `soap::ip6`, `soap::endpoint`, `soap::host`, `soap::port`, `soap_query`.

int soap::port

The client port connected to as received on the server side by `soap_accept` (or the C++ service class `accept` method)

See also
  `soap::ip`, `soap::ip6`.

const char* soap::prolog

User-definable XML declaration prolog (`<?xml version="1.0" encoding="UTF-8"?>` by default)

const char* soap::proxy_from

The `X-Forwarding-For` HTTP header string value received.

const char* soap::proxy_host

User-definable proxy host name string which should be set to connect through an HTTP proxy.

Example:

#include "soapH.h"
struct soap *soap = soap_new();
soap->proxy_host = "proxy-domain-or-IP";
soap->proxy_port = 3128;
soap->proxy_userid = "proxy-id";
soap->proxy_passwd = "proxy-pw";
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);

See also
  `soap::bearer`, `soap::userid`, `soap::passwd`, `soap::ntlm_challenge`, `soap::http_extra_header`, and the HTTP digest plugin documentation.

const char* soap::proxy_passwd

User-definable proxy authorization password string to authenticate and connect to an HTTP proxy.

See also
  `soap::proxy_host`.

int soap::proxy_port

User-definable proxy port which should be set to connect through an HTTP proxy (the value is 8080 by default)

See also
  `soap::proxy_host`.

const char* soap::proxy_userid

User-definable proxy authorization user id string to authenticate and connect to an HTTP proxy.

See also
  `soap::proxy_host`.

int soap::rcvbuf

User-definable value to set `SO_RCVBUF` `setsockopt` (the value is `SOAP_BUFLEN` by default)

Example:

struct soap *soap = soap_new();
soap->rcvbuf = 32768; // setsockopt SO_RCVBUF size

ULONG64 soap::recv_maxlength

User-definable maximum message length that is permitted to be received, zero means unlimited (the value is 2GB by default)

Example:

struct soap *soap = soap_new();
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)

int soap::recv_timeout

User-definable timeout to receive a packet of data, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default)

Example:

struct soap *soap = soap_new();
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)

See also
  `soap::error`, `soap::errnum`, `soap::connect_timeout`, `soap::accept_timeout`, `soap::send_timeout`, `soap::transfer_timeout`, `soap::recv_maxlength`.

int soap::recvfd

The file descriptor to read data from when no socket communications are set (`soap::socket` == `SOAP_INVALID_SOCKET`) and `soap:is` == NULL, default value is 0 (stdin)

Example:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_DOM_TREE);
struct ns__someElement data;
if ((soap->recvfd = open("doc.xml", O_RDONLY)) == 0)
... // an error occurred
// parse and deserialize XML into a ns__someElement structure
if (soap_read_ns__someElement(soap, &data))
... // an error occurred
close(soap->recvfd);
soap->recvfd = 0;

int soap::send_timeout

User-definable timeout to send a packet of data, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default)

Example:

struct soap *soap = soap_new();
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)

See also
  `soap::error`, `soap::errnum`, `soap::connect_timeout`, `soap::accept_timeout`, `soap::recv_timeout`, `soap::transfer_timeout`, `soap::recv_maxlength`.

int soap::sendfd

The file descriptor to write data to when no socket communications are set (`soap::socket` == `SOAP_INVALID_SOCKET`) and `soap:os` == NULL, default value is 1 (stdout)

Example:

#include "soapH.h"
struct soap *soap = soap_new1(SOAP_DOM_TREE);
struct ns__someElement data;
... // populate the data
if ((soap->sendfd = open("doc.xml", O_CREAT | O_RDWR, 0644)) == 0)
... // an error occurred
// serialize ns__someElement structure as XML
if (soap_write_ns__someElement(soap, &data))
... // an error occurred
close(soap->sendfd);
soap->sendfd = 1;

int soap::sndbuf

User-definable value to set `SO_SNDBUF` `setsockopt` (the value is `SOAP_BUFLEN` by default)

Example:

struct soap *soap = soap_new();
soap->sndbuf = 32768; // setsockopt SO_SNDBUF size

SOAP_SOCKET soap::socket

The socket set by `soap_accept` (or the C++ service class `accept` method) or `soap_connect` or `soap_connect_command` (or the C++ proxy methods) when successful, or `SOAP_INVALID_SOCKET` when unassigned.

See also
  `soap_accept`, `soap_connect`, `soap_connect_command`, `soap_valid_socket`.

int soap::socket_flags

User-definable socket `send` and `recv` flags, for example assign `MSG_NOSIGNAL` to disable sigpipe (the value is 0 by default)

Example:

struct soap *soap = soap_new();
soap->socket_flags = MSG_NOSIGNAL; // no sigpipe (this is not portable)

Other ways to disable sigpipe:

struct soap *soap = soap_new();
soap->connect_flags = SO_NOSIGPIPE;
soap->bind_flags = SO_NOSIGPIPE;
#include <signal.h>
void sigpipe_handle(int) { }
signal(SIGPIPE, sigpipe_handle);

See also
  `soap::connect_flags`, `soap::bind_flags`, `soap::accept_flags`.

int soap::status

The `soap` context HTTP status code received at the client side (100 to 599), HTTP header method received at the server side (`SOAP_POST`, `SOAP_PATCH`, `SOAP_GET`, `SOAP_PUT`, `SOAP_DEL`, `SOAP_HEAD`, `SOAP_OPTIONS`), or the HTTP method to use for sending a message with `soap_connect_command` or with `soap_response` (`SOAP_POST`, `SOAP_POST_FILE`, `SOAP_PATCH`, `SOAP_GET`, `SOAP_PUT`, `SOAP_PUT`, `SOAP_DEL`, `SOAP_CONNECT`, `SOAP_HEAD`, `SOAP_OPTIONS`)

See also
  `soap_connect_command`, `soap_GET`, `soap_PUT`, `soap_PATCH`, `soap_POST`, `soap_DELETE`, `soap_response`.

int soap::tcp_keep_alive

User-definable value to set `SO_KEEPALIVE` `setsockopt` (0 by default unless the `SOAP_IO_KEEPALIVE` mode flag is set)

Example:

struct soap *soap = soap_new();
soap->tcp_keep_alive = 1; // setsockopt SO_KEEPALIVE
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

HTTP keep-alive together with TCP `SO_KEEPALIVE` is enabled with:

struct soap *soap = soap_new1(SOAP_IO_KEEPALIVE); // enable HTTP keep-alive
soap->max_keep_alive = 50; // 50 max keep-alive exchanges for SOAP_IO_KEEPALIVE (SOAP_MAXKEEPALIVE by default)
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

See also
  `SOAP_IO_KEEPALIVE`, `soap::tcp_keep_idle`, `soap::tcp_keep_intvl` and `soap::tcp_keep_cnt`.

unsigned int soap::tcp_keep_cnt

User-definable value to set `TCP_KEEPCNT` `setsockopt` (the value is 0 by default)

Example:

struct soap *soap = soap_new();
soap->tcp_keep_alive = 1; // setsockopt SO_KEEPALIVE
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

HTTP keep-alive with TCP `SO_KEEPALIVE` is enabled with:

struct soap *soap = soap_new1(SOAP_IO_KEEPALIVE); // enable HTTP keep-alive
soap->max_keep_alive = 50; // 50 max keep-alive exchanges (SOAP_MAXKEEPALIVE by default)
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

See also
  `soap::tcp_keep_alive`, `soap::tcp_keep_idle` and `soap::tcp_keep_intvl`.

unsigned int soap::tcp_keep_idle

User-definable value to set `TCP_KEEPIDLE` `setsockopt` (the value is 0 by default)

Example:

struct soap *soap = soap_new();
soap->tcp_keep_alive = 1; // setsockopt SO_KEEPALIVE
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

HTTP keep-alive with TCP `SO_KEEPALIVE` is enabled with:

struct soap *soap = soap_new1(SOAP_IO_KEEPALIVE); // enable HTTP keep-alive
soap->max_keep_alive = 50; // 50 max keep-alive exchanges (SOAP_MAXKEEPALIVE by default)
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

See also
  `soap::tcp_keep_alive`, `soap::tcp_keep_intvl` and `soap::tcp_keep_cnt`.

unsigned int soap::tcp_keep_intvl

User-definable value to set `TCP_KEEPINTVL` `setsockopt` (the value is 0 by default)

Example:

struct soap *soap = soap_new();
soap->tcp_keep_alive = 1; // setsockopt SO_KEEPALIVE
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

HTTP keep-alive with TCP `SO_KEEPALIVE` is enabled with:

struct soap *soap = soap_new1(SOAP_IO_KEEPALIVE); // enable HTTP keep-alive
soap->max_keep_alive = 50; // 50 max keep-alive exchanges (SOAP_MAXKEEPALIVE by default)
soap->tcp_keep_idle = 30; // time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
soap->tcp_keep_intvl = 120; // time in seconds between individual keepalive probes
soap->tcp_keep_cnt = 5; // maximum number of keepalive probes TCP should send before dropping the connection

See also
  `soap::tcp_keep_alive`, `soap::tcp_keep_idle` and `soap::tcp_keep_cnt`.

char soap::tmpbuf[SOAP_TMPLEN]

Internal buffer to hold temporary strings such as string representations of primitive values, XML tag names, HTTP header lines and so on, must have at least `SOAP_TMPLEN` = 1024 bytes of space allocated.

int soap::transfer_timeout

User-definable timeout to send or receive an entire message, positive timeout values are seconds, negative timeout values are microseconds, zero means no timeout (the value is 0 by default)

Example:

struct soap *soap = soap_new();
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)

See also
  `soap::error`, `soap::errnum`, `soap::connect_timeout`, `soap::accept_timeout`, `soap::recv_timeout`, `soap::send_timeout`, `soap::recv_maxlength`.

void* soap::user

User-definable variable that may point to user-specified data of any type to pass the data through to callbacks and plugins.

const char* soap::userid

User-definable HTTP and NTLM authorization user id string for HTTP basic and NTLM authentication by the client, server side receives this string when the client uses HTTP basic authentication, for HTTP digest authentication see the gSOAP HTTP digest authentication plugin.

Examples:

#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_client_context(soap, ...))
exit(EXIT_FAILURE);
soap->userid = "user-id"; // HTTP basic auth credential
soap->passwd = "user-pw"; // HTTP basic auth credential
soap->authrealm = "server-domain"; // if known in advance, see example below
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...))
soap_print_fault(soap, stderr);
else
... // success
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_client_context(soap, ...))
exit(EXIT_FAILURE);
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...) == 401) // Unauthorized, got soap->authrealm
{
soap->userid = "user-id"; // HTTP basic auth credential
soap->passwd = "user-pw"; // HTTP basic auth credential
if (soap_call_ns__webmethod(soap, endpoint, NULL, ...)) // try again
soap_print_fault(soap, stderr);
else
... // success
}
else
{
... // success
}
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap, ...))
exit(EXIT_FAILURE);
... // serve requests with soap_bind, soap_accept, soap_ssl_accept, and soap_serve
}
int ns__webmethod(struct soap *soap, ...)
{
if (!soap->userid ||
!soap->passwd ||
!soap->authrealm ||
strcmp(soap->userid, "user-id") ||
strcmp(soap->passwd, "user-pw") ||
strcmp(soap->authrealm, "server-domain"))
return 401; // Unauthorized
... // process the request data and populate the response data
return SOAP_OK;
}

See also
  `soap::passwd`, `soap::authrealm`, `soap_ssl_client_context`, `soap::bearer`, `soap::ntlm_challenge`, `soap::http_extra_header`, `soap::proxy_userid`, `soap::proxy_passwd` and the HTTP digest plugin documentation.

short soap::version

SOAP version (0 = no SOAP, 1 = SOAP 1.1, 2 = SOAP 1.2)

The SOAP version is determined from the SOAP or XML message received. The version is automatically set before sending messages when SOAP 1.1 or SOAP 1.2 namespaces are defined in the `Namespace` table or when SOAP namespaces are omitted from the table. The version can be explicitly set or overruled by calling `soap_set_version`.

See also
  `soap::encodingStyle`, `soap_set_version`.

unsigned short soap::z_level

User-definable compression level for gzip compression (0=none, 1=fast to 9=best) default level is 6.

See also
  `WITH_GZIP`, `WITH_ZLIB`, `SOAP_ENC_ZLIB`, `soap::z_ratio_in`, `soap::z_ratio_out`.

float soap::z_ratio_in

The compression ratio = compressed.size/uncompressed.size of the compressed message received.

See also
  `WITH_GZIP`, `WITH_ZLIB`, `SOAP_ENC_ZLIB`, `soap::z_level`, `soap::z_ratio_out`.

float soap::z_ratio_out

The compression ratio = compressed.size/uncompressed.size of the compressed message sent.

See also
  `WITH_GZIP`, `WITH_ZLIB`, `SOAP_ENC_ZLIB`, `soap::z_level`, `soap::z_ratio_in`.