From 92b54aacc0de5446dd5497c39897b0bbff72e626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 13 Jun 2018 09:54:12 +0200 Subject: Rebuild using Asciideck --- .../2.4/manual/cowboy_req.read_part/index.html | 200 +++++++-------------- 1 file changed, 66 insertions(+), 134 deletions(-) (limited to 'docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html') diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html index 50931838..7746b475 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html @@ -62,162 +62,94 @@

cowboy_req:read_part(3)

-

Name

-
-

cowboy_req:read_part - Read the next multipart headers

-
-
-
+

cowboy_req:read_part - Read the next multipart headers

Description

-
-
-
-
read_part(Req :: cowboy_req:req())
-    -> read_part(Req, #{})
-
-read_part(Req :: cowboy_req:req(), Opts)
-    -> {ok, Headers, Req} | {done, Req}
-
-Opts    :: cowboy_req:read_body_opts()
-Headers :: #{binary() => binary()}
-

Read the next part of a multipart body.

-

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 -multipart/form-data and multipart/byteranges.

-

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.

-

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.

-

The headers returned are MIME headers, NOT HTTP headers. -They can be parsed using the functions from the cow_multipart -module. In addition, the cow_multipart:form_data/1 function -can be used to quickly extract information from multipart/form-data -representations.

-

Once a part has been read, it can not be read again.

-

Once the body has been read, Cowboy sets the content-length -header if it was not previously provided.

-
-
-
+
read_part(Req :: cowboy_req:req())
+    -> read_part(Req, #{})
+
+read_part(Req :: cowboy_req:req(), Opts)
+    -> {ok, Headers, Req} | {done, Req}
+
+Opts    :: cowboy_req:read_body_opts()
+Headers :: #{binary() => binary()}
+
+

Read the next part of a multipart body.

+

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 multipart/form-data and multipart/byteranges.

+

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.

+

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.

+

The headers returned are MIME headers, NOT HTTP headers. They can be parsed using the functions from the cow_multipart module. In addition, the cow_multipart:form_data/1 function can be used to quickly extract information from multipart/form-data representations.

+ +

Once a part has been read, it can not be read again.

+

Once the body has been read, Cowboy sets the content-length header if it was not previously provided.

+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-Opts -
-
-

-A map of body reading options. Please refer to -cowboy_req:read_body(3) -for details about each option. -

-

This function defaults the length to 64KB and the period -to 5 seconds.

+
Opts
+

A map of body reading options. Please refer to cowboy_req:read_body(3) for details about each option.

+

This function defaults the length to 64KB and the period to 5 seconds.

-
-
- -
+

Return value

-
-

An ok tuple is returned containing the next part’s headers -as a map.

-

A done tuple is returned if there are no more parts to read.

-

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.

-
-
-
+

An ok tuple is returned containing the next part's headers as a map.

+

A done tuple is returned if there are no more parts to read.

+

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.

Changelog

-
-
    -
  • -

    -2.0: Function introduced. Replaces part/1,2. -

    +
    • 2.0: Function introduced. Replaces part/1,2.
      • -
-
-
-
+

Examples

-
-
-
Read all parts
-
-
acc_multipart(Req0, Acc) ->
-    case cowboy_req:read_part(Req0) of
-        {ok, Headers, Req1} ->
-            {ok, Body, Req} = stream_body(Req1, <<>>),
-            acc_multipart(Req, [{Headers, Body}|Acc]);
-        {done, Req} ->
-            {lists:reverse(Acc), Req}
-    end.
-
-stream_body(Req0, Acc) ->
-    case cowboy_req:read_part_body(Req0) of
-        {more, Data, Req} ->
-            stream_body(Req, << Acc/binary, Data/binary >>);
-        {ok, Data, Req} ->
-            {ok, << Acc/binary, Data/binary >>, Req}
-    end.
-
-
Read all part headers, skipping bodies
-
-
skip_body_multipart(Req0, Acc) ->
-    case cowboy_req:read_part(Req0) of
-        {ok, Headers, Req} ->
-            skip_body_multipart(Req, [Headers|Acc]);
-        {done, Req} ->
-            {lists:reverse(Acc), Req}
-    end.
-
-
Read a part header in larger chunks
-
-
{ok, Headers, Req} = cowboy_req:read_part(Req0, #{length => 1000000}).
-
-
-
+
{ok, Headers, Req} = cowboy_req:read_part(Req0, #{length => 1000000}).
+

See also

-
-

cowboy_req(3), -cowboy_req:has_body(3), -cowboy_req:body_length(3), -cowboy_req:read_body(3), -cowboy_req:read_urlencoded_body(3), -cowboy_req:read_part_body(3)

-
- +

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:body_length(3), cowboy_req:read_body(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_part_body(3)

+ -- cgit v1.2.3