Package Name: HTTP protocol handling

struct ap_bucket_error

A bucket referring to an HTTP error This bucket can be passed down the filter stack to indicate that an HTTP error occurred while running a filter. In order for this bucket to be used successfully, it MUST be sent as the first bucket in the first brigade to be sent from a given filter.

Member Index

• const char *data
• apr_bucket_refcount refcount
• int status

Class Variables

const char *data;

The error string

apr_bucket_refcount refcount;

Number of buckets using this memory

int status;

The error code

Global Functions

(void,insert_error_filter,(request_rec *r));

This hook allows modules to insert filters for the current error response @ingroup hooks

Parameters

r	the current request

(void);

Read the mime-encoded headers.

Parameters

r	The current request

(void);

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

Parameters

r	The current request
bb	temp brigade

(int);

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.

Return Value

Ab int value representing an offset into a bitmask.

(void);

Initialize the method_registry and allocate memory for it.

Parameters

p	Pool to allocate memory for the registry from.

(void);

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

(apr_status_t);

Get the next line of input for the request Note: on ASCII boxes, ap_rgetline is a macro which simply calls ap_rgetline_core to get the line of input.

on EBCDIC boxes, ap_rgetline is a wrapper function which translates ASCII protocol lines to the local EBCDIC code page after getting the line of input.

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 the request pool
n	The size of the buffer
read	The length of the line.
r	The request
fold	Whether to merge continuation lines
bb	Working brigade to use when reading buckets

Return Value

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

(int);

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

Return Value

The method number

(const char *);

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

Return Value

The name corresponding to the method number

ap_method_list_tap_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

Return Value

Pointer to the newly created structure.

request_rec *ap_read_request(conn_rec *c);

Read a request and fill in the fields.

Parameters

c	The current connection

Return Value

The new request_rec

ap_run_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

Return Value

OK or DECLINED

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

Determine if a bucket is an error bucket Make the bucket passed in an error bucket

Parameters

e	The bucket to inspect
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.

Return Value

true or false The new bucket, or NULL if allocation failed

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

Return Value

The new bucket, or NULL if allocation failed

apr_port_tap_run_default_port(const request_rec *r);

Return the default port from the current request

Parameters

r	The current request

Return Value

The current port

apr_status_tap_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

apr_time_tap_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

Return Value

the latest rational time.

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.

Return Value

The entity tag

constchar *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

Return Value

The Status-Line

constchar *ap_run_http_method(const request_rec *r);

This hook allows modules to retrieve the http method from a request. This allows Apache modules to easily extend the methods that Apache understands

Parameters

r	The current request

Return Value

The http method from the request

constchar *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, type is set to ap_default_type(r) - 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

Return Value

The content-type

intap_set_keepalive(request_rec *r);

Set the keepalive status for this request

Parameters

r	The current request

Return Value

1 if keepalive can be set, 0 otherwise

intap_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

Return Value

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

intap_method_in_list(const char *method, ap_method_list_t *l);

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 cmd->methods_limited.

Return Value

1 if method is in the list, otherwise 0

intap_rputc(int c, request_rec *r);

Output one character for this request

Parameters

c	the character to output
r	the current request

Return Value

The number of bytes sent

intap_rputs(const char *str, request_rec *r);

Output a string for the current request

Parameters

str	The string to output
r	The current request

Return Value

The number of bytes sent

intap_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

Return Value

The number of bytes sent

intap_rvputs(request_rec *r, ...);

Write an unspecified number of strings to the request

Parameters

r	The current request ... The strings to write

Return Value

The number of bytes sent

intap_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

Return Value

The number of bytes sent

intap_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

Return Value

The number of bytes sent

intap_rflush(request_rec *r);

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

Parameters

r	The current request

Return Value

The number of bytes sent

intap_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

Return Value

The index of the response

intap_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.

Return Value

either OK or an error code

intap_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.

Never call this function more than once.

Parameters

r	The current request

Return Value

0 if there is no message to read, 1 otherwise

intap_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

Return Value

error status if request is malformed, OK otherwise

intap_get_basic_auth_pw(request_rec *r, const char **pw);

Get the password from the request headers

Parameters

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

Return Value

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).

intap_method_number_of(const char *method);

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
fold	Whether to merge continuation lines

Return Value

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

intap_run_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

Return Value

OK, DECLINED, or HTTP_...

longap_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

Return Value

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

size_tap_send_mmap(apr_mmap_t *mm, request_rec *r, size_t offset, 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

Return Value

The number of bytes sent

voidap_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

voidap_setup_make_content_type(apr_pool_t *pool);

Precompile metadata structures used by ap_make_content_type()

Parameters

r	The pool to use for allocations

voidap_set_etag(request_rec *r);

Set the E-tag outgoing header

Parameters

The	current request

voidap_set_last_modified(request_rec *r);

Set the last modified time for the file being sent

Parameters

r	The current request

voidap_method_in_list(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 cmd->methods_limited.

Return Value

None.

voidap_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 cmd->methods_limited.
method	String containing the name of the method to remove.

Return Value

None.

voidap_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 cmd->methods_limited.

Return Value

None.

voidap_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

voidap_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. This function works for both basic and digest authentication

Parameters

r	The current request

voidap_note_basic_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. This function works only for basic authentication

Parameters

r	The current request

voidap_note_digest_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. This function works only for digest authentication

Parameters

r	The current request

voidap_parse_uri(request_rec *r, const char *uri);

parse_uri: break apart the uri

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

voidap_finalize_request_protocol(request_rec *r);

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

Parameters

r	The current request

voidap_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.