|  | Home | Documentation | HTTP cookie functions updated by Robert van Engelen |

HTTP cookie functions

This module describes 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.
int | soap_set_cookie_expire (struct soap *soap, const char *name, long maxage, const char *domain, const char *path)
| Set cookie expiration.
int | soap_set_cookie_secure (struct soap *soap, const char *name, const char *domain, const char *path)
| Set cookie secure.
int | soap_set_cookie_session (struct soap *soap, const char *name, const char *domain, const char *path)
| Set session cookie.
void | soap_clr_cookie (struct soap *soap, const char *name, const char *domain, const char *path)
| Clear cookie.
int | soap_clr_cookie_session (struct soap *soap, const char *name, const char *domain, const char *path)
| Clear session cookie.
struct soap_cookie * | soap_cookie (struct soap *soap, const char *name, const char *domain, const char *path)
| Find a cookie.
const char * | soap_cookie_value (struct soap *soap, const char *name, const char *domain, const char *path)
| Get cookie value.
time_t | soap_cookie_expire (struct soap *soap, const char *name, const char *domain, const char *path)
| Get cookie expiration.
int | soap_getenv_cookies (struct soap *soap)
| Get cookies from the HTTP_COOKIE environment variable.
void | soap_free_cookies (struct soap *soap)
| Free cookies.

## Detailed Description

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

This module describes 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

## ◆ soap_clr_cookie()

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

## ◆ soap_clr_cookie_session()

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

## ◆ soap_cookie()

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

## ◆ soap_cookie_expire()

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

## ◆ soap_cookie_value()

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

## ◆ soap_free_cookies()

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

## ◆ soap_getenv_cookies()

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

## ◆ soap_set_cookie()

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;
}
soap_set_cookie
struct soap_cookie * soap_set_cookie(struct soap *soap, const char *name, const char *value, const char *domain, const char *path)
Add a cookie.
soap_getenv_cookies
int soap_getenv_cookies(struct soap *soap)
Get cookies from the HTTP_COOKIE environment variable.
soap_set_cookie_expire
int soap_set_cookie_expire(struct soap *soap, const char *name, long maxage, const char *domain, const char *path)
Set cookie expiration.
soap_cookie_value
const char * soap_cookie_value(struct soap *soap, const char *name, const char *domain, const char *path)
Get cookie value.
SOAP_OK
#define SOAP_OK
The soap_status code for no error (zero).
Definition stdsoap2.h:2392
soap_serve
*Bind and listen to a port SOAP_SOCKET soap_bind *(struct soap *soap, const char *host, int port, int backlog) * @returns the ` Accept a connection with a client SOAP_SOCKET soap_accept *(struct soap *soap) * @returns the ` Serve a pending request in soap_serve)(struct soap *soap) * @returns `
Definition stdsoap2.h:7466
soap
Context with the engine state.
Definition stdsoap2.h:2929
soap::cookie_domain
const char * cookie_domain
User-definable string that specifies the HTTP cookie domain of the running server.
Definition stdsoap2.h:3094
soap::cookie_path
const char * cookie_path
User-definable string that specifies the HTTP cookie path of the running server.
Definition stdsoap2.h:3096

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

## ◆ soap_set_cookie_expire()

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

## ◆ soap_set_cookie_secure()

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

## ◆ soap_set_cookie_session()

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