request_rec API

The request record is what Apache passes to most of the phase handlers.

send_http_header

Synopsis

request_rec.send_http_header()

Description

Before content data is sent to the client, headers must be sent. Modules which choose to handle the entire content_handler phase by themselves, must call this routine prior to sending content. The headers sent are setup within the request_rec's headers_in and headers_out dictionaries. Other fields such as content_type and status are also used when send_http_header() generates its response.

add_cgi_vars

Synopsis

request_rec.add_cgi_vars()

Description

This routine is equivalent to the Apache ap_add_cgi_vars(), which adds commonly used CGI environment variables to the request's subprocess_env dictionary.

add_common_vars

Synopsis

request_rec.add_common_vars()

Description

This routine is equivalent to the Apache ap_add_common_vars(), which adds common CGI environment variables to the request's subprocess_env dictionary.

get_basic_auth_pw

Synopsis

request_rec.get_basic_auth_pw()

Description

This routine returns a tuple (rescode, pword), where rescode is one of mod_snake.HTTP_INTERNAL_SERVER_ERROR, mod_snake.HTTP_UNAUTHORIZED, mod_snake.OK, or mod_snake.DECLINED. If rescode is mod_snake.OK, pword will be a string password passed by the client, else it will be None.

requires

Synopsis

request_rec.requires()

Return Value

This routine returns a tuple containing a number of require_line objects. Each require_line object contains requirement and method_mask attributes.

Description

When Apache processes 'Require' directives, the values are added to an internal array. PyMods may access this array via the requires() function. The objects returned contain a requirement attribute, designating the value passed to the 'Require' directive, and a method_mask indicating the limit imposed on the requirement as designated by the <Limit> directives.

note_auth_failure

Synopsis

request_rec.note_auth_failure()

Description

This routine is a wrapper around the request_rec.note_basic_auth_failure(), and request_rec.note_digest_auth_failure() functions. Either of them, or none may be called depending on the authentication type of the request.

note_basic_failure

Synopsis

request_rec.note_basic_auth_failure()

Description

This routine makes modifications to the outgoing client error headers. It will add the WWW-Authenticate header, or the Proxy-Authenticate header, depending on the type of request.

note_digest_failure

Synopsis

request_rec.note_digest_auth_failure()

Description

This routine makes modifications to the outgoing client error headers. It will add the WWW-Authenticate header, or the Proxy-Authenticate header, depending on the type of request.

send_http_trace

Synopsis

request_rec.send_http_trace()

Return Value

This routine returns mod_snake.OK on success, and a mod_snake.HTTP_* error on failure.

Description

This routine sends a copy of the clients request back to the client, including header and body information.

ap_rwrite

Synopsis

request_rec.rwrite( str)

Arguments

Return Value

Returns an integer designating how many bytes were written.

Description

The rwrite function is one of the main ways that PyMods can communicate information back to the remote client. This routine sends all data passed in through all of Apache's internal routines for buffering and filtering. Under Apache 2.0, this method is still available, but buffers data internally before converting it to a bucket in a brigade.

Warning

Modules should never use both rwrite calls and bucket brigades to write to a client. Since rwrite calls are buffered internally, data may be sent out of order if they are mixed.

setup_client_block

Synopsis

request_rec.setup_client_block( policy)

Arguments

Return Value

The return value is one of the standard hook return values in Table 2.

Description

The read policy argument is one of:

Table 3. Read Policies

ArgumentDescription
REQUEST_NO_BODYSend 413 error if message has any body
REQUEST_CHUNKED_ERRORSend 411 error if body without Content-Length
REQUEST_CHUNKED_DECHUNKIf chunked, remove the chunks for the caller

This routine sets up the policy for how subsequent reads via should_client_block, and get_client_block are performed.

should_client_block

Synopsis

request_rec.should_client_block()

Return Value

This method will return 0 if there is no data to be read, otherwise it will return 1.

Description

This method is an intermediate step between the setup of the client block, and getting the client blocks. It ensures that 100 Continue responses are sent appropriately. This function should never be called more than once per request.

get_client_block

Synopsis

request_rec.get_client_block( len)

Arguments

Return Value

This method returns a tuple containing a (data, datalen) pair -- the data read, and the length of the data. On error, 'data' will be Py_None.

Description

This method gets client sent information. It takes care of chunking, as per the setup_client_block.

discard_request_body

Synopsis

request_rec.discard_request_body()

Return Value

Returns one of the standard hook return values in Table 2.

Description

In the case where a handler does not want to deal with a request body, this routine can be called to safely discard it. This is especially useful, as to not disrupt persistant connections.

add_output_filter

Synopsis

request_rec.add_output_filter( filtername, callback_data)

Arguments

Compatability

This method is only available when mod_snake is running on an Apache 2.0 server.

Description

This method is used to add a filter to the filter chain. The filter must first be registered via register_output_filter (see the section called register_output_filter). The callback data is available within the filter function as filter.ctx.

brigade_create

Synopsis

request_rec.brigade_create()

Compatability

This method is only available when mod_snake is running on an Apache 2.0 server.

Description

This method creates a new brigade (see the section called brigade API).

output_filters

Synopsis

request_rec.output_filters

Compatability

This hook is only available when mod_snake is running on an Apache 2.0 server.

Description

This attribute contains a reference to the chain of filters that are scheduled to process data. Content generation phases can call the pass_brigade method of this object to send data to the client.

connection

Synopsis

request_rec.connection

Description

This attribute contains a reference to the connection associated with the incoming request.

server

Synopsis

request_rec.server

Description

This attribute contains a reference to the server that the incoming request came in on.

next

Synopsis

request_rec.next

Description

If the request ends up getting redirected, this attribute points to the request that it was directed to.

prev

Synopsis

request_rec.prev

Description

If the current request is an internal redirect, this attribute points to the request it came from.

main

Synopsis

request_rec.main

Description

If this request is a sub request, this attribute points back to the main request.

the_request

Synopsis

request_rec.the_request

Description

This attribute contains the first line of the request. Example: 'GET /foo/bar.html HTTP/1.0'

header_only

Synopsis

request_rec.header_only

Description

This attribute is a true/false indicating whether or not it is a HEAD request

protocol

Synopsis

request_rec.protocol

Description

This attribute is a string containing the protocol sent by the client, otherwise HTTP/0.9

proto_num

Synopsis

request_rec.proto_num

Description

This attribute is an integer representing the protocol number, as sent by the client. Example: HTTP/0.9 == 9, HTTP/1.1 == 1001

hostname

Synopsis

request_rec.hostname

Description

This attribute contains the hostname, as set by the Host: header, or the full URI. If not given, it is 'None'

status_line

Synopsis

request_rec.status_line

Description

This string attribute may be set by the module to return a specialized status-line back to the client.

status

Synopsis

request_rec.status

Description

This integer attribute may be set byt he module to return a specific status number back to the client.

method

Synopsis

request_rec.method

Description

This string attribute contains the method as set by the client. Example: GET, HEAD, FOO, etc.

method_number

Synopsis

request_rec.method_number

Description

This attribute holds an integer value representing the method as sent by the client. The following values are the ones recognized by the server, and are properties of the mod_snake module: M_GET, M_PUT, M_POST, M_DELETE, M_CONNECT, M_OPTIONS, M_TRACE, M_PATCH, M_PROPFIND, M_PROPPATCH, M_MKCOL, M_COPY, M_MOVE, M_LOCK, M_UNLOCK, M_INVALID. Note that M_GET is valid for both GET and HEAD methods.

headers_in

Synopsis

request_rec.headers_in

Description

This dictionary attribute contains the MIME headers as specified by the client.

headers_out

Synopsis

request_rec.headers_out

Description

This dictionary attribute contains the MIME headers that will be sent out to the client when the send_http_header method is called.

notes

Synopsis

request_rec.notes

Description

This dictionary attribute provides storage for modules on a per request basis. Modules can store any data they wish in this dictionary, however it will be unavailable for subsequent requests. This storage can be useful when a module needs to keep per-request information in between different handlers (such as the fixups and content-handlers.)

content_type

Synopsis

request_rec.content_type

Description

This string attribute contains the content type as established by the Apache type-checker phase, or None before the type-checker phase is called. Example: "text/html"

content_encoding

Synopsis

request_rec.content_encoding

Description

This string attribute contains the encoding of the content.

handler

Synopsis

request_rec.handler

Description

This string attribute contains the handler to be dispatched on for the content-handler, else None.

user

Synopsis

request_rec.user

Description

This string attribute contains the user name if authentication was made, else None.

ap_auth_type

Synopsis

request_rec.ap_auth_type

Description

This string attribute contains the authentication type if authentication was made, else None. Example: 'basic', 'digest', etc.

unparsed_uri

Synopsis

request_rec.unparsed_uri

Description

This string attribute contains the unparsed URI.

uri

Synopsis

request_rec.uri

Description

This string attribute contains the path portion of the URI.

filename

Synopsis

request_rec.filename

Description

This string attribute contains the filename portion of the requested URI.

path_info

Synopsis

request_rec.path_info

Description

This string attribute contains the path information of the requested URI, with no appended filename. If there is no path, this attribute is 'None'

args

Synopsis

request_rec.args

Description

This string attribute contains the query arguments from the URI if given, else None. This string can be passed to cgi.py's parse_qs() function to turn it into a dictionary of values.

cgi.py: cgi.py is distributed with all Python distributions.

finfo

Synopsis

request_rec.finfo

Description

If the requested document is a real file, this attribute contains a tuple from the stat(). The tuple is the same as returned by the os.stat function, and contains the following elements: (mode, inode, device, number_links, uid, guid, size, atime, mtime, ctime)