client_block_api.html revision 2def4b444619c4a3f1508662c0feee58cd96a3ba
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<HTML>
<HEAD>
<TITLE>Reading Client Input in Apache 1.2</TITLE>
</HEAD>
<BODY>
<H1>Reading Client Input in Apache 1.2</h1>
<hr>
<p>Apache 1.1 and earlier let modules handle POST and PUT requests by
themselves. The module would, on its own, determine whether the
request had an entity, how many bytes it was, and then called a
function (<code>read_client_block</code>) to get the data.
handlers that did not fit into this module, and all existing modules
have to be rewritten. The API calls for handling this have been
furthur abstracted, so that future HTTP protocol changes can be
accomplished while remaining backwards-compatible.</p>
<hr>
<h3>The New API Functions</h3>
<pre>
int setup_client_block (request_rec *);
int should_client_block (request_rec *);
long get_client_block (request_rec *, char *buffer, int buffer_size);
</pre>
<ol>
<li>Call <code>setup_client_block()</code> near the beginning of the request
handler. This will set up all the neccessary properties, and
will return either OK, or an error code. If the latter,
the module should return that error code.
<li>When you are ready to possibly accept input, call
<code>should_client_block()</code>.
This will tell the module whether or not to read input. If it is 0,
the module should assume that the input is of a non-entity type
(e.g. a GET request). A nonzero response indicates that the module
should proceed (to step 3).
This step also sends a 100 Continue response
is *defenitely* ready to read content. (otherwise, the point of the
100 response is defeated). Never call this function more than once.
<li>Finally, call <code>get_client_block</code> in a loop. Pass it a
buffer and its
size. It will put data into the buffer (not neccessarily the full
buffer, in the case of chunked inputs), and return the length of
the input block. When it is done reading, it will return 0, and
the module should proceed.
</ol>
<p>As an example, please look at the code in
guidelines.</p>
<hr>
</BODY>
</HTML>