granicus.if.org Git - apache/blob - docs/manual/misc/client_block_api.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Reading Client Input in Apache 1.2</TITLE>
   5 </HEAD>
   6
   7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   8 <BODY
   9  BGCOLOR="#FFFFFF"
  10  TEXT="#000000"
  11  LINK="#0000FF"
  12  VLINK="#000080"
  13  ALINK="#FF0000"
  14 >
  15 <!--#include virtual="header.html" -->
  16 <H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</H1>
  17
  18 <HR>
  19
  20 <P>Apache 1.1 and earlier let modules handle POST and PUT requests by
  21 themselves. The module would, on its own, determine whether the
  22 request had an entity, how many bytes it was, and then called a
  23 function (<CODE>read_client_block</CODE>) to get the data.
  24
  25 <P>However, HTTP/1.1 requires several things of POST and PUT request
  26 handlers that did not fit into this module, and all existing modules
  27 have to be rewritten. The API calls for handling this have been
  28 further abstracted, so that future HTTP protocol changes can be
  29 accomplished while remaining backwards-compatible.</P>
  30
  31 <HR>
  32
  33 <H3>The New API Functions</H3>
  34
  35 <PRE>
  36    int ap_setup_client_block (request_rec *, int read_policy);
  37    int ap_should_client_block (request_rec *);
  38    long ap_get_client_block (request_rec *, char *buffer, int buffer_size);
  39 </PRE>
  40
  41 <OL>
  42 <LI>Call <CODE>ap_setup_client_block()</CODE> near the beginning of the request
  43     handler. This will set up all the necessary properties, and
  44     will return either OK, or an error code. If the latter,
  45     the module should return that error code. The second parameter
  46     selects the policy to apply if the request message indicates a
  47     body, and how a chunked
  48     transfer-coding should be interpreted. Choose one of
  49 <PRE>
  50     REQUEST_NO_BODY          Send 413 error if message has any body
  51     REQUEST_CHUNKED_ERROR    Send 411 error if body without Content-Length
  52     REQUEST_CHUNKED_DECHUNK  If chunked, remove the chunks for me.
  53     REQUEST_CHUNKED_PASS     Pass the chunks to me without removal.
  54 </PRE>
  55     In order to use the last two options, the caller MUST provide a buffer
  56     large enough to hold a chunk-size line, including any extensions.
  57
  58
  59
  60 <LI>When you are ready to possibly accept input, call
  61     <CODE>ap_should_client_block()</CODE>.
  62     This will tell the module whether or not to read input. If it is 0,
  63     the module should assume that the input is of a non-entity type
  64     (<EM>e.g.</EM>, a GET request). A nonzero response indicates that the module
  65     should proceed (to step 3).
  66     This step also sends a 100 Continue response
  67     to HTTP/1.1 clients, so should not be called until the module
  68     is <STRONG>*definitely*</STRONG> ready to read content. (otherwise, the
  69     point of the
  70     100 response is defeated). Never call this function more than once.
  71
  72 <LI>Finally, call <CODE>ap_get_client_block</CODE> in a loop. Pass it a
  73     buffer and its
  74     size. It will put data into the buffer (not necessarily the full
  75     buffer, in the case of chunked inputs), and return the length of
  76     the input block. When it is done reading, it will
  77     return 0 if EOF, or -1 if there was an error.
  78
  79 </OL>
  80
  81 <P>As an example, please look at the code in
  82 <CODE>mod_cgi.c</CODE>. This is properly written to the new API
  83 guidelines.</P>
  84
  85 <!--#include virtual="footer.html" -->
  86 </BODY>
  87 </HTML>