This module defines functions to set and get HTTP cookies at the server side. More...

Classes
struct	soap_cookie
	Cookie structure. More...

Functions
struct soap_cookie *	soap_set_cookie (struct soap soap, const char name, const char value, const char domain, const char *path)
	Add a cookie. More...

int	soap_set_cookie_expire (struct soap soap, const char name, long maxage, const char domain, const char path)
	Set cookie expiration. More...

int	soap_set_cookie_secure (struct soap soap, const char name, const char domain, const char path)
	Set cookie secure. More...

int	soap_set_cookie_session (struct soap soap, const char name, const char domain, const char path)
	Set session cookie. More...

void	soap_clr_cookie (struct soap soap, const char name, const char domain, const char path)
	Clear cookie. More...

int	soap_clr_cookie_session (struct soap soap, const char name, const char domain, const char path)
	Clear session cookie. More...

struct soap_cookie *	soap_cookie (struct soap soap, const char name, const char domain, const char path)
	Find a cookie. More...

const char *	soap_cookie_value (struct soap soap, const char name, const char domain, const char path)
	Get cookie value. More...

time_t	soap_cookie_expire (struct soap soap, const char name, const char domain, const char path)
	Get cookie expiration. More...

int	soap_getenv_cookies (struct soap *soap)
	Get cookies from the `HTTP_COOKIE` environment variable. More...

void	soap_free_cookies (struct soap *soap)
	Free cookies. More...

Detailed Description

This module defines functions to set and get HTTP cookies at the server side.

This module defines the cookie structure of cookies stored in the cookie store and server-side functions to set and inspect cookies. Cookie handling is fully automatic on the client side, when the engine is compiled with WITH_COOKIES. To avoid "cookie storms" caused by malicious servers that return an unreasonable amount of cookies, the size of the cookie store is limited to soap::cookie_max cookies. Each soap context has its own independent cookie store.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: The HTTP Server Session Management plugin documentation to use the HTTP session plugin to store a database of sessions to keep track of client data across multiple requests.

Function Documentation

void soap_clr_cookie	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Clear cookie.

This function deletes the specified cookie name from the cookie store at the server side. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

int soap_clr_cookie_session	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Clear session cookie.

This function clears the session property of the specified cookie name and updates the cookie store at the server side. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path. Returns SOAP_OK or a soap_status error code.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Returns: SOAP_OK or a soap_status error code

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

struct soap_cookie* soap_cookie	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Find a cookie.

This function returns the cookie structure of the specified cookie name or NULL when not found by searching the cookie store at the server side. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Returns: pointer to a soap_cookie structure or NULL when not found

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

time_t soap_cookie_expire	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Get cookie expiration.

This function returns the cookie expiration time time_t of the specified cookie name or -1 when not found by searching the cookie store at the server side. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Returns: cookie expiration time

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

const char* soap_cookie_value	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Get cookie value.

This function returns the cookie value of the specified cookie name or NULL when not found by searching the cookie store at the server side. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Returns: cookie value or NULL when not found

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

void soap_free_cookies ( struct soap * soap )

Free cookies.

This function frees the cookie store and deletes all cookies.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

Parameters

soap	`soap` context

int soap_getenv_cookies ( struct soap * soap )

Get cookies from the HTTP_COOKIE environment variable.

This function initializes the cookie store at the server side by reading the HTTP_COOKIE environment variable. This provides a means for a CGI application to read cookies sent by a client. Returns SOAP_OK or a soap_status error code when the HTTP_COOKIE variable was not found.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

Returns: SOAP_OK or a soap_status error code

Parameters

soap	`soap` context

struct soap_cookie* soap_set_cookie	(	struct soap *	soap,
		const char *	name,
		const char *	value,
		const char *	domain,
		const char *	path
	)

Add a cookie.

This function adds a cookie to the cookie store at the server side, if not already there, with the specified name and value. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path. Returns pointer to the cookie structure in the database or NULL when an error occurred.

Example:

// A CGI service with `::soap_serve` function generated by soapcpp2 from an interface file declaring a ns__webmethod function
#include "soapH.h"
int main()
{
  struct soap *soap = soap_new();
  soap->cookie_domain = "example.com";
  soap->cookie_path = "/";
  soap_getenv_cookies(soap);
  return soap_serve(soap);
}
// Define a ns__webmethod service operation with parameters that uses HTTP cookies to control state
int ns__webmethod(struct soap *soap, ...)
{
  const char *cookie_value = soap_cookie_value(soap, "cookie_name", NULL, NULL);
  if (cookie_value)
    ... // modify the cookie value to advance the state of this (otherwise stateless CGI) service
  else
    cookie_value = "initial_value";
  soap_set_cookie(soap, "cookie_name", cookie_value, NULL, NULL);
  soap_set_cookie_expire(soap, "cookie_name", 60, NULL, NULL); // cookie expires in 60 seconds
  ... // other webmethod logic
  return SOAP_OK;
}

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path, soap::cookie_max.

Returns: pointer to cookie or NULL when an error occurred

Parameters

soap	`soap` context
name	cookie name
value	cookie value to set
domain	cookie domain or NULL
path	cookie path or NULL

int soap_set_cookie_expire	(	struct soap *	soap,
		const char *	name,
		long	maxage,
		const char *	domain,
		const char *	path
	)

Set cookie expiration.

This function sets the expiration of the specified cookie name in seconds and updates the cookie store at the server side. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path. Returns SOAP_OK or a soap_status error code.

See also: soap::cookie_domain, soap::cookie_path.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

Returns: SOAP_OK or a soap_status error code

Parameters

soap	`soap` context
name	cookie name
maxage	the age to live in seconds
domain	cookie domain or NULL
path	cookie path or NULL

int soap_set_cookie_secure	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Set cookie secure.

This function sets the "secure" property of the specified cookie name and updates the cookie store at the server side. The "secure" property means that this cookie should be sent by the client to the server only when a secure HTTPS connection can be established. When HTTPS is enabled all cookies are sent by the server to the client with the "secure" property set, which means that this function is generally not needed unless the server is not HTTPS-enabled but cookies must be secure. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path. Returns SOAP_OK or a soap_status error code.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Returns: SOAP_OK or a soap_status error code

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

int soap_set_cookie_session	(	struct soap *	soap,
		const char *	name,
		const char *	domain,
		const char *	path
	)

Set session cookie.

This function makes the specified cookie name a "session cookie" and updates the cookie store at the server side by marking the cookie as a session cookie. This means that the cookie will be sent to clients that connect to the server. This function is not needed when a cookie is modified with soap_set_cookie_expire, for example, because modified cookies are always sent back to the client. The domain and path parameters can be specified or can be NULL to use the current domain and path given by soap::cookie_domain and soap::cookie_path. Returns SOAP_OK or a soap_status error code.

To enable HTTP cookies, the engine must be compiled with WITH_COOKIES.

See also: soap::cookie_domain, soap::cookie_path.

Returns: SOAP_OK or a soap_status error code

Parameters

soap	`soap` context
name	cookie name
domain	cookie domain or NULL
path	cookie path or NULL

Classes

Functions

Detailed Description

Function Documentation