4176N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<
TITLE>Reading Client Input in Apache 1.2</
TITLE>
0N/A<!-- Background white, links blue (unvisited), navy (visited), red (active) --> 0N/A<
H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</
H1>
2362N/A<
P>Apache 1.1 and earlier let modules handle POST and PUT requests by
0N/Athemselves. The module would, on its own, determine whether the
4880N/Arequest had an entity, how many bytes it was, and then called a
1178N/Afunction (<
CODE>read_client_block</
CODE>) to get the data.
1178N/A<
P>However,
HTTP/
1.1 requires several things of POST and PUT request
0N/Ahandlers that did not fit into this module, and all existing modules
1178N/Ahave to be rewritten. The API calls for handling this have been
0N/Afurther abstracted, so that future HTTP protocol changes can be
1178N/Aaccomplished while remaining backwards-compatible.</
P>
1178N/A<
H3>The New API Functions</
H3>
1178N/A int ap_setup_client_block (request_rec *, int read_policy);
1178N/A int ap_should_client_block (request_rec *);
0N/A long ap_get_client_block (request_rec *, char *buffer, int buffer_size);
1178N/A<
LI>Call <
CODE>ap_setup_client_block()</
CODE> near the beginning of the request
1178N/A handler. This will set up all the necessary properties, and
0N/A will return either OK, or an error code. If the latter,
1178N/A the module should return that error code. The second parameter
1178N/A selects the policy to apply if the request message indicates a
1178N/A transfer-coding should be interpreted. Choose one of
0N/A REQUEST_NO_BODY Send 413 error if message has any body
0N/A REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length
0N/A REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me.
0N/A REQUEST_CHUNKED_PASS Pass the chunks to me without removal.
0N/A In order to use the last two options, the caller MUST provide a buffer
1178N/A large enough to hold a chunk-size line, including any extensions.
0N/A<
LI>When you are ready to possibly accept input, call
1178N/A <
CODE>ap_should_client_block()</
CODE>.
4176N/A This will tell the module whether or not to read input. If it is 0,
1178N/A the module should assume that the input is of a non-entity type
1178N/A (
e.g. a GET request). A nonzero response indicates that the module
1178N/A should proceed (to step 3).
0N/A This step also sends a 100 Continue response
0N/A to
HTTP/
1.1 clients, so should not be called until the module
1178N/A is <
STRONG>*definitely*</
STRONG> ready to read content. (otherwise, the
0N/A 100 response is defeated). Never call this function more than once.
0N/A<
LI>Finally, call <
CODE>ap_get_client_block</
CODE> in a loop. Pass it a
1178N/A size. It will put data into the buffer (not necessarily the full
1178N/A buffer, in the case of chunked inputs), and return the length of
0N/A the input block. When it is done reading, it will
0N/A return 0 if EOF, or -1 if there was an error.
1178N/A<
P>As an example, please look at the code in
0N/A<
CODE>
mod_cgi.c</
CODE>. This is properly written to the new API