The request record is what Apache passes to most of the phase handlers.
request_rec.send_http_header()
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.
request_rec.add_cgi_vars()
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.
request_rec.add_common_vars()
This routine is equivalent to the Apache ap_add_common_vars(), which adds common CGI environment variables to the request's subprocess_env dictionary.
request_rec.get_basic_auth_pw()
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.
request_rec.requires()
This routine returns a tuple containing a number of require_line objects. Each require_line object contains requirement and method_mask attributes.
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.
request_rec.note_auth_failure()
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.
request_rec.note_basic_auth_failure()
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.
request_rec.note_digest_auth_failure()
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.
request_rec.send_http_trace()
This routine returns mod_snake.OK on success, and a mod_snake.HTTP_* error on failure.
This routine sends a copy of the clients request back to the client, including header and body information.
request_rec.rwrite( str)
str - data to write to the remote client.
Returns an integer designating how many bytes were written.
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. |
request_rec.setup_client_block( policy)
policy - One of the pre-defined policies
The return value is one of the standard hook return values in Table 2.
The read policy argument is one of:
Table 3. Read Policies
Argument | Description |
---|---|
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 the caller |
This routine sets up the policy for how subsequent reads via should_client_block, and get_client_block are performed.
request_rec.should_client_block()
This method will return 0 if there is no data to be read, otherwise it will return 1.
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.
request_rec.get_client_block( len)
len - Number of bytes to read.
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.
This method gets client sent information. It takes care of chunking, as per the setup_client_block.
request_rec.discard_request_body()
Returns one of the standard hook return values in Table 2.
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.
request_rec.add_output_filter( filtername, callback_data)
filtername - Name of filter to add.
callback_data - Callback data to send to the filter function.
This method is only available when mod_snake is running on an Apache 2.0 server.
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.
request_rec.brigade_create()
This method is only available when mod_snake is running on an Apache 2.0 server.
This method creates a new brigade (see the section called brigade API).
request_rec.output_filters
This hook is only available when mod_snake is running on an Apache 2.0 server.
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.
request_rec.connection
This attribute contains a reference to the connection associated with the incoming request.
request_rec.server
This attribute contains a reference to the server that the incoming request came in on.
request_rec.next
If the request ends up getting redirected, this attribute points to the request that it was directed to.
request_rec.prev
If the current request is an internal redirect, this attribute points to the request it came from.
request_rec.main
If this request is a sub request, this attribute points back to the main request.
request_rec.the_request
This attribute contains the first line of the request. Example: 'GET /foo/bar.html HTTP/1.0'
request_rec.header_only
This attribute is a true/false indicating whether or not it is a HEAD request
request_rec.protocol
This attribute is a string containing the protocol sent by the client, otherwise HTTP/0.9
request_rec.proto_num
This attribute is an integer representing the protocol number, as sent by the client. Example: HTTP/0.9 == 9, HTTP/1.1 == 1001
request_rec.hostname
This attribute contains the hostname, as set by the Host: header, or the full URI. If not given, it is 'None'
request_rec.status_line
This string attribute may be set by the module to return a specialized status-line back to the client.
request_rec.status
This integer attribute may be set byt he module to return a specific status number back to the client.
request_rec.method
This string attribute contains the method as set by the client. Example: GET, HEAD, FOO, etc.
request_rec.method_number
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.
request_rec.headers_in
This dictionary attribute contains the MIME headers as specified by the client.
request_rec.headers_out
This dictionary attribute contains the MIME headers that will be sent out to the client when the send_http_header method is called.
request_rec.notes
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.)
request_rec.content_type
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"
request_rec.content_encoding
This string attribute contains the encoding of the content.
request_rec.handler
This string attribute contains the handler to be dispatched on for the content-handler, else None.
request_rec.user
This string attribute contains the user name if authentication was made, else None.
request_rec.ap_auth_type
This string attribute contains the authentication type if authentication was made, else None. Example: 'basic', 'digest', etc.
request_rec.unparsed_uri
This string attribute contains the unparsed URI.
request_rec.filename
This string attribute contains the filename portion of the requested URI.
request_rec.path_info
This string attribute contains the path information of the requested URI, with no appended filename. If there is no path, this attribute is 'None'
request_rec.args
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.
request_rec.finfo
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)