Genivia Home Documentation
HTTP cookie functions

updated Fri Oct 16 2020 by Robert van Engelen
 
HTTP cookie functions

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_cookiesoap_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_cookiesoap_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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie 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
soapsoap 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
soapsoap 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 = "/";
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
soapsoap context
namecookie name
valuecookie value to set
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
maxagethe age to live in seconds
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie 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
soapsoap context
namecookie name
domaincookie domain or NULL
pathcookie path or NULL