client_block_api.html revision 7b3e47feb2f0d0a120f80b2de66656a55d0e63ef
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
4da61833a1cbbca94094f9653fd970582b97a72etrawick BGCOLOR="#FFFFFF"
4da61833a1cbbca94094f9653fd970582b97a72etrawick TEXT="#000000"
4da61833a1cbbca94094f9653fd970582b97a72etrawick LINK="#0000FF"
4da61833a1cbbca94094f9653fd970582b97a72etrawick VLINK="#000080"
4789804be088bcd86ae637a29cdb7fda25169521jailletc ALINK="#FF0000"
4789804be088bcd86ae637a29cdb7fda25169521jailletc<!--#include virtual="header.html" -->
e50c3026198fd496f183cda4c32a202925476778covenerThis document has not been updated to take into account changes
e50c3026198fd496f183cda4c32a202925476778covenermade in the 2.0 version of the Apache HTTP Server. Some of the
5b88c8507d5ef6d0c4cfbc78230294968175b638minfrininformation may still be relevant, but please use it
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic</blockquote>
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</H1>
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic<P>Apache 1.1 and earlier let modules handle POST and PUT requests by
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavicthemselves. The module would, on its own, determine whether the
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavicrequest had an entity, how many bytes it was, and then called a
69301145375a889e7e37caf7cc7321ac0f91801erpluemfunction (<CODE>read_client_block</CODE>) to get the data.
69301145375a889e7e37caf7cc7321ac0f91801erpluem<P>However, HTTP/1.1 requires several things of POST and PUT request
506bfe33206b2fece40ef25f695af39dd4130facjkaluzahandlers that did not fit into this module, and all existing modules
506bfe33206b2fece40ef25f695af39dd4130facjkaluzahave to be rewritten. The API calls for handling this have been
506bfe33206b2fece40ef25f695af39dd4130facjkaluzafurther abstracted, so that future HTTP protocol changes can be
506bfe33206b2fece40ef25f695af39dd4130facjkaluzaaccomplished while remaining backwards-compatible.</P>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic int ap_setup_client_block (request_rec *, int read_policy);
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic int ap_should_client_block (request_rec *);
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic long ap_get_client_block (request_rec *, char *buffer, int buffer_size);
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic<LI>Call <CODE>ap_setup_client_block()</CODE> near the beginning of the request
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic handler. This will set up all the necessary properties, and
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic will return either OK, or an error code. If the latter,
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic the module should return that error code. The second parameter
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic selects the policy to apply if the request message indicates a
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic body, and how a chunked
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic transfer-coding should be interpreted. Choose one of
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic REQUEST_NO_BODY Send 413 error if message has any body
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me.
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener REQUEST_CHUNKED_PASS Pass the chunks to me without removal.
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener In order to use the last two options, the caller MUST provide a buffer
44ff304057225e944e220e981d434a046d14cf06covener large enough to hold a chunk-size line, including any extensions.
5d1ba75b8794925e67591c209085a49279791de9covener<LI>When you are ready to possibly accept input, call
5d1ba75b8794925e67591c209085a49279791de9covener This will tell the module whether or not to read input. If it is 0,
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand the module should assume that the input is of a non-entity type
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand (<EM>e.g.</EM>, a GET request). A nonzero response indicates that the module
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand should proceed (to step 3).
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand This step also sends a 100 Continue response
caad2986f81ab263f7af41467dd622dc9add17f3ylavic to HTTP/1.1 clients, so should not be called until the module
caad2986f81ab263f7af41467dd622dc9add17f3ylavic is <STRONG>*definitely*</STRONG> ready to read content. (otherwise, the
caad2986f81ab263f7af41467dd622dc9add17f3ylavic point of the
caad2986f81ab263f7af41467dd622dc9add17f3ylavic 100 response is defeated). Never call this function more than once.
f7317ff316c2b141feea31bddb74d5d3fa1584edjorton<LI>Finally, call <CODE>ap_get_client_block</CODE> in a loop. Pass it a
f7317ff316c2b141feea31bddb74d5d3fa1584edjorton buffer and its
2165214331e4afafca4048f66f303d0253d7b001covener size. It will put data into the buffer (not necessarily the full
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem buffer, in the case of chunked inputs), and return the length of
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem the input block. When it is done reading, it will
1e2d421a36999d292042a5539971070d54aa6c63ylavic return 0 if EOF, or -1 if there was an error.
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh<P>As an example, please look at the code in
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh<CODE>mod_cgi.c</CODE>. This is properly written to the new API
0b67eb8568cd58bb77082703951679b42cf098actrawickguidelines.</P>
0b67eb8568cd58bb77082703951679b42cf098actrawick<!--#include virtual="footer.html" -->