| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Reading Client Input in Apache 1.2</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">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. |
| |
| <P>However, HTTP/1.1 requires several things of POST and PUT request |
| handlers that did not fit into this module, and all existing modules |
| have to be rewritten. The API calls for handling this have been |
| further abstracted, so that future HTTP protocol changes can be |
| accomplished while remaining backwards-compatible.</P> |
| |
| <HR> |
| |
| <H3>The New API Functions</H3> |
| |
| <PRE> |
| int ap_setup_client_block (request_rec *, int read_policy); |
| int ap_should_client_block (request_rec *); |
| long ap_get_client_block (request_rec *, char *buffer, int buffer_size); |
| </PRE> |
| |
| <OL> |
| <LI>Call <CODE>ap_setup_client_block()</CODE> near the beginning of the request |
| handler. This will set up all the necessary properties, and |
| will return either OK, or an error code. If the latter, |
| the module should return that error code. The second parameter |
| selects the policy to apply if the request message indicates a |
| body, and how a chunked |
| transfer-coding should be interpreted. Choose one of |
| <PRE> |
| 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 me. |
| REQUEST_CHUNKED_PASS Pass the chunks to me without removal. |
| </PRE> |
| In order to use the last two options, the caller MUST provide a buffer |
| large enough to hold a chunk-size line, including any extensions. |
| |
| |
| |
| <LI>When you are ready to possibly accept input, call |
| <CODE>ap_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 |
| (<EM>e.g.</EM>, a GET request). A nonzero response indicates that the module |
| should proceed (to step 3). |
| This step also sends a 100 Continue response |
| to HTTP/1.1 clients, so should not be called until the module |
| is <STRONG>*definitely*</STRONG> ready to read content. (otherwise, the |
| point of the |
| 100 response is defeated). Never call this function more than once. |
| |
| <LI>Finally, call <CODE>ap_get_client_block</CODE> in a loop. Pass it a |
| buffer and its |
| size. It will put data into the buffer (not necessarily 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 if EOF, or -1 if there was an error. |
| |
| </OL> |
| |
| <P>As an example, please look at the code in |
| <CODE>mod_cgi.c</CODE>. This is properly written to the new API |
| guidelines.</P> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
