client_block_api.html revision 2def4b444619c4a3f1508662c0feee58cd96a3ba
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>Apache 1.1 and earlier let modules handle POST and PUT requests by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncthemselves. The module would, on its own, determine whether the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncrequest had an entity, how many bytes it was, and then called a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncfunction (<code>read_client_block</code>) to get the data.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>However, HTTP/1.1 requires several things of POST and PUT request
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynchandlers that did not fit into this module, and all existing modules
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynchave to be rewritten. The API calls for handling this have been
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncfurthur abstracted, so that future HTTP protocol changes can be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncaccomplished while remaining backwards-compatible.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync int setup_client_block (request_rec *);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync int should_client_block (request_rec *);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync long get_client_block (request_rec *, char *buffer, int buffer_size);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<li>Call <code>setup_client_block()</code> near the beginning of the request
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync handler. This will set up all the neccessary properties, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync will return either OK, or an error code. If the latter,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the module should return that error code.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<li>When you are ready to possibly accept input, call
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This will tell the module whether or not to read input. If it is 0,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the module should assume that the input is of a non-entity type
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync (e.g. a GET request). A nonzero response indicates that the module
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync should proceed (to step 3).
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This step also sends a 100 Continue response
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync to HTTP/1.1 clients, so should not be called until the module
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is *defenitely* ready to read content. (otherwise, the point of the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 100 response is defeated). Never call this function more than once.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<li>Finally, call <code>get_client_block</code> in a loop. Pass it a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync buffer and its
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync size. It will put data into the buffer (not neccessarily the full
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync buffer, in the case of chunked inputs), and return the length of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the input block. When it is done reading, it will return 0, and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the module should proceed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>As an example, please look at the code in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<code>mod_cgi.c</code>. This is properly written to the new API
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncguidelines.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<A HREF="../"><IMG SRC="/images/apache_home.gif" ALT="Home"></A>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<A HREF="./"><IMG SRC="/images/apache_index.gif" ALT="Index"></A>
