Mercurial > hg > nginx-site
comparison xml/en/docs/dev/development_guide.xml @ 1970:a1d29eda04b6
The HTTP request body section of the development guide.
author | Roman Arutyunyan <arut@nginx.com> |
---|---|
date | Wed, 19 Apr 2017 18:42:45 +0300 |
parents | 275c928ab386 |
children | 5fb870087b76 |
comparison
equal
deleted
inserted
replaced
1969:275c928ab386 | 1970:a1d29eda04b6 |
---|---|
5042 If <literal>count</literal> is positive, there are unfinished activities | 5042 If <literal>count</literal> is positive, there are unfinished activities |
5043 within the request, which will be finalized at a later point. | 5043 within the request, which will be finalized at a later point. |
5044 </listitem> | 5044 </listitem> |
5045 | 5045 |
5046 </list> | 5046 </list> |
5047 | |
5048 </section> | |
5049 | |
5050 | |
5051 <section name="Request body" id="http_request_body"> | |
5052 | |
5053 <para> | |
5054 For dealing with client request body, nginx provides the following functions: | |
5055 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> and | |
5056 <literal>ngx_http_discard_request_body(r)</literal>. | |
5057 The first function reads the request body and makes it available via the | |
5058 <literal>request_body</literal> request field. | |
5059 The second function instructs nginx to discard (read and ignore) the request | |
5060 body. | |
5061 One of these functions must be called for every request. | |
5062 Normally, it is done in the content handler. | |
5063 </para> | |
5064 | |
5065 <para> | |
5066 Reading or discarding client request body from a subrequest is not allowed. | |
5067 It should always be done in the main request. | |
5068 When a subrequest is created, it inherits the parent | |
5069 <literal>request_body</literal> object which can be used by the subrequest if | |
5070 the main request has previously read the request body. | |
5071 </para> | |
5072 | |
5073 <para> | |
5074 The function | |
5075 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> starts | |
5076 the process of reading the request body. | |
5077 When the body is completely read, the <literal>post_handler</literal> callback | |
5078 is called to continue processing the request. | |
5079 If request body is missing or already read, the callback is called immediately. | |
5080 The function | |
5081 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> | |
5082 allocates the <literal>request_body</literal> request field of type | |
5083 <literal>ngx_http_request_body_t</literal>. | |
5084 The field <literal>bufs</literal> of this object keeps the result as a buffer | |
5085 chain. | |
5086 The body can be saved in memory buffers or file buffers, if | |
5087 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/> | |
5088 is not enough to fit the entire body in memory. | |
5089 </para> | |
5090 | |
5091 <para> | |
5092 The following example reads client request body and returns its size. | |
5093 </para> | |
5094 | |
5095 <programlisting> | |
5096 ngx_int_t | |
5097 ngx_http_foo_content_handler(ngx_http_request_t *r) | |
5098 { | |
5099 ngx_int_t rc; | |
5100 | |
5101 rc = ngx_http_read_client_request_body(r, ngx_http_foo_init); | |
5102 | |
5103 if (rc >= NGX_HTTP_SPECIAL_RESPONSE) { | |
5104 /* error */ | |
5105 return rc; | |
5106 } | |
5107 | |
5108 return NGX_DONE; | |
5109 } | |
5110 | |
5111 | |
5112 void | |
5113 ngx_http_foo_init(ngx_http_request_t *r) | |
5114 { | |
5115 off_t len; | |
5116 ngx_buf_t *b; | |
5117 ngx_int_t rc; | |
5118 ngx_chain_t *in, out; | |
5119 | |
5120 if (r->request_body == NULL) { | |
5121 ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR); | |
5122 return; | |
5123 } | |
5124 | |
5125 len = 0; | |
5126 | |
5127 for (in = r->request_body->bufs; in; in = in->next) { | |
5128 len += ngx_buf_size(in->buf); | |
5129 } | |
5130 | |
5131 b = ngx_create_temp_buf(r->pool, NGX_OFF_T_LEN); | |
5132 if (b == NULL) { | |
5133 ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR); | |
5134 return; | |
5135 } | |
5136 | |
5137 b->last = ngx_sprintf(b->pos, "%O", len); | |
5138 b->last_buf = (r == r->main) ? 1: 0; | |
5139 b->last_in_chain = 1; | |
5140 | |
5141 r->headers_out.status = NGX_HTTP_OK; | |
5142 r->headers_out.content_length_n = b->last - b->pos; | |
5143 | |
5144 rc = ngx_http_send_header(r); | |
5145 | |
5146 if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) { | |
5147 ngx_http_finalize_request(r, rc); | |
5148 return; | |
5149 } | |
5150 | |
5151 out.buf = b; | |
5152 out.next = NULL; | |
5153 | |
5154 rc = ngx_http_output_filter(r, &out); | |
5155 | |
5156 ngx_http_finalize_request(r, rc); | |
5157 } | |
5158 </programlisting> | |
5159 | |
5160 <para> | |
5161 The following fields of the request affect the way request body is read: | |
5162 </para> | |
5163 | |
5164 <list type="bullet"> | |
5165 | |
5166 <listitem> | |
5167 <literal>request_body_in_single_buf</literal> - read body to a single memory | |
5168 buffer | |
5169 </listitem> | |
5170 | |
5171 <listitem> | |
5172 <literal>request_body_in_file_only</literal> - always read body to a file, | |
5173 even if fits the memory buffer | |
5174 </listitem> | |
5175 | |
5176 <listitem> | |
5177 <literal>request_body_in_persistent_file</literal> - do not unlink the file | |
5178 right after creation. | |
5179 Such a file can be moved to another directory | |
5180 </listitem> | |
5181 | |
5182 <listitem> | |
5183 <literal>request_body_in_clean_file</literal> - unlink the file the when the | |
5184 request is finalized. | |
5185 This can be useful when a file was supposed to be moved to another directory | |
5186 but eventually was not moved for some reason | |
5187 </listitem> | |
5188 | |
5189 <listitem> | |
5190 <literal>request_body_file_group_access</literal> - enable file group access. | |
5191 By default a file is created with 0600 access mask. | |
5192 When the flag is set, 0660 access mask is used | |
5193 </listitem> | |
5194 | |
5195 <listitem> | |
5196 <literal>request_body_file_log_level</literal> - log file errors with this | |
5197 log level | |
5198 </listitem> | |
5199 | |
5200 <listitem> | |
5201 <literal>request_body_no_buffering</literal> - read request body without | |
5202 buffering | |
5203 </listitem> | |
5204 | |
5205 </list> | |
5206 | |
5207 <para> | |
5208 When the <literal>request_body_no_buffering</literal> flag is set, the | |
5209 unbuffered mode of reading the request body is enabled. | |
5210 In this mode, after calling | |
5211 <literal>ngx_http_read_client_request_body()</literal>, the | |
5212 <literal>bufs</literal> chain may keep only a part of the body. | |
5213 To read the next part, the | |
5214 <literal>ngx_http_read_unbuffered_request_body(r)</literal> function should be | |
5215 called. | |
5216 The return value of <literal>NGX_AGAIN</literal> and the request flag | |
5217 <literal>reading_body</literal> indicate that more data is available. | |
5218 If <literal>bufs</literal> is NULL after calling this function, there is | |
5219 nothing to read at the moment. | |
5220 The request callback <literal>read_event_handler</literal> will be called when | |
5221 the next part of request body is available. | |
5222 </para> | |
5047 | 5223 |
5048 </section> | 5224 </section> |
5049 | 5225 |
5050 | 5226 |
5051 <section name="Response" id="http_response"> | 5227 <section name="Response" id="http_response"> |