Apache 1.3 API Documentation

Structure request_rec

Definition:

typedef struct request_rec request_rec; 
struct request_rec { 
    pool *pool; 
    conn_rec *connection; 
    server_rec *server; 
    request_rec *next; 
    request_rec *prev; 
    request_rec *main; 
    char *the_request; 
    int assbackwards; 
    enum proxyreqtype proxyreq; 
    int header_only; 
    char *protocol; 
    int proto_num; 
    char *hostname; 
    time_t request_time; 
    const char *status_line; 
    int status; 
    const char *method; 
    int method_number; 
    int allowed; 
    int sent_bodyct; 
    long bytes_sent; 
    time_t mtime; 
    int chunked; 
    int byterange; 
    char *boundary; 
    const char *range; 
    long clength; 
    long remaining; 
    long read_length; 
    int read_body; 
    int read_chunked; 
    unsigned expecting_100; 
    table *headers_in; 
    table *headers_out; 
    table *err_headers_out; 
    table *subprocess_env; 
    table *notes; 
    const char *content_type; 
    const char *handler; 
    const char *content_encoding; 
    const char *content_language; 
    array_header *content_languages; 
    char *vlist_validator; 
    int no_cache; 
    int no_local_copy; 
    char *unparsed_uri; 
    char *uri; 
    char *filename; 
    char *path_info; 
    char *args; 
    struct stat finfo; 
    uri_components parsed_uri; 
    void *per_dir_config; 
    void *request_config; 
    const struct htaccess_result *htaccess; 
    char *case_preserved_filename; 
};
     

Usage example:

No examples available.
     

The request_rec structure is key to Apache's processing of client requests. A pointer to a request_req structure is passed to all phase handlers and many API routines, and it is usually given the argument name 'r' (e.g., ap_add_common_vars(r)).

Detailed Field Descriptions

pool *pool

If a module routine is passed a request_rec structure, the pool pointer in the structure is available for memory allocation. (See the description of ap_palloc() and related routines.) When the request is completed, the memory pool will be released.

conn_rec *connection

This is a pointer to the conn_rec structure describing the TCP/IP connexion over which the request was received.

server_rec *server

This field contains a pointer to the server_rec structure for the virtual host which was assigned to handle the request.

request_rec *next

request_rec *prev

request_rec *main

These fields are pointers to other request_rec structures in the case of a complex opertion involving subrequests. The main pointer refers to the request actually received from the client, as opposed to any internal ones created by Apache during its request resolution.

char *the_request

This is a pointer to the actual request string received from the client (e.g., "GET /index.html HTTP/1.1").

int assbackwards

This is a Boolean flag indicating whether the request was made using the HTTP/0.9 protocol. It is set to non-zero if so.

enum proxyreqtype proxyreq

This field is only used by proxy modules, and indicates the type of proxy request involved. See the description of the proxyreqtype enumeration for more information.

int header_only

This Boolean flag is set to non-zero if the request was made with the HEAD method. The response headers will be returned, but modules shouldn't bother to generate any content for the response.

char *protocol

This is a pointer to a string representing the protocol of the request, such as "HTTP/0.9" or "HTTP/1.1".

int proto_num

This is a numeric representation of the protocol level. It can be parsed with the HTTP_VERSION_MAJOR() and HTTP_VERSION_MINOR() macros (q.q.v.).

char *hostname

Pointer to a string indicating the hostname to which the request was directed (extracted from either the r->the_request string or the Host request header field). Note that this value may be different from the name of the host actually processing the request; that is, it may differ from any value in the r->server->names array.

time_t request_time

This field is used to record the time the request was received by the server. This value is stored in local time, not GMT.

const char *status_line

This field is reserved to and used by the core server for constructing the status line portion of the response header.

int status

This is used to contain the numeric code of the HTTP response status, such as HTTP_NOT_MODIFIED. It is typically not used by modules because the protocol module derives the correct value from module responses and the HTTP specification defining the interaction of header fields.

const char *method

This is a pointer to a string representing the name of the HTTP method used to make the request, such as "GET", as extracted from the r->the_request string. Modules may want to reference this field if they handle extension methods not directly known to the core server and therefore not represented by a numeric value. (See th enext field, method_number.)

int method_number

This field contains a numeric value representing the request method. The possible values are give mnemonic names prefixed with "M_", such as "M_GET" and "M_DELETE" (q.q.v.; see the description of M_GET for additional references and information.) If the request was made using a method unknown to the core server, the value in this field will be M_INVALID, even if the server has been configured to recognise the method (such as with the Script directive). In this case modules should check the string value in the method field of the request_rec structure, which immediately precedes this one.

int allowed

This is a bitmask of the HTTP methods permitted for the resource. The module that generates the response content is responsible for setting this; it should do so before or during the content generation phase, before the response header is sent. This mask is used solely to create the Allowed response header field. It's a good idea to set it in an earlier phase if possible, in case the request method is OPTIONS and will be handled by the default_handler. Due to the dependence on hard-coded bitmask values, Apache 1.3 provides no support for listing extension methods in this field.

int sent_bodyct

This field is reserved for use by the core server.

long bytes_sent

This field is reserved for use by the core server. At the completion of the request it contains the number of bytes sent as the response body; it does not include the bytes in the response header. It is primarily used by logging modules.

time_t mtime

This field contains the last-modified time for the current document. It should be set with the ap_update_mtime() or ap_rationalize_mtime() routines.

int chunked

This field is reserved for use by the core server. It is a Boolean value indicating whether the response is being sent using chunked encoding.

int byterange

This field contains the number of distinct byte-ranges in the request header's Range field.

char *boundary

The delimiting string used in multipart or byterange bodies.

const char *range

The value of the request's Range header field. This is stored here for convenience; it is also available in the headers_in table described below.

long clength

The actual length in bytes of the response body. Set with the ap_set_content_length() routine (q.v.).

long remaining

The number of bytes in the request body that have not yet been read. This is updated by the server core each time a module asks the server core for more of the body. Modules must regard it as a read-only field.

long read_length

Similar to the remaining field described above, this field contains the count of bytes already read from the request bosy. Modules must regard this as a read-only field.

int read_body

int read_chunked

unsigned expecting_100

This field is reserved for use by the core server in handling aspects of the HTTP/1.1 protocol.

table *headers_in

This table contains a key/value pair for every field in the request header. Some of the fields are also represented in other ways, such as the Range field, but all of the original request header fields are stored in this table in their raw form. Modules must regard this table as read-only.

table *headers_out

This table is used to hold the key/value pairs of the header fields to be sent as part of the response. Under certain conditions, such as error responses, the values in this table will not be used in the construction of the response header. Under normal circumstances, however, its contents are merged with those in the r->err_headers_out table to form the response header.

table *err_headers_out

Similar to the headers_out table described previously, the contents of this table are used in the formation of the response header. However, the values in this table are always used, even under error conditions. Under normal conditions, they are merged with those in the r->header_out table and the result is used.

table *subprocess_env

The name of this field is somewhat misleading. This table contains the names and values of 'environment' variables that are available to subsequent stages of processing for the request. They are set as actual environment variables only if a child process needs to be created, such as for invoking a CGI script. However, these values are also available for use by things such as mod_include, even though no actual subprocess creation is involved.

table *notes

This table has no strictly defined purpose; it is generally intended to provide a means for modules to communicate with each other when processing a request, or for different phase handlers of the same module to pass information from phase to another. For example, mod_speling uses this table to pass a list of possible document variants to mod_negotiation.

const char *content_type

Specifies the content-type of the respose body (if there is one). Modules should set this field rather than inserting an entry directly into either r->headers_out or r->err_headers_out.

const char *handler

const char *content_encoding

const char *content_language

array_header *content_languages

char *vlist_validator

int no_cache

int no_local_copy

char *unparsed_uri

char *uri

char *filename

char *path_info

char *args

struct stat finfo

uri_components parsed_uri

void *per_dir_config

void *request_config

const struct htaccess_result *htaccess

char *case_preserved_filename

This field contains the original translated filename representing the document source (if it actually is a file) before canonicalisation. This is necessary for some situations in which canonicalisation actually modifies the name for later use. For example, on Windows systems Apache always always translates filenames to lowercase for security reasons (among others). This would cause problems if the case of the requested name was actually significant though the case of the actual filename was not, such as if the request was referring to a Java class file. This field provides the original filename before the downcasing (or other canonicalisation transform) has been performed.

See also:

BUFF, cmd_parms, command_rec, conn_rec, HTTP_VERSION_MAJOR, HTTP_VERSION_MINOR, proxyreqtype, server_addr_rec, server_rec, uri_components

Previous: regmatch_t Next: scoreboard

Table of Contents (Routines, Structures, Data Cells, Constants)