Data Structures
struct	N_HTTP_RESP
	a response under construction (fields are private, use the functions) More...

Macros
#define	N_HTTP_RESPONSE_HEADERS_MAX 64
	most headers a response may carry
#define	N_HTTP_RESPONSE_VALUE_MAX 8192
	longest header value accepted, in bytes

Typedefs
typedef ssize_t(*	n_http_write_fn) (void ctx, const void buf, size_t len)
	a write function: write up to len bytes, return how many were written (at least 1) or -1 on a fatal error; partial writes are retried

Enumerations
enum	N_HTTP_RANGE { N_HTTP_RANGE_NONE = 0 , N_HTTP_RANGE_OK = 1 , N_HTTP_RANGE_UNSATISFIABLE = 2 }
	result of n_http_parse_range() More...

Functions
N_HTTP_RANGE	n_http_parse_range (const char value, size_t len, long long total, long long first, long long *last)
	interpret a Range header for a body of `total` bytes
int	n_http_response_add_header (N_HTTP_RESP r, const char name, const char *value)
	add a header line (repeats allowed, e.g.
int	n_http_response_append (N_HTTP_RESP r, const void data, size_t len)
	append bytes to the memory body (drops a file body)
long long	n_http_response_body_length (const N_HTTP_RESP *r)
	body length the response declares (Content-Length), 0 for a bodiless status
int	n_http_response_file (N_HTTP_RESP *r, int fd, long long offset, long long length)
	use a file range as the body; the response owns fd from now on (it is closed on free, also when this call fails) and drops any memory body
void	n_http_response_free (N_HTTP_RESP **r)
	free a response (closing its file body) and set *r to NULL
const char *	n_http_response_get_header (const N_HTTP_RESP r, const char name)
	value of the first header of that name (ASCII case-insensitive)
int	n_http_response_head (const N_HTTP_RESP r, N_STR *out)
	append the status line and headers, through the blank line
N_HTTP_RESP *	n_http_response_new (int status)
	new response with a status, keep-alive off, HTTP/1.1
size_t	n_http_response_remove_header (N_HTTP_RESP r, const char name)
	remove every header of that name (ASCII case-insensitive)
int	n_http_response_set_connection (N_HTTP_RESP *r, int keep_alive, int version_minor, int head_only)
	connection handling for this response
int	n_http_response_set_header (N_HTTP_RESP r, const char name, const char *value)
	set a header: remove every header of that name (ASCII case-insensitive), then add it; same refusals as add_header
int	n_http_response_set_status (N_HTTP_RESP *r, int status)
	change the status code
int	n_http_response_write (const N_HTTP_RESP r, n_http_write_fn fn, void ctx)
	write the whole response (head, then body unless HEAD or bodiless)
const char *	n_http_status_reason (int status)
	reason phrase of a status code ("Not Found"); a generic class phrase for an unlisted code, "" outside 100..599

Detailed Description

Data Structure Documentation

◆ N_HTTP_RESP

struct N_HTTP_RESP

a response under construction (fields are private, use the functions)

Examples: ex_http_response.c, and ex_http_server.c.

Definition at line 69 of file n_http_response.h.

Collaboration diagram for N_HTTP_RESP:

Data Fields
N_STR *	body	memory body, or NULL
int	fd	file body descriptor (owned, closed on free), or -1
long long	fd_length	file body length
long long	fd_offset	file body start offset
int	head_only	non-zero: send headers only (HEAD request)
int	keep_alive	non-zero: the connection stays open after this response
char *	names[64]	header names, nb_headers of them
size_t	nb_headers	number of headers
int	status	status code, 100..599
char *	values[64]	header values
int	version_minor	HTTP/1.x minor version of the request (0 or 1).

Macro Definition Documentation

◆ N_HTTP_RESPONSE_HEADERS_MAX

#define N_HTTP_RESPONSE_HEADERS_MAX 64

most headers a response may carry

Examples: ex_http_response.c.

Definition at line 60 of file n_http_response.h.

Referenced by n_http_response_add_header(), and test_headers().

◆ N_HTTP_RESPONSE_VALUE_MAX

#define N_HTTP_RESPONSE_VALUE_MAX 8192

longest header value accepted, in bytes

Definition at line 62 of file n_http_response.h.

Referenced by n_http_response_add_header().

Typedef Documentation

◆ n_http_write_fn

typedef ssize_t(* n_http_write_fn) (void *ctx, const void *buf, size_t len)

a write function: write up to len bytes, return how many were written (at least 1) or -1 on a fatal error; partial writes are retried

Definition at line 66 of file n_http_response.h.

Enumeration Type Documentation

◆ N_HTTP_RANGE

enum N_HTTP_RANGE

result of n_http_parse_range()

Enumerator
N_HTTP_RANGE_NONE	no usable Range: send the whole body (200)
N_HTTP_RANGE_OK	one satisfiable range: send 206
N_HTTP_RANGE_UNSATISFIABLE	send 416, with a Content-Range that gives only the total

Definition at line 194 of file n_http_response.h.

Function Documentation

◆ n_http_parse_range()

N_HTTP_RANGE n_http_parse_range	(	const char *	value,
		size_t	len,
		long long	total,
		long long *	first,
		long long *	last )

interpret a Range header for a body of total bytes

Only a single "bytes=a-b", "bytes=a-" or "bytes=-n" range is served; anything else (other units, several ranges, malformed) answers NONE so the full body goes out, which is always correct. A range starting at or past the end is UNSATISFIABLE.

Parameters

value	the Range header value (may be NULL: NONE)
len	its length
total	the full body length
first	receives the first byte (OK only)
last	receives the last byte, inclusive (OK only)

Returns: one of N_HTTP_RANGE

interpret a Range header for a body of total bytes

Parameters

value	the Range header value (may be NULL: NONE)
len	its length
total	the full body length
first	receives the first byte (OK only)
last	receives the last byte, inclusive (OK only)

Returns: one of N_HTTP_RANGE

Definition at line 601 of file n_http_response.c.

References _resp_num(), last, N_HTTP_RANGE_NONE, N_HTTP_RANGE_OK, and N_HTTP_RANGE_UNSATISFIABLE.

Referenced by test_range().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_add_header()

int n_http_response_add_header	(	N_HTTP_RESP *	r,
		const char *	name,
		const char *	value )

add a header line (repeats allowed, e.g.

Set-Cookie)

Refused: a name that is not a token; Content-Length, Transfer-Encoding and Connection (the builder's own); a value holding a control byte other than a tab, or longer than N_HTTP_RESPONSE_VALUE_MAX; more than N_HTTP_RESPONSE_HEADERS_MAX headers. Surrounding spaces of the value are trimmed.

Parameters

r	the response
name	header name
value	header value

Returns: TRUE, FALSE when refused

add a header line (repeats allowed, e.g.

Parameters

r	the response
name	header name
value	header value

Returns: TRUE, FALSE when refused

Definition at line 248 of file n_http_response.c.

References _resp_ieq(), _resp_token(), FreeNoLog, LOG_DEBUG, Malloc, N_HTTP_RESPONSE_HEADERS_MAX, N_HTTP_RESPONSE_VALUE_MAX, n_log, N_HTTP_RESP::names, N_HTTP_RESP::nb_headers, and N_HTTP_RESP::values.

Referenced by n_http_response_set_header(), test_headers(), and test_status().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_append()

int n_http_response_append	(	N_HTTP_RESP *	r,
		const void *	data,
		size_t	len )

append bytes to the memory body (drops a file body)

Parameters

r	the response
data	bytes (may be NULL only when len is 0)
len	number of bytes

Returns: TRUE, FALSE on a bad argument or allocation failure

Definition at line 380 of file n_http_response.c.

References _resp_drop_body(), N_HTTP_RESP::body, N_HTTP_RESP::fd, new_nstr(), and nstrcat_ex().

Referenced by _send_error(), handler(), test_headers(), test_status(), test_write(), and text().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_body_length()

long long n_http_response_body_length ( const N_HTTP_RESP * r )

body length the response declares (Content-Length), 0 for a bodiless status

Parameters

r	the response

Returns: the length, -1 on a NULL argument

body length the response declares (Content-Length), 0 for a bodiless status

Parameters

r	the response

Returns: the length, -1 on a NULL argument

Definition at line 438 of file n_http_response.c.

References _resp_bodiless(), N_HTTP_RESP::body, N_HTTP_RESP::fd, N_HTTP_RESP::fd_length, N_HTTP_RESP::status, and N_STR::written.

Referenced by n_http_response_head(), test_status(), and test_write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_file()

int n_http_response_file	(	N_HTTP_RESP *	r,
		int	fd,
		long long	offset,
		long long	length )

use a file range as the body; the response owns fd from now on (it is closed on free, also when this call fails) and drops any memory body

Parameters

r	the response
fd	an open, readable descriptor
offset	first byte
length	number of bytes from offset

Returns: TRUE, FALSE on a bad argument

use a file range as the body; the response owns fd from now on (it is closed on free, also when this call fails) and drops any memory body

Parameters

r	the response
fd	an open, readable descriptor
offset	first byte
length	number of bytes from offset

Returns: TRUE, FALSE on a bad argument (fd is closed then too)

Definition at line 403 of file n_http_response.c.

References _resp_drop_body(), N_HTTP_RESP::fd, N_HTTP_RESP::fd_length, and N_HTTP_RESP::fd_offset.

Referenced by test_write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_free()

void n_http_response_free ( N_HTTP_RESP ** r )

free a response (closing its file body) and set *r to NULL

Parameters

r	address of the response pointer (may point to NULL)

Definition at line 216 of file n_http_response.c.

References _resp_drop_body(), and FreeNoLog.

Referenced by _send_error(), _serve(), test_headers(), test_status(), and test_write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_get_header()

const char * n_http_response_get_header	(	const N_HTTP_RESP *	r,
		const char *	name )

value of the first header of that name (ASCII case-insensitive)

Parameters

r	the response
name	header name

Returns: the value, or NULL

Definition at line 363 of file n_http_response.c.

References _resp_ieq(), N_HTTP_RESP::names, N_HTTP_RESP::nb_headers, and N_HTTP_RESP::values.

Referenced by n_http_response_head(), and test_headers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_head()

int n_http_response_head	(	const N_HTTP_RESP *	r,
		N_STR **	out )

append the status line and headers, through the blank line

Parameters

r	the response
out	destination, appended to (created when *out is NULL)

Returns: TRUE, FALSE on a bad argument or allocation failure

Definition at line 463 of file n_http_response.c.

References _resp_bodiless(), _resp_cat(), free_nstr, h(), N_HTTP_RESP::keep_alive, line(), n_http_response_body_length(), n_http_response_get_header(), n_http_status_reason(), n_time_http_date(), N_TIME_HTTP_DATE_LEN, N_HTTP_RESP::names, N_HTTP_RESP::nb_headers, nstrcat_ex(), N_HTTP_RESP::status, N_HTTP_RESP::values, and N_HTTP_RESP::version_minor.

Referenced by head_is(), n_http_response_write(), test_headers(), and test_write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_new()

N_HTTP_RESP * n_http_response_new ( int status )

new response with a status, keep-alive off, HTTP/1.1

Parameters

status status code, 100..599

Returns: the response, NULL on a bad status or allocation failure

Definition at line 191 of file n_http_response.c.

References __n_assert, N_HTTP_RESP::fd, Malloc, N_HTTP_RESP::status, and N_HTTP_RESP::version_minor.

Referenced by _send_error(), _serve(), handler(), test_headers(), test_status(), test_write(), and text().

Here is the caller graph for this function:

◆ n_http_response_remove_header()

size_t n_http_response_remove_header	(	N_HTTP_RESP *	r,
		const char *	name )

remove every header of that name (ASCII case-insensitive)

Parameters

r	the response
name	header name

Returns: the number removed

Definition at line 295 of file n_http_response.c.

References _resp_ieq(), FreeNoLog, N_HTTP_RESP::names, N_HTTP_RESP::nb_headers, and N_HTTP_RESP::values.

Referenced by test_headers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_set_connection()

int n_http_response_set_connection	(	N_HTTP_RESP *	r,
		int	keep_alive,
		int	version_minor,
		int	head_only )

connection handling for this response

Parameters

r	the response
keep_alive	non-zero to keep the connection open
version_minor	the request's HTTP/1.x minor version (0 or 1)
head_only	non-zero for a HEAD request

Returns: TRUE, FALSE on a bad argument

Definition at line 424 of file n_http_response.c.

References N_HTTP_RESP::head_only, N_HTTP_RESP::keep_alive, and N_HTTP_RESP::version_minor.

Referenced by _send_error(), _serve(), test_headers(), test_status(), and test_write().

Here is the caller graph for this function:

◆ n_http_response_set_header()

int n_http_response_set_header	(	N_HTTP_RESP *	r,
		const char *	name,
		const char *	value )

set a header: remove every header of that name (ASCII case-insensitive), then add it; same refusals as add_header

Parameters

r	the response
name	header name
value	header value

Returns: TRUE, FALSE when refused

set a header: remove every header of that name (ASCII case-insensitive), then add it; same refusals as add_header

Parameters

r	the response
name	header name
value	header value

Returns: TRUE, FALSE when refused (the old headers are kept then)

Definition at line 325 of file n_http_response.c.

References _resp_ieq(), FreeNoLog, n_http_response_add_header(), N_HTTP_RESP::names, N_HTTP_RESP::nb_headers, and N_HTTP_RESP::values.

Referenced by _send_error(), test_headers(), test_status(), and text().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_response_set_status()

int n_http_response_set_status	(	N_HTTP_RESP *	r,
		int	status )

change the status code

Parameters

r	the response
status	100..599

Returns: TRUE, FALSE on a bad argument

Definition at line 234 of file n_http_response.c.

References N_HTTP_RESP::status.

Referenced by test_status().

Here is the caller graph for this function:

◆ n_http_response_write()

int n_http_response_write	(	const N_HTTP_RESP *	r,
		n_http_write_fn	fn,
		void *	ctx )

write the whole response (head, then body unless HEAD or bodiless)

Partial writes are continued; a file body is read in chunks from its offset. Stops at the first write error or short file.

Parameters

r	the response
fn	the write function
ctx	passed to fn

Returns: TRUE when every byte was written, FALSE otherwise

Parameters

r	the response
fn	the write function
ctx	passed to fn

Returns: TRUE when every byte was written, FALSE otherwise

Definition at line 539 of file n_http_response.c.

References __n_assert, _resp_bodiless(), _resp_pread(), _resp_write_all(), N_HTTP_RESP::body, N_STR::data, done, N_HTTP_RESP::fd, N_HTTP_RESP::fd_length, N_HTTP_RESP::fd_offset, Free, free_nstr, N_HTTP_RESP::head_only, LOG_DEBUG, Malloc, N_HTTP_RESPONSE_CHUNK, n_http_response_head(), n_log, N_HTTP_RESP::status, and N_STR::written.

Referenced by _send_error(), _serve(), test_status(), and test_write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_http_status_reason()

const char * n_http_status_reason ( int status )

reason phrase of a status code ("Not Found"); a generic class phrase for an unlisted code, "" outside 100..599

Parameters

status the status code

Returns: a static string

reason phrase of a status code ("Not Found"); a generic class phrase for an unlisted code, "" outside 100..599

Parameters

status the status code

Returns: a static string, "" outside 100..599

Definition at line 52 of file n_http_response.c.

Referenced by _send_error(), n_http_response_head(), and test_status().

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ N_HTTP_RESP

Macro Definition Documentation

◆ N_HTTP_RESPONSE_HEADERS_MAX

◆ N_HTTP_RESPONSE_VALUE_MAX

Typedef Documentation

◆ n_http_write_fn

Enumeration Type Documentation

◆ N_HTTP_RANGE

Function Documentation

◆ n_http_parse_range()

◆ n_http_response_add_header()

◆ n_http_response_append()

◆ n_http_response_body_length()

◆ n_http_response_file()

◆ n_http_response_free()

◆ n_http_response_get_header()

◆ n_http_response_head()

◆ n_http_response_new()

◆ n_http_response_remove_header()

◆ n_http_response_set_connection()

◆ n_http_response_set_header()

◆ n_http_response_set_status()

◆ n_http_response_write()

◆ n_http_status_reason()