diff options
Diffstat (limited to 'docs/en/cowboy/2.3/manual/cowboy_req.read_part')
-rw-r--r-- | docs/en/cowboy/2.3/manual/cowboy_req.read_part/index.html | 200 |
1 files changed, 66 insertions, 134 deletions
diff --git a/docs/en/cowboy/2.3/manual/cowboy_req.read_part/index.html b/docs/en/cowboy/2.3/manual/cowboy_req.read_part/index.html index 4a9fa13d..0fa219b0 100644 --- a/docs/en/cowboy/2.3/manual/cowboy_req.read_part/index.html +++ b/docs/en/cowboy/2.3/manual/cowboy_req.read_part/index.html @@ -62,162 +62,94 @@ <h1 class="lined-header"><span>cowboy_req:read_part(3)</span></h1> -<div class="sect1"> <h2 id="_name">Name</h2> -<div class="sectionbody"> -<div class="paragraph"><p>cowboy_req:read_part - Read the next multipart headers</p></div> -</div> -</div> -<div class="sect1"> +<p>cowboy_req:read_part - Read the next multipart headers</p> <h2 id="_description">Description</h2> -<div class="sectionbody"> -<div class="listingblock"> -<div class="content"><!-- Generator: GNU source-highlight +<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) - <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span>, #{}) - -<span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) - <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} | {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} - -<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>() -<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}</tt></pre></div></div> -<div class="paragraph"><p>Read the next part of a multipart body.</p></div> -<div class="paragraph"><p>This function reads the request body and parses it as -multipart. Each parts of a multipart representation have -their own headers and body. This function parses and returns -headers. Examples of multipart media types are -<code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div> -<div class="paragraph"><p>Cowboy will skip any data remaining until the beginning of -the next part. This includes the preamble to the multipart -message but also the body of a previous part if it hasn’t -been read. Both are skipped automatically when calling this -function.</p></div> -<div class="paragraph"><p>Cowboy will read the body before parsing in chunks of size -up to 64KB, with a period of 5 seconds. This is tailored for -reading part headers and might not be the most efficient for -skipping the previous part’s body.</p></div> -<div class="paragraph"><p>The headers returned are MIME headers, <strong>NOT</strong> HTTP headers. -They can be parsed using the functions from the <code>cow_multipart</code> -module. In addition, the <code>cow_multipart:form_data/1</code> function -can be used to quickly extract information from <code>multipart/form-data</code> -representations.</p></div> -<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div> -<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length -header if it was not previously provided.</p></div> -</div> -</div> -<div class="sect1"> +<pre><tt><b><font color="#000000">read_part</font></b>(<font color="#009900">Req</font> <font color="#990000">::</font> <b><font color="#000000">cowboy_req:req</font></b>()) + <font color="#990000">-></font> <b><font color="#000000">read_part</font></b>(<font color="#009900">Req</font>, #{}) + +<b><font color="#000000">read_part</font></b>(<font color="#009900">Req</font> <font color="#990000">::</font> <b><font color="#000000">cowboy_req:req</font></b>(), <font color="#009900">Opts</font>) + <font color="#990000">-></font> {<font color="#FF6600">ok</font>, <font color="#009900">Headers</font>, <font color="#009900">Req</font>} | {<font color="#FF6600">done</font>, <font color="#009900">Req</font>} + +<font color="#009900">Opts</font> <font color="#990000">::</font> <b><font color="#000000">cowboy_req:read_body_opts</font></b>() +<font color="#009900">Headers</font> <font color="#990000">::</font> #{<b><font color="#000080">binary</font></b>() <font color="#990000">=></font> <b><font color="#000080">binary</font></b>()}</tt></pre> +</div></div> +<p>Read the next part of a multipart body.</p> +<p>This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body. This function parses and returns headers. Examples of multipart media types are <code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p> +<p>Cowboy will skip any data remaining until the beginning of the next part. This includes the preamble to the multipart message but also the body of a previous part if it hasn't been read. Both are skipped automatically when calling this function.</p> +<p>Cowboy will read the body before parsing in chunks of size up to 64KB, with a period of 5 seconds. This is tailored for reading part headers and might not be the most efficient for skipping the previous part's body.</p> +<p>The headers returned are MIME headers, <strong>NOT</strong> HTTP headers. They can be parsed using the functions from the <code>cow_multipart</code> module. In addition, the <code>cow_multipart:form_data/1</code> function can be used to quickly extract information from <code>multipart/form-data</code> representations.</p> +<!-- @todo Proper link to cow_multipart:form_data.--> +<p>Once a part has been read, it can not be read again.</p> +<p>Once the body has been read, Cowboy sets the content-length header if it was not previously provided.</p> +<!-- @todo Limit the maximum size of multipart headers.--> <h2 id="_arguments">Arguments</h2> -<div class="sectionbody"> -<div class="dlist"><dl> -<dt class="hdlist1"> -Req -</dt> -<dd> -<p> -The Req object. -</p> +<dl><dt>Req</dt> +<dd><p>The Req object.</p> </dd> -<dt class="hdlist1"> -Opts -</dt> -<dd> -<p> -A map of body reading options. Please refer to -<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> -for details about each option. -</p> -<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code> -to 5 seconds.</p></div> +<dt>Opts</dt> +<dd><p>A map of body reading options. Please refer to <a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> for details about each option.</p> +<p>This function defaults the <code>length</code> to 64KB and the <code>period</code> to 5 seconds.</p> </dd> -</dl></div> -</div> -</div> -<div class="sect1"> +</dl> <h2 id="_return_value">Return value</h2> -<div class="sectionbody"> -<div class="paragraph"><p>An <code>ok</code> tuple is returned containing the next part’s headers -as a map.</p></div> -<div class="paragraph"><p>A <code>done</code> tuple is returned if there are no more parts to read.</p></div> -<div class="paragraph"><p>The Req object returned in the tuple must be used for that point -onward. It contains a more up to date representation of the request. -For example it may have an added content-length header once the -body has been read.</p></div> -</div> -</div> -<div class="sect1"> +<p>An <code>ok</code> tuple is returned containing the next part's headers as a map.</p> +<p>A <code>done</code> tuple is returned if there are no more parts to read.</p> +<p>The Req object returned in the tuple must be used for that point onward. It contains a more up to date representation of the request. For example it may have an added content-length header once the body has been read.</p> <h2 id="_changelog">Changelog</h2> -<div class="sectionbody"> -<div class="ulist"><ul> -<li> -<p> -<strong>2.0</strong>: Function introduced. Replaces <code>part/1,2</code>. -</p> +<ul><li><strong>2.0</strong>: Function introduced. Replaces <code>part/1,2</code>. </li> -</ul></div> -</div> -</div> -<div class="sect1"> +</ul> <h2 id="_examples">Examples</h2> -<div class="sectionbody"> -<div class="listingblock"> -<div class="title">Read all parts</div> -<div class="content"><!-- Generator: GNU source-highlight +<div class="listingblock"><div class="title">Read all parts</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</span>) <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req1</span>, <span style="color: #990000"><<>></span>), - <span style="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req</span>, [{<span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>}|<span style="color: #009900">Acc</span>]); - {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</span>} - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> - -<span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</span>) <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> - {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>); - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, <span style="color: #009900">Req</span>} - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="listingblock"> -<div class="title">Read all part headers, skipping bodies</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">acc_multipart</font></b>(<font color="#009900">Req0</font>, <font color="#009900">Acc</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">Headers</font>, <font color="#009900">Req1</font>} <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#009900">Body</font>, <font color="#009900">Req</font>} <font color="#990000">=</font> <b><font color="#000000">stream_body</font></b>(<font color="#009900">Req1</font>, <font color="#990000"><<>></font>), + <b><font color="#000000">acc_multipart</font></b>(<font color="#009900">Req</font>, [{<font color="#009900">Headers</font>, <font color="#009900">Body</font>}|<font color="#009900">Acc</font>]); + {<font color="#FF6600">done</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + {<b><font color="#000000">lists:reverse</font></b>(<font color="#009900">Acc</font>), <font color="#009900">Req</font>} + <b><font color="#0000FF">end</font></b><font color="#990000">.</font> + +<b><font color="#000000">stream_body</font></b>(<font color="#009900">Req0</font>, <font color="#009900">Acc</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part_body</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">more</font>, <font color="#009900">Data</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <b><font color="#000000">stream_body</font></b>(<font color="#009900">Req</font>, <font color="#990000"><<</font> <font color="#009900">Acc</font><font color="#990000">/</font><b><font color="#000080">binary</font></b>, <font color="#009900">Data</font><font color="#990000">/</font><b><font color="#000080">binary</font></b> <font color="#990000">>></font>); + {<font color="#FF6600">ok</font>, <font color="#009900">Data</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + {<font color="#FF6600">ok</font>, <font color="#990000"><<</font> <font color="#009900">Acc</font><font color="#990000">/</font><b><font color="#000080">binary</font></b>, <font color="#009900">Data</font><font color="#990000">/</font><b><font color="#000080">binary</font></b> <font color="#990000">>></font>, <font color="#009900">Req</font>} + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<div class="listingblock"><div class="title">Read all part headers, skipping bodies</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</span>) <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> - {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req</span>, [<span style="color: #009900">Headers</span>|<span style="color: #009900">Acc</span>]); - {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> - {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</span>} - <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="listingblock"> -<div class="title">Read a part header in larger chunks</div> -<div class="content"><!-- Generator: GNU source-highlight +<pre><tt><b><font color="#000000">skip_body_multipart</font></b>(<font color="#009900">Req0</font>, <font color="#009900">Acc</font>) <font color="#990000">-></font> + <b><font color="#0000FF">case</font></b> <b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req0</font>) <b><font color="#0000FF">of</font></b> + {<font color="#FF6600">ok</font>, <font color="#009900">Headers</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + <b><font color="#000000">skip_body_multipart</font></b>(<font color="#009900">Req</font>, [<font color="#009900">Headers</font>|<font color="#009900">Acc</font>]); + {<font color="#FF6600">done</font>, <font color="#009900">Req</font>} <font color="#990000">-></font> + {<b><font color="#000000">lists:reverse</font></b>(<font color="#009900">Acc</font>), <font color="#009900">Req</font>} + <b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre> +</div></div> +<div class="listingblock"><div class="title">Read a part header in larger chunks</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> +<pre><tt>{<font color="#FF6600">ok</font>, <font color="#009900">Headers</font>, <font color="#009900">Req</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:read_part</font></b>(<font color="#009900">Req0</font>, #{<b><font color="#000080">length</font></b> <font color="#990000">=></font> <font color="#993399">1000000</font>})<font color="#990000">.</font></tt></pre> +</div></div> <h2 id="_see_also">See also</h2> -<div class="sectionbody"> -<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, -<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, -<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, -<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, -<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, -<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> -</div> -</div> +<p><a href="../cowboy_req">cowboy_req(3)</a>, <a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, <a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, <a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, <a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, <a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p> + |