[Apache]

Package Name: HTTP protocol handling

struct ap_bucket_error


struct ap_bucket_error

Source:./include/http_protocol.h

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

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
rthe current request
(void);
Read the mime-encoded headers.

Parameters
rThe current request
(void);
Optimized version of ap_get_mime_headers() that requires a temporary brigade to work with

Parameters
rThe current request
bbtemp brigade
(int);
Register a new request method, and return the offset that will be associated with that method.

Parameters
pThe pool to create registered method numbers from.
methnameThe 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
pPool 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
sPointer 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
nThe size of the buffer
readThe length of the line.
rThe request
foldWhether to merge continuation lines
bbWorking 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
methodA 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
pA pool to use for temporary allocations.
methnumAn 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
pPointer to a pool in which the structure should be allocated.
neltsNumber 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
cThe 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
rThe 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
eThe bucket to inspect
bThe bucket to make into an error bucket
errorThe HTTP error code to put in the bucket.
bufAn optional error string to put in the bucket.
pA 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
errorThe HTTP error code to put in the bucket.
bufAn optional error string to put in the bucket.
pA pool to allocate the error string out of.
listThe 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
rThe 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
fdThe file to send.
rThe current request
offsetOffset into the file to start sending.
lengthAmount of data to send
nbytesAmount 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
rThe current request
mtimeThe 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
rThe current request
force_weakForce 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
statusThe 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
rThe 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
rThe current request
Return Value
The content-type

intap_set_keepalive(request_rec *r);
Set the keepalive status for this request

Parameters
rThe 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
rThe 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
methodString containing the name of the method to check.
lPointer 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
cthe character to output
rthe 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
strThe string to output
rThe 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
bufThe buffer to write
nbyteThe number of bytes to send from the buffer
rThe current request
Return Value
The number of bytes sent

intap_rvputs(request_rec *r, ...);
Write an unspecified number of strings to the request

Parameters
rThe 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
rThe current request
fmtThe format string
vlistThe 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
rThe current request
fmtThe 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
rThe 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
statusHTTP 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
rThe current request
read_policyHow 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
rThe 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
rThe 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
rThe current request
pwThe 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
sThe buffer into which to read the line
nThe size of the buffer
rThe request
foldWhether 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
rThe 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
rThe current request
bufferThe buffer in which to store the data
bufsizThe 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
mmThe MMAP'ed file to send
rThe current request
offsetThe offset into the MMAP to start sending
lengthThe 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
rThe current request
lengthThe new content length
voidap_setup_make_content_type(apr_pool_t *pool);
Precompile metadata structures used by ap_make_content_type()

Parameters
rThe pool to use for allocations
voidap_set_etag(request_rec *r);
Set the E-tag outgoing header

Parameters
Thecurrent request
voidap_set_last_modified(request_rec *r);
Set the last modified time for the file being sent

Parameters
rThe 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
methodString containing the name of the method to check.
lPointer 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
lPointer to a method list, such as cmd->methods_limited.
methodString 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
lPointer 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
rThe current request
ctThe 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
rThe 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
rThe 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
rThe 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
rThe current request
uriThe 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
rThe current request
voidap_send_error_response(request_rec *r, int recursive_error);
Send error back to client.

Parameters
rThe current request
recursive_errorlast 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.

© 2000 [Apache Software Foundation]
Generated by ScanDoc 0.14
Last Updated: Fri Apr 14 12:43:20 2006