Collaboration diagram for HTTP Protocol Handling:

Data Structures
struct	etag_rec
	A structure with the ingredients for a file based etag. More...

struct	ap_bucket_error
	A bucket referring to an HTTP error. More...

Macros
#define	AP_METHOD_CHECK_ALLOWED(mask, methname) ((mask) & (AP_METHOD_BIT << ap_method_number_of((methname))))

#define	AP_GET_BASIC_AUTH_PW_NOTE "AP_GET_BASIC_AUTH_PW_NOTE"

#define	AP_GETLINE_FOLD (1 << 0) /* Whether to merge continuation lines */

#define	AP_GETLINE_CRLF (1 << 1) /* Whether line ends must be CRLF */

#define	AP_GETLINE_NOSPC_EOL

#define	AP_GETLINE_NONBLOCK (1 << 3) /* Whether to read non-blocking */

#define	AP_PROTOCOL_HTTP1 "http/1.1"

#define	AP_BUCKET_IS_ERROR(e) (e->type == &ap_bucket_type_error)

Typedefs
typedef struct etag_rec	etag_rec

typedef struct ap_bucket_error	ap_bucket_error

Enumerations
enum	ap_condition_e { AP_CONDITION_NONE, AP_CONDITION_NOMATCH, AP_CONDITION_WEAK, AP_CONDITION_STRONG }

Functions
request_rec *	ap_create_request (conn_rec *c)

request_rec *	ap_read_request (conn_rec *c)

int	ap_parse_request_line (request_rec *r)

int	ap_check_request_header (request_rec *r)

void	ap_get_mime_headers (request_rec *r)

void	ap_get_mime_headers_core (request_rec r, apr_bucket_brigade bb)

void	ap_finalize_request_protocol (request_rec *r)

void	ap_send_error_response (request_rec *r, int recursive_error)

void	ap_set_content_length (request_rec *r, apr_off_t length)

int	ap_set_keepalive (request_rec *r)

apr_time_t	ap_rationalize_mtime (request_rec *r, apr_time_t mtime)

const char *	ap_make_content_type (request_rec r, const char type)

void	ap_setup_make_content_type (apr_pool_t *pool)

char *	ap_make_etag (request_rec *r, int force_weak)

char *	ap_make_etag_ex (request_rec r, etag_rec er)

void	ap_set_etag (request_rec *r)

void	ap_set_etag_fd (request_rec r, apr_file_t fd)

void	ap_set_last_modified (request_rec *r)

ap_condition_e	ap_condition_if_match (request_rec r, apr_table_t headers)

ap_condition_e	ap_condition_if_unmodified_since (request_rec r, apr_table_t headers)

ap_condition_e	ap_condition_if_none_match (request_rec r, apr_table_t headers)

ap_condition_e	ap_condition_if_modified_since (request_rec r, apr_table_t headers)

ap_condition_e	ap_condition_if_range (request_rec r, apr_table_t headers)

int	ap_meets_conditions (request_rec *r)

apr_status_t	ap_send_fd (apr_file_t fd, request_rec r, apr_off_t offset, apr_size_t length, apr_size_t *nbytes)

apr_size_t	ap_send_mmap (apr_mmap_t mm, request_rec r, apr_size_t offset, apr_size_t length)

int	ap_method_register (apr_pool_t p, const char methname)

void	ap_method_registry_init (apr_pool_t *p)

ap_method_list_t *	ap_make_method_list (apr_pool_t *p, int nelts)

void	ap_copy_method_list (ap_method_list_t dest, ap_method_list_t src)

int	ap_method_in_list (ap_method_list_t l, const char method)

void	ap_method_list_add (ap_method_list_t l, const char method)

void	ap_method_list_remove (ap_method_list_t l, const char method)

void	ap_clear_method_list (ap_method_list_t *l)

void	ap_set_content_type (request_rec r, const char ct)

void	ap_set_accept_ranges (request_rec *r)

int	ap_rputc (int c, request_rec *r)

int	ap_rwrite (const void buf, int nbyte, request_rec r)

int	ap_rvputs (request_rec *r,...) AP_FN_ATTR_SENTINEL

int	ap_vrprintf (request_rec r, const char fmt, va_list vlist)

int	ap_rprintf (request_rec r, const char fmt,...) __attribute__((format(printf

int int	ap_rflush (request_rec *r)

int	ap_index_of_response (int status)

const char *	ap_get_status_line (int status)

const char *	ap_get_status_line_ex (apr_pool_t *p, int status)

int	ap_setup_client_block (request_rec *r, int read_policy)

int	ap_should_client_block (request_rec *r)

long	ap_get_client_block (request_rec r, char buffer, apr_size_t bufsiz)

int	ap_map_http_request_error (apr_status_t rv, int status)

int	ap_discard_request_body (request_rec *r)

void	ap_note_auth_failure (request_rec *r)

void	ap_note_basic_auth_failure (request_rec *r)

void	ap_note_digest_auth_failure (request_rec *r)

int	note_auth_failure (request_rec r, const char auth_type)

int	ap_get_basic_auth_pw (request_rec r, const char *pw)

apr_status_t	ap_get_basic_auth_components (const request_rec r, const char username, const char *password)

void	ap_parse_uri (request_rec r, const char uri)

int	ap_getline (char s, int n, request_rec r, int flags)

apr_status_t	ap_fgetline (char *s, apr_size_t n, apr_size_t read, ap_filter_t f, int flags, apr_bucket_brigade bb, apr_pool_t *p)

apr_status_t	ap_rgetline (char *s, apr_size_t n, apr_size_t read, request_rec r, int flags, apr_bucket_brigade bb)

int	ap_method_number_of (const char *method)

const char *	ap_method_name_of (apr_pool_t *p, int methnum)

void	pre_read_request (request_rec r, conn_rec c)

int	post_read_request (request_rec *r)

int	log_transaction (request_rec *r)

const char *	http_scheme (const request_rec *r)

apr_port_t	default_port (const request_rec *r)

int	protocol_propose (conn_rec c, request_rec r, server_rec s, const apr_array_header_t offers, apr_array_header_t *proposals)

int	protocol_switch (conn_rec c, request_rec r, server_rec s, const char protocol)

const char *	protocol_get (const conn_rec *c)

apr_status_t	ap_get_protocol_upgrades (conn_rec c, request_rec r, server_rec s, int report_all, const apr_array_header_t *pupgrades)

const char *	ap_select_protocol (conn_rec c, request_rec r, server_rec s, const apr_array_header_t choices)

apr_status_t	ap_switch_protocol (conn_rec c, request_rec r, server_rec s, const char protocol)

const char *	ap_get_protocol (conn_rec *c)

int	ap_is_allowed_protocol (conn_rec c, request_rec r, server_rec s, const char protocol)

apr_bucket *	ap_bucket_error_make (apr_bucket b, int error, const char buf, apr_pool_t *p)

apr_bucket *	ap_bucket_error_create (int error, const char buf, apr_pool_t p, apr_bucket_alloc_t *list)

apr_status_t	ap_byterange_filter (ap_filter_t f, apr_bucket_brigade b)

apr_status_t	ap_http_header_filter (ap_filter_t f, apr_bucket_brigade b)

apr_status_t	ap_content_length_filter (ap_filter_t , apr_bucket_brigade )

apr_status_t	ap_old_write_filter (ap_filter_t f, apr_bucket_brigade b)

void	ap_set_sub_req_protocol (request_rec rnew, const request_rec r)

void	ap_finalize_sub_req_protocol (request_rec *sub_r)

void	ap_send_interim_response (request_rec *r, int send_headers)

Variables
AP_DECLARE_DATA ap_filter_rec_t *	ap_old_write_func

AP_DECLARE_DATA const apr_bucket_type_t	ap_bucket_type_error

Detailed Description

Macro Definition Documentation

#define AP_BUCKET_IS_ERROR ( e ) (e->type == &ap_bucket_type_error)

Determine if a bucket is an error bucket

Parameters

e	The bucket to inspect

Returns: true or false

#define AP_GET_BASIC_AUTH_PW_NOTE "AP_GET_BASIC_AUTH_PW_NOTE"

#define AP_GETLINE_CRLF (1 << 1) /* Whether line ends must be CRLF */

#define AP_GETLINE_FOLD (1 << 0) /* Whether to merge continuation lines */

#define AP_GETLINE_NONBLOCK (1 << 3) /* Whether to read non-blocking */

#define AP_GETLINE_NOSPC_EOL

Value:

(1 << 2) /* Whether to consume up to and including

the end of line on APR_ENOSPC */

#define AP_METHOD_CHECK_ALLOWED	(	mask,
		methname
	)	((mask) & (AP_METHOD_BIT << ap_method_number_of((methname))))

This is a convenience macro to ease with checking a mask against a method name.

#define AP_PROTOCOL_HTTP1 "http/1.1"

Typedef Documentation

typedef struct ap_bucket_error ap_bucket_error

See Also: ap_bucket_type_error

typedef struct etag_rec etag_rec

A structure with the ingredients for a file based etag

Enumeration Type Documentation

enum ap_condition_e

Enumerator
AP_CONDITION_NONE
AP_CONDITION_NOMATCH
AP_CONDITION_WEAK
AP_CONDITION_STRONG

Function Documentation

apr_bucket* ap_bucket_error_create	(	int	error,
		const char *	buf,
		apr_pool_t *	p,
		apr_bucket_alloc_t *	list
	)

Create a bucket referring to an HTTP error.

Parameters

error	The HTTP error code to put in the bucket.
buf	An optional error string to put in the bucket.
p	A pool to allocate the error string out of.
list	The bucket allocator from which to allocate the bucket

Returns: The new bucket, or NULL if allocation failed

apr_bucket* ap_bucket_error_make	(	apr_bucket *	b,
		int	error,
		const char *	buf,
		apr_pool_t *	p
	)

Make the bucket passed in an error bucket

Parameters

b	The bucket to make into an error bucket
error	The HTTP error code to put in the bucket.
buf	An optional error string to put in the bucket.
p	A pool to allocate out of.

Returns: The new bucket, or NULL if allocation failed

apr_status_t ap_byterange_filter	(	ap_filter_t *	f,
		apr_bucket_brigade *	b
	)

int ap_check_request_header ( request_rec * r )

Validate the request header and select vhost.

Parameters

r	The current request

Returns: 1 on success, 0 on failure

void ap_clear_method_list ( ap_method_list_t * l )

Reset a method list to be completely empty.

Parameters

l	Pointer to a method list, such as r->allowed_methods.

Returns: None.

ap_condition_e ap_condition_if_match	(	request_rec *	r,
		apr_table_t *	headers
	)

Tests conditional request rules for the If-Match header.

Parameters

r	The current request
headers	The response headers to check against

Returns: AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_STRONG for a strong match. Weak matches are not permitted for the If-Match header.

ap_condition_e ap_condition_if_modified_since	(	request_rec *	r,
		apr_table_t *	headers
	)

Tests conditional request rules for the If-Modified-Since header.

Parameters

r	The current request
headers	The response headers to check against

Returns: AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_WEAK if a weak match was present and allowed by RFC2616, AP_CONDITION_STRONG for a strong match.

ap_condition_e ap_condition_if_none_match	(	request_rec *	r,
		apr_table_t *	headers
	)

Tests conditional request rules for the If-None-Match header.

Parameters

r	The current request
headers	The response headers to check against

Returns: AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_WEAK if a weak match was present and allowed by RFC2616, AP_CONDITION_STRONG for a strong match.

ap_condition_e ap_condition_if_range	(	request_rec *	r,
		apr_table_t *	headers
	)

Tests conditional request rules for the If-Range header.

Parameters

r	The current request
headers	The response headers to check against

Returns: AP_CONDITION_NONE if either the If-Range or Range header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_STRONG for a strong match. Weak matches are not permitted for the If-Range header.

ap_condition_e ap_condition_if_unmodified_since	(	request_rec *	r,
		apr_table_t *	headers
	)

Tests conditional request rules for the If-Unmodified-Since header.

Parameters

r	The current request
headers	The response headers to check against

Returns: AP_CONDITION_NONE if the header is missing, AP_CONDITION_NOMATCH if the header does not match, AP_CONDITION_WEAK if a weak match was present and allowed by RFC2616, AP_CONDITION_STRONG for a strong match.

apr_status_t ap_content_length_filter	(	ap_filter_t *	,
		apr_bucket_brigade *
	)

void ap_copy_method_list	(	ap_method_list_t *	dest,
		ap_method_list_t *	src
	)

Copy a method list

Parameters

dest	List to copy to
src	List to copy from

request_rec* ap_create_request ( conn_rec * c )

Read an empty request and set reasonable defaults.

Parameters

c	The current connection

Returns: The new request_rec

int ap_discard_request_body ( request_rec * r )

In HTTP/1.1, any method can have a body. However, most GET handlers wouldn't know what to do with a request body if they received one. This helper routine tests for and reads any message body in the request, simply discarding whatever it receives. We need to do this because failing to read the request body would cause it to be interpreted as the next request on a persistent connection.

Parameters

r	The current request

Returns: error status if request is malformed, OK otherwise

apr_status_t ap_fgetline	(	char **	s,
		apr_size_t	n,
		apr_size_t *	read,
		ap_filter_t *	f,
		int	flags,
		apr_bucket_brigade *	bb,
		apr_pool_t *	p
	)

Get the next line from an input filter

Parameters

s	Pointer to the pointer to the buffer into which the line should be read; if *s==NULL, a buffer of the necessary size to hold the data will be allocated from `p`
n	The size of the buffer
read	The length of the line.
f	Input filter to read from
flags	Bit mask of AP_GETLINE_* options
bb	Working brigade to use when reading buckets
p	The pool to allocate the buffer from (if needed)

Returns: APR_SUCCESS, if successful APR_ENOSPC, if the line is too big to fit in the buffer Other errors where appropriate

void ap_finalize_request_protocol ( request_rec * r )

Called at completion of sending the response. It sends the terminating protocol information.

Parameters

r	The current request

void ap_finalize_sub_req_protocol ( request_rec * sub_r )

A wrapup function to keep the internal accounting straight. Indicates that there is no more content coming.

Parameters

sub_r Subrequest that is now compete

apr_status_t ap_get_basic_auth_components	(	const request_rec *	r,
		const char **	username,
		const char **	password
	)

Get the username and/or password from the request's Basic authentication headers. Unlike ap_get_basic_auth_pw(), calling this function has no side effects on the passed request_rec.

Parameters

r	The current request
username	If not NULL, set to the username sent by the client
password	If not NULL, set to the password sent by the client

Returns: APR_SUCCESS if the credentials were successfully parsed and returned; APR_EINVAL if there was no authentication header sent or if the client was not using the Basic authentication scheme. username and password are unchanged on failure.

int ap_get_basic_auth_pw	(	request_rec *	r,
		const char **	pw
	)

Get the password from the request headers. This function has multiple side effects due to its prior use in the old authentication framework, including setting r->user (which is supposed to indicate that the user in question has been authenticated for the current request).

Modules which call ap_get_basic_auth_pw() during the authentication phase MUST either immediately authenticate the user after the call, or else stop the request immediately with an error response, to avoid incorrectly authenticating the current request. (See CVE-2017-3167.) The replacement ap_get_basic_auth_components() API should be preferred.

Deprecated:

See Also: ap_get_basic_auth_components

Parameters

r	The current request
pw	The password as set in the headers

Returns: 0 (OK) if it set the 'pw' argument (and assured a correct value in r->user); otherwise it returns an error code, either HTTP_INTERNAL_SERVER_ERROR if things are really confused, HTTP_UNAUTHORIZED if no authentication at all seemed to be in use, or DECLINED if there was authentication but it wasn't Basic (in which case, the caller should presumably decline as well).

long ap_get_client_block	(	request_rec *	r,
		char *	buffer,
		apr_size_t	bufsiz
	)

Call this in a loop. It will put data into a buffer and return the length of the input block

Parameters

r	The current request
buffer	The buffer in which to store the data
bufsiz	The size of the buffer

Returns: Number of bytes inserted into the buffer. When done reading, 0 if EOF, or -1 if there was an error

void ap_get_mime_headers ( request_rec * r )

Read the mime-encoded headers.

Parameters

r	The current request

void ap_get_mime_headers_core	(	request_rec *	r,
		apr_bucket_brigade *	bb
	)

Optimized version of ap_get_mime_headers() that requires a temporary brigade to work with

Parameters

r	The current request
bb	temp brigade

const char* ap_get_protocol ( conn_rec * c )

Call the protocol_get hook to determine the protocol currently in use for the given connection.

Unless another protocol has been switch to, will default to

See Also: AP_PROTOCOL_HTTP1 and modules implementing a new protocol must report a switched connection via the protocol_get hook.

Parameters

c	The connection to determine the protocol for

Returns: the protocol in use, never NULL

apr_status_t ap_get_protocol_upgrades	(	conn_rec *	c,
		request_rec *	r,
		server_rec *	s,
		int	report_all,
		const apr_array_header_t **	pupgrades
	)

Get the protocols that the connection and optional request may upgrade to - besides the protocol currently active on the connection. These values may be used to announce to a client what choices it has.

If report_all == 0, only protocols more preferable than the one currently being used, are reported. Otherwise, all available protocols beside the current one are being reported.

Parameters

c	The current connection
r	The current request or NULL
s	The server/virtual host selected or NULL
report_all	include also protocols less preferred than the current one
pupgrades	on return, possible protocols to upgrade to in descending order of preference. Maybe NULL if none are available.

const char* ap_get_status_line ( int status )

Return the Status-Line for a given status code (excluding the HTTP-Version field). If an invalid or unknown status code is passed, "500 Internal Server Error" will be returned.

Parameters

status The HTTP status code

Returns: The Status-Line

const char* ap_get_status_line_ex	(	apr_pool_t *	p,
		int	status
	)

Return the Status-Line for a given status code (excluding the HTTP-Version field). If an invalid status code is passed, "500 Internal Server Error" will be returned, whereas an unknown status will be returned like "xxx Status xxx".

Parameters

p	The pool to allocate from when status is unknown
status	The HTTP status code

Returns: The Status-Line

int ap_getline	(	char *	s,
		int	n,
		request_rec *	r,
		int	flags
	)

Get the next line of input for the request

Parameters

s	The buffer into which to read the line
n	The size of the buffer
r	The request
flags	Bit mask of AP_GETLINE_* options

Returns: The length of the line, if successful n, if the line is too big to fit in the buffer -1 for miscellaneous errors

apr_status_t ap_http_header_filter	(	ap_filter_t *	f,
		apr_bucket_brigade *	b
	)

int ap_index_of_response ( int status )

Index used in custom_responses array for a specific error code (only use outside protocol.c is in getting them configured).

Parameters

status HTTP status code

Returns: The index of the response

int ap_is_allowed_protocol	(	conn_rec *	c,
		request_rec *	r,
		server_rec *	s,
		const char *	protocol
	)

Check if the given protocol is an allowed choice on the given combination of connection, request and server.

When server is NULL, it is taken from request_rec, unless request_rec is NULL. Then it is taken from the connection base server.

Parameters

c	The current connection
r	The current request or NULL
s	The server/virtual host selected or NULL
protocol	the protocol to switch to

Returns: != 0 iff protocol is allowed

const char* ap_make_content_type	(	request_rec *	r,
		const char *	type
	)

Build the content-type that should be sent to the client from the content-type specified. The following rules are followed:

if type is NULL or "", return NULL (do not set content-type).
if charset adding is disabled, stop processing and return type.
then, if there are no parameters on type, add the default charset
return type
Parameters

r The current request

type The content type

Returns
The content-type

char* ap_make_etag	(	request_rec *	r,
		int	force_weak
	)

Construct an entity tag from the resource information. If it's a real file, build in some of the file characteristics.

Parameters

r	The current request
force_weak	Force the entity tag to be weak - it could be modified again in as short an interval.

Returns: The entity tag

char* ap_make_etag_ex	(	request_rec *	r,
		etag_rec *	er
	)

Construct an entity tag from information provided in the etag_rec structure.

Parameters

r	The current request
er	The etag record, containing ingredients for the etag.

ap_method_list_t* ap_make_method_list	(	apr_pool_t *	p,
		int	nelts
	)

Create a new method list with the specified number of preallocated slots for extension methods.

Parameters

p	Pointer to a pool in which the structure should be allocated.
nelts	Number of preallocated extension slots

Returns: Pointer to the newly created structure.

int ap_map_http_request_error	(	apr_status_t	rv,
		int	status
	)

Map specific APR codes returned by the filter stack to HTTP error codes, or the default status code provided. Use it as follows:

return ap_map_http_request_error(rv, HTTP_BAD_REQUEST);

If the filter has already handled the error, AP_FILTER_ERROR will be returned, which is cleanly passed through.

These mappings imply that the filter stack is reading from the downstream client, the proxy will map these codes differently.

Parameters

rv	APR status code
status	Default HTTP code should the APR code not be recognised

Returns: Mapped HTTP status code

int ap_meets_conditions ( request_rec * r )

Implements condition GET rules for HTTP/1.1 specification. This function inspects the client headers and determines if the response fulfills the requirements specified.

Parameters

r	The current request

Returns: OK if the response fulfills the condition GET rules, some other status code otherwise

int ap_method_in_list	(	ap_method_list_t *	l,
		const char *	method
	)

Search for an HTTP method name in an ap_method_list_t structure, and return true if found.

Parameters

method	String containing the name of the method to check.
l	Pointer to a method list, such as r->allowed_methods.

Returns: 1 if method is in the list, otherwise 0

void ap_method_list_add	(	ap_method_list_t *	l,
		const char *	method
	)

Add an HTTP method name to an ap_method_list_t structure if it isn't already listed.

Parameters

method	String containing the name of the method to check.
l	Pointer to a method list, such as r->allowed_methods.

Returns: None.

void ap_method_list_remove	(	ap_method_list_t *	l,
		const char *	method
	)

Remove an HTTP method name from an ap_method_list_t structure.

Parameters

l	Pointer to a method list, such as r->allowed_methods.
method	String containing the name of the method to remove.

Returns: None.

const char* ap_method_name_of	(	apr_pool_t *	p,
		int	methnum
	)

Get the method name associated with the given internal method number. Returns NULL if not recognized.

Parameters

p	A pool to use for temporary allocations.
methnum	An integer value corresponding to an internal method number

Returns: The name corresponding to the method number

int ap_method_number_of ( const char * method )

Get the method number associated with the given string, assumed to contain an HTTP method. Returns M_INVALID if not recognized.

Parameters

method A string containing a valid HTTP method

Returns: The method number

int ap_method_register	(	apr_pool_t *	p,
		const char *	methname
	)

Register a new request method, and return the offset that will be associated with that method.

Parameters

p	The pool to create registered method numbers from.
methname	The name of the new method to register.

Returns: An int value representing an offset into a bitmask.

void ap_method_registry_init ( apr_pool_t * p )

Initialize the method_registry and allocate memory for it.

Parameters

p	Pool to allocate memory for the registry from.

void ap_note_auth_failure ( request_rec * r )

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed.

Parameters

r	The current request

void ap_note_basic_auth_failure ( request_rec * r )

Deprecated:

See Also: ap_note_auth_failure

void ap_note_digest_auth_failure ( request_rec * r )

Deprecated:

See Also: ap_note_auth_failure

apr_status_t ap_old_write_filter	(	ap_filter_t *	f,
		apr_bucket_brigade *	b
	)

int ap_parse_request_line ( request_rec * r )

Parse and validate the request line.

Parameters

r	The current request

Returns: 1 on success, 0 on failure

void ap_parse_uri	(	request_rec *	r,
		const char *	uri
	)

parse_uri: break apart the uri

Warning

Side Effects:

sets r->args to rest after '?' (or NULL if no '?')
sets r->uri to request uri (without r->args part)
sets r->hostname (if not set already) from request (scheme://host:port)

Parameters

r	The current request
uri	The uri to break apart

apr_time_t ap_rationalize_mtime	(	request_rec *	r,
		apr_time_t	mtime
	)

Return the latest rational time from a request/mtime pair. Mtime is returned unless it's in the future, in which case we return the current time.

Parameters

r	The current request
mtime	The last modified time

Returns: the latest rational time.

request_rec* ap_read_request ( conn_rec * c )

Read a request and fill in the fields.

Parameters

c	The current connection

Returns: The new request_rec

int int ap_rflush ( request_rec * r )

Flush all of the data for the current request to the client

Parameters

r	The current request

Returns: 0 on success, -1 if an error occurred

apr_status_t ap_rgetline	(	char **	s,
		apr_size_t	n,
		apr_size_t *	read,
		request_rec *	r,
		int	flags,
		apr_bucket_brigade *	bb
	)

See Also: ap_fgetline

Note: genuinely calls, ap_fgetline(s, n, read, r->proto_input_filters, flags, bb, r->pool)

int ap_rprintf	(	request_rec *	r,
		const char *	fmt,
			...
	)

Output data to the client in a printf format

Parameters

r	The current request
fmt	The format string
...	The arguments to use to fill out the format string

Returns: The number of bytes sent

int ap_rputc	(	int	c,
		request_rec *	r
	)

Output one character for this request

Parameters

c	the character to output
r	the current request

Returns: The number of bytes sent

int ap_rvputs	(	request_rec *	r,
			...
	)

Write an unspecified number of strings to the request

Parameters

r	The current request
...	The strings to write

Returns: The number of bytes sent

int ap_rwrite	(	const void *	buf,
		int	nbyte,
		request_rec *	r
	)

Write a buffer for the current request

Parameters

buf	The buffer to write
nbyte	The number of bytes to send from the buffer
r	The current request

Returns: The number of bytes sent

const char* ap_select_protocol	(	conn_rec *	c,
		request_rec *	r,
		server_rec *	s,
		const apr_array_header_t *	choices
	)

Select a protocol for the given connection and optional request. Will return the protocol identifier selected which may be the protocol already in place on the connection. The selected protocol will be NULL if non of the given choices could be agreed upon (e.g. no proposal as made).

A special case is where the choices itself is NULL (instead of empty). In this case there are no restrictions imposed on protocol selection.

Parameters

c	The current connection
r	The current request or NULL
s	The server/virtual host selected
choices	A list of protocol identifiers, normally the client's wishes

Returns: The selected protocol or NULL if no protocol could be agreed upon

void ap_send_error_response	(	request_rec *	r,
		int	recursive_error
	)

Send error back to client.

Parameters

r	The current request
recursive_error	last arg indicates error status in case we get an error in the process of trying to deal with an ErrorDocument to handle some other error. In that case, we print the default report for the first thing that went wrong, and more briefly report on the problem with the ErrorDocument.

apr_status_t ap_send_fd	(	apr_file_t *	fd,
		request_rec *	r,
		apr_off_t	offset,
		apr_size_t	length,
		apr_size_t *	nbytes
	)

Send an entire file to the client, using sendfile if supported by the current platform

Parameters

fd	The file to send.
r	The current request
offset	Offset into the file to start sending.
length	Amount of data to send
nbytes	Amount of data actually sent

void ap_send_interim_response	(	request_rec *	r,
		int	send_headers
	)

Send an interim (HTTP 1xx) response immediately.

Parameters

r	The request
send_headers	Whether to send&clear headers in r->headers_out

apr_size_t ap_send_mmap	(	apr_mmap_t *	mm,
		request_rec *	r,
		apr_size_t	offset,
		apr_size_t	length
	)

Send an MMAP'ed file to the client

Parameters

mm	The MMAP'ed file to send
r	The current request
offset	The offset into the MMAP to start sending
length	The amount of data to send

Returns: The number of bytes sent

void ap_set_accept_ranges ( request_rec * r )

Set the Accept-Ranges header for this response

Parameters

r	The current request

void ap_set_content_length	(	request_rec *	r,
		apr_off_t	length
	)

Set the content length for this request

Parameters

r	The current request
length	The new content length

void ap_set_content_type	(	request_rec *	r,
		const char *	ct
	)

Set the content type for this request (r->content_type).

Parameters

r	The current request
ct	The new content type

Warning: This function must be called to set r->content_type in order for the AddOutputFilterByType directive to work correctly.

void ap_set_etag ( request_rec * r )

Set the E-tag outgoing header

Parameters

r	The current request

void ap_set_etag_fd	(	request_rec *	r,
		apr_file_t *	fd
	)

Set the E-tag outgoing header, with the option of forcing a strong ETag.

Parameters

r	The current request
fd	The file descriptor

int ap_set_keepalive ( request_rec * r )

Set the keepalive status for this request

Parameters

r	The current request

Returns: 1 if keepalive can be set, 0 otherwise

void ap_set_last_modified ( request_rec * r )

Set the last modified time for the file being sent

Parameters

r	The current request

void ap_set_sub_req_protocol	(	request_rec *	rnew,
		const request_rec *	r
	)

Sett up the protocol fields for subsidiary requests

Parameters

rnew	New Sub Request
r	current request

int ap_setup_client_block	(	request_rec *	r,
		int	read_policy
	)

Setup the client to allow Apache to read the request body.

Parameters

r	The current request
read_policy	How the server should interpret a chunked transfer-encoding. One of: REQUEST_NO_BODY Send 413 error if message has any body REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me.

Returns: either OK or an error code

void ap_setup_make_content_type ( apr_pool_t * pool )

Precompile metadata structures used by ap_make_content_type()

Parameters

pool	The pool to use for allocations

int ap_should_client_block ( request_rec * r )

Determine if the client has sent any data. This also sends a 100 Continue response to HTTP/1.1 clients, so modules should not be called until the module is ready to read content.

Warning: Never call this function more than once.

Parameters

r	The current request

Returns: 0 if there is no message to read, 1 otherwise

apr_status_t ap_switch_protocol	(	conn_rec *	c,
		request_rec *	r,
		server_rec *	s,
		const char *	protocol
	)

Perform the actual protocol switch. The protocol given must have been selected before on the very same connection and request pair.

Parameters

c	The current connection
r	The current request or NULL
s	The server/virtual host selected
protocol	the protocol to switch to

Returns: APR_SUCCESS, if caller may continue processing as usual APR_EOF, if caller needs to stop processing the connection APR_EINVAL, if the protocol is already in place APR_NOTIMPL, if no module performed the switch Other errors where appropriate

int ap_vrprintf	(	request_rec *	r,
		const char *	fmt,
		va_list	vlist
	)

Output data to the client in a printf format

Parameters

r	The current request
fmt	The format string
vlist	The arguments to use to fill out the format string

Returns: The number of bytes sent

apr_port_t default_port ( const request_rec * r )

Return the default port from the current request

Parameters

r	The current request

Returns: The current port

const char* http_scheme ( const request_rec * r )

This hook allows modules to retrieve the http scheme for a request. This allows Apache modules to easily extend the schemes that Apache understands

Parameters

r	The current request

Returns: The http scheme from the request

int log_transaction ( request_rec * r )

This hook allows modules to perform any module-specific logging activities over and above the normal server things.

Parameters

r	The current request

Returns: OK, DECLINED, or HTTP_...

int note_auth_failure	(	request_rec *	r,
		const char *	auth_type
	)

This hook allows modules to add support for a specific auth type to ap_note_auth_failure

Parameters

r	the current request
auth_type	the configured auth_type

Returns: OK, DECLINED

int post_read_request ( request_rec * r )

This hook allows modules to affect the request immediately after the request has been read, and before any other phases have been processes. This allows modules to make decisions based upon the input header fields

Parameters

r	The current request

Returns: OK or DECLINED

void pre_read_request	(	request_rec *	r,
		conn_rec *	c
	)

This hook allows modules to affect the request or connection immediately before the request has been read, and before any other phases have been processes.

Parameters

r	The current request of the soon-to-be-read request
c	The connection

Returns: None/void

const char* protocol_get ( const conn_rec * c )

Return the protocol used on the connection. Modules implementing protocol switching must register here and return the correct protocol identifier for connections they switched.

To find out the protocol for the current connection, better call

See Also: ap_get_protocol which internally uses this hook.

Parameters

c	The current connection

Returns: The identifier of the protocol in place or NULL

int protocol_propose	(	conn_rec *	c,
		request_rec *	r,
		server_rec *	s,
		const apr_array_header_t *	offers,
		apr_array_header_t *	proposals
	)

Determine the list of protocols available for a connection/request. This may be collected with or without any request sent, in which case the request is NULL. Or it may be triggered by the request received, e.g. through the "Upgrade" header.

This hook will be run whenever protocols are being negotiated (ALPN as one example). It may also be invoked at other times, e.g. when the server wants to advertise protocols it is capable of switching to.

The identifiers for protocols are taken from the TLS extension type ALPN: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml

If no protocols are added to the proposals, the server not perform any switch. If the protocol selected from the proposals is the protocol already in place, also no protocol switch will be invoked.

The client may already have announced the protocols it is willing to accept. These will then be listed as offers. This parameter may also be NULL, indicating that offers from the client are not known and the hooks should propose all protocols that are valid for the current connection/request.

All hooks are run, unless one returns an error. Proposals may contain duplicates. The order in which proposals are added is usually ignored.

Parameters

c	The current connection
r	The current request or NULL
s	The server/virtual host selected
offers	A list of protocol identifiers offered by the client or NULL to indicated that the hooks are free to propose
proposals	The list of protocol identifiers proposed by the hooks

Returns: OK or DECLINED

int protocol_switch	(	conn_rec *	c,
		request_rec *	r,
		server_rec *	s,
		const char *	protocol
	)

Perform a protocol switch on the connection. The exact requirements for that depend on the protocol in place and the one switched to. The first protocol module to handle the switch is the last module run.

For a connection level switch (r == NULL), the handler must on return leave the conn_rec in a state suitable for processing the switched protocol, e.g. correct filters in place.

For a request triggered switch (r != NULL), the protocol switch is done before the response is sent out. When switching from "http/1.1" via Upgrade header, the 101 intermediate response will have been sent. The hook needs then to process the connection until it can be closed. Which the server will enforce on hook return. Any error the hook might encounter must already be sent by the hook itself to the client in whatever form the new protocol requires.

Parameters