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