HTTP Protocol Handling
[Core routines]

Collaboration diagram for HTTP Protocol Handling:

Data Structures

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

Defines

#define AP_METHOD_CHECK_ALLOWED(mask, methname)   ((mask) & (AP_METHOD_BIT << ap_method_number_of((methname))))
#define ap_rgetline(s, n, read, r, fold, bb)   ap_rgetline_core((s), (n), (read), (r), (fold), (bb))
#define AP_BUCKET_IS_ERROR(e)   (e->type == &ap_bucket_type_error)

Typedefs

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_recap_read_request (conn_rec *c)
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)
void ap_set_etag (request_rec *r)
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_tap_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)
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)
void ap_parse_uri (request_rec *r, const char *uri)
int ap_getline (char *s, int n, request_rec *r, int fold)
apr_status_t ap_rgetline_core (char **s, apr_size_t n, apr_size_t *read, request_rec *r, int fold, 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)
apr_bucketap_bucket_error_make (apr_bucket *b, int error, const char *buf, apr_pool_t *p)
apr_bucketap_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_tap_old_write_func
AP_DECLARE_DATA const
apr_bucket_type_t 
ap_bucket_type_error

Define Documentation

#define AP_BUCKET_IS_ERROR (  )     (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_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_rgetline ( s,
n,
read,
r,
fold,
bb   )     ap_rgetline_core((s), (n), (read), (r), (fold), (bb))

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
Returns:
APR_SUCCESS, if successful APR_ENOSPC, if the line is too big to fit in the buffer Other errors where appropriate

Typedef Documentation


Enumeration Type Documentation

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 
)
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
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
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
int ap_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
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_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
int ap_getline ( char *  s,
int  n,
request_rec r,
int  fold 
)

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
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
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
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 
)
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  ) 
void ap_note_digest_auth_failure ( request_rec r  ) 
apr_status_t ap_old_write_filter ( ap_filter_t f,
apr_bucket_brigade b 
)
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_core ( char **  s,
apr_size_t  n,
apr_size_t read,
request_rec r,
int  fold,
apr_bucket_brigade bb 
)
See also:
ap_rgetline
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
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
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
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

Variable Documentation

AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_error

This is an optimization. We keep a record of the filter_rec that stores the old_write filter, so that we can avoid strcmp's later.

Generated on Fri Oct 24 16:08:28 2014 for Apache2 by  doxygen 1.6.3