2 Module N_HTTP_COOKIE
gullradriel edited this page 2026-10-29 20:54:40 +01:00

HTTP COOKIES: server-side Cookie reading and Set-Cookie building

Structures

Name
struct N_HTTP_SET_COOKIE
what a Set-Cookie should carry

Types

Name
enum N_HTTP_SAMESITE { N_HTTP_SAMESITE_UNSET = 0, N_HTTP_SAMESITE_STRICT = 2, N_HTTP_SAMESITE_NONE = 3, N_HTTP_SAMESITE_LAX = 1}
SameSite attribute of a Set-Cookie.

Functions

Name
int n_http_set_cookie_build(N_STR ** out, const N_HTTP_SET_COOKIE * c)
append a Set-Cookie header value (without "Set-Cookie: ")
const char * n_http_cookie_get(const char * header, size_t len, const char * name, size_t * value_len)
find a cookie in a Cookie header value
size_t n_http_cookie_count(const char * header, size_t len, const char * name)
count the pairs named name in a Cookie header value

Defines

Name
N_HTTP_COOKIE_SESSION
Max-Age value meaning "session cookie": neither Max-Age nor Expires is sent.

Types Documentation

enum N_HTTP_SAMESITE

Enumerator Value Description
N_HTTP_SAMESITE_UNSET 0 no SameSite attribute (browser default)
N_HTTP_SAMESITE_STRICT 2 SameSite=Strict.
N_HTTP_SAMESITE_NONE 3 SameSite=None, needs Secure.
N_HTTP_SAMESITE_LAX 1 SameSite=Lax.

SameSite attribute of a Set-Cookie.

Functions Documentation

int n_http_set_cookie_build(
    N_STR ** out,
    const N_HTTP_SET_COOKIE * c
)

append a Set-Cookie header value (without "Set-Cookie: ")

Parameters:

  • out destination, appended to (created when *out is NULL)
  • c what the cookie carries
  • out destination, appended to (created when *out is NULL)
  • c what the cookie carries

Return:

  • TRUE on success, FALSE on a refused cookie or allocation failure
  • TRUE on success, FALSE on a refused cookie or allocation failure

append a Set-Cookie header value, refusing anything that could break out of an attribute or that a browser would reject for its prefix

Attributes come in this order: Max-Age (and Expires when deleting), Path, Domain, Secure, HttpOnly, SameSite. Refused (FALSE, nothing appended): a name that is not a token, a value outside cookie-octets, an empty path or one with a control byte or ';', a domain outside [A-Za-z0-9.-], a negative max_age other than N_HTTP_COOKIE_SESSION, a "__Host-" cookie that is not Secure with Path=/ and no Domain, a "__Secure-" cookie that is not Secure, SameSite=None without Secure. append a Set-Cookie header value (without "Set-Cookie: ")

const char * n_http_cookie_get(
    const char * header,
    size_t len,
    const char * name,
    size_t * value_len
)

find a cookie in a Cookie header value

Parameters:

  • header the Cookie header value (may be NULL only when len is 0)
  • len its length
  • name the cookie name, case-sensitive
  • value_len receives the value length (may be NULL)
  • header the Cookie header value (may be NULL only when len is 0)
  • len its length
  • name the cookie name, case-sensitive
  • value_len receives the value length (may be NULL)

Return:

  • a pointer to the value inside header, or NULL when absent
  • a pointer to the value inside header, or NULL when absent

find a cookie in a Cookie header value (first occurrence wins)

Pairs are separated by ';' (spaces around them ignored). The FIRST pair with that exact name wins, as in PHP's $_COOKIE and as browsers order the most specific cookie first. Pairs whose name is not a token are skipped. The value is returned raw (quotes and percent escapes kept), not NUL-terminated. find a cookie in a Cookie header value

size_t n_http_cookie_count(
    const char * header,
    size_t len,
    const char * name
)

count the pairs named name in a Cookie header value

Parameters:

  • header the Cookie header value
  • len its length
  • name the cookie name, case-sensitive
  • header the Cookie header value
  • len its length
  • name the cookie name, case-sensitive

Return:

  • the count, 0 on a NULL argument
  • the count, 0 on a NULL argument

count the pairs named name in a Cookie header value

count the pairs named name in a Cookie header value

Macros Documentation

#define N_HTTP_COOKIE_SESSION (-1LL)

Max-Age value meaning "session cookie": neither Max-Age nor Expires is sent.