[APACHE DOCUMENTATION]

Reading Client Input in Apache 1.2

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 (read_client_block) to get the data.

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 furthur abstracted, so that future HTTP protocol changes can be accomplished while remaining backwards-compatible.

The New API Functions

   int setup_client_block (request_rec *, int read_policy);
   int should_client_block (request_rec *);
   long get_client_block (request_rec *, char *buffer, int buffer_size);
  1. Call setup_client_block() 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. The second parameter selects the policy to apply if the request message indicates a body, and how a chunked transfer-coding sho uld be interpreted. Choose one of 
        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.
    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.
  2. When you are ready to possibly accept input, call should_client_block(). 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 to HTTP/1.1 clients, so should not be called until the module is *defenitely* ready to read content. (otherwise, the point of the 100 response is defeated). Never call this function more than once.
  3. Finally, call get_client_block 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 if EOF, or -1 if there was an error.

As an example, please look at the code in mod_cgi.c. This is properly written to the new API guidelines.

Index Home