Genivia - HTTP cookie functions

|  | Home | Documentation | HTTP cookie functions updated Mon Apr 22 2024 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Classes | Functions
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_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