client_block_api.html revision 25503838e438bb909e3ff880125732c7ed5e64ad
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
bdd36cfdba3ff66d25570a9ff568d69e1eb543cfTimo Sirainen<TITLE>Reading Client Input in Apache 1.2</TITLE>
aa797403d51ff047727b77d64532001d6b6cc21aTimo Sirainen<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
ae32667c54480d329eed994b3defab89cd76c077Timo Sirainen BGCOLOR="#FFFFFF"
b6b9c99fefbbc662bd9a0006566133c4480bf0e8Timo Sirainen TEXT="#000000"
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen LINK="#0000FF"
b6b9c99fefbbc662bd9a0006566133c4480bf0e8Timo Sirainen VLINK="#000080"
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen ALINK="#FF0000"
550d2fe097e95f12e8fa60ef52753ea7fe53d4eaTimo Sirainen<!--#include virtual="header.html" -->
dff32d11a411a24f3b76003c1ae22c5a960f180eTimo Sirainen<H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</H1>
eb209d12e3b1cfed564c35cf19fdb1bf7fcc6811Timo Sirainen<P>Apache 1.1 and earlier let modules handle POST and PUT requests by
09060303d565e15d54e42b4ef722f9d3c26f5336Timo Sirainenthemselves. The module would, on its own, determine whether the
09060303d565e15d54e42b4ef722f9d3c26f5336Timo Sirainenrequest had an entity, how many bytes it was, and then called a
a5ddfd7a8b473f73135b93d5e081e470a87f0f7eTimo Sirainenfunction (<CODE>read_client_block</CODE>) to get the data.
ae32667c54480d329eed994b3defab89cd76c077Timo Sirainen<P>However, HTTP/1.1 requires several things of POST and PUT request
ae32667c54480d329eed994b3defab89cd76c077Timo Sirainenhandlers that did not fit into this module, and all existing modules
aa797403d51ff047727b77d64532001d6b6cc21aTimo Sirainenhave to be rewritten. The API calls for handling this have been
8c2b4a45f17a5cb13bb01058ca37798cf48d91baTimo Sirainenfurther abstracted, so that future HTTP protocol changes can be
8c2b4a45f17a5cb13bb01058ca37798cf48d91baTimo Sirainenaccomplished while remaining backwards-compatible.</P>
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen int setup_client_block (request_rec *, int read_policy);
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen int should_client_block (request_rec *);
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen long get_client_block (request_rec *, char *buffer, int buffer_size);
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<LI>Call <CODE>setup_client_block()</CODE> near the beginning of the request
009217abb57a24a4076092e8e4e165545747839eStephan Bosch handler. This will set up all the necessary properties, and
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen will return either OK, or an error code. If the latter,
009217abb57a24a4076092e8e4e165545747839eStephan Bosch the module should return that error code. The second parameter
00e7c3010f7da4a49881a7feb05e413af353af0aTimo Sirainen selects the policy to apply if the request message indicates a
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen body, and how a chunked
5f5713d6468dca1acf3d350dd8a33057331f78c5Timo Sirainen transfer-coding should be interpreted. Choose one of
5f5713d6468dca1acf3d350dd8a33057331f78c5Timo Sirainen REQUEST_NO_BODY Send 413 error if message has any body
5f5713d6468dca1acf3d350dd8a33057331f78c5Timo Sirainen REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me.
0a53eb0283d7ec28c6105f61e118b96fce8ecb95Timo Sirainen REQUEST_CHUNKED_PASS Pass the chunks to me without removal.
0a53eb0283d7ec28c6105f61e118b96fce8ecb95Timo Sirainen In order to use the last two options, the caller MUST provide a buffer
433f5c9cc560a8cbff47257513d0bacb1cf250f4Timo Sirainen large enough to hold a chunk-size line, including any extensions.
cf9d67e4a9bfee31cf3be05244555d51a3d1b9feTimo Sirainen<LI>When you are ready to possibly accept input, call
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainen This will tell the module whether or not to read input. If it is 0,
edd318d5866ac3fbc6e8df28fb24a4dfef93c884Timo Sirainen the module should assume that the input is of a non-entity type
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen (e.g. a GET request). A nonzero response indicates that the module
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen should proceed (to step 3).
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen This step also sends a 100 Continue response
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen to HTTP/1.1 clients, so should not be called until the module
4ee00532a265bdfb38539d811fcd12d51210ac35Timo Sirainen is <STRONG>*definitely*</STRONG> ready to read content. (otherwise, the point of the
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen 100 response is defeated). Never call this function more than once.
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen<LI>Finally, call <CODE>get_client_block</CODE> in a loop. Pass it a
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen buffer and its
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen size. It will put data into the buffer (not necessarily the full
2670cd577aa57eb9f915a4f4220ae48c9b4fc5fbTimo Sirainen buffer, in the case of chunked inputs), and return the length of
4ee00532a265bdfb38539d811fcd12d51210ac35Timo Sirainen the input block. When it is done reading, it will
e4194f4703eeec32b432371ae30fc8f25ab720d8Timo Sirainen return 0 if EOF, or -1 if there was an error.
58b8a301b7b36047f10a592751094fbed86d6f0cTimo Sirainen<P>As an example, please look at the code in
58b8a301b7b36047f10a592751094fbed86d6f0cTimo Sirainen<CODE>mod_cgi.c</CODE>. This is properly written to the new API
aa797403d51ff047727b77d64532001d6b6cc21aTimo Sirainenguidelines.</P>
152db3f90f298b7fb2dbbd4276f0fc30a9bc30f6Timo Sirainen<!--#include virtual="footer.html" -->