diff options
Diffstat (limited to 'manual/cowboy_req.md')
| -rw-r--r-- | manual/cowboy_req.md | 65 |
1 files changed, 58 insertions, 7 deletions
diff --git a/manual/cowboy_req.md b/manual/cowboy_req.md index d7af41f..91139ac 100644 --- a/manual/cowboy_req.md +++ b/manual/cowboy_req.md @@ -408,6 +408,51 @@ Request body related exports > will perform all the required initialization when it is > called the first time. +### part(Req) -> {ok, Headers, Req2} | {done, Req2} + +> Types: +> * Headers = cow_multipart:headers() +> +> Read the headers for the next part of the multipart message. +> +> 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. +> +> 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 figure out `multipart/form-data` messages. +> It takes the list of headers and returns whether this part is +> a simple form field or a file being uploaded. +> +> Note that once a part has been read, or skipped, it cannot +> be read again. + +### part_body(Req) -> part_body(8000000, Req) +### part_body(MaxReadSize, Req) -> {ok, Data, Req2} | {more, Data, Req2} + +> Types: +> * MaxReadSize = non_neg_integer() +> * Data = binary() +> +> Read the body of the current part of the multipart message. +> +> This function will read the body up to `MaxReadSize` bytes. +> This is a soft limit. If there are more data to be read +> from the socket for this part, the function will return +> what it could read inside a `more` tuple. Otherwise, it +> will return an `ok` tuple. +> +> Calling this function again after receiving a `more` tuple +> will return another chunk of body. The last chunk will be +> returned inside an `ok` tuple. +> +> Note that once the body has been read, fully or partially, +> it cannot be read again. + ### skip_body(Req) -> {ok, Req2} | {error, Reason} > Types: @@ -419,26 +464,31 @@ Request body related exports > read before. ### stream_body(Req) -> stream_body(1000000, Req) -### stream_body(MaxSegmentSize, Req) -> {ok, Data, Req2} +### stream_body(MaxReadSize, Req) -> {ok, Data, Req2} | {done, Req2} | {error, Reason} > Types: -> * MaxSegmentSize = non_neg_integer() +> * MaxReadSize = non_neg_integer() > * Data = binary() > * Reason = atom() > > Stream the request body. > -> This function will return a segment of the request body -> with a size of up to `MaxSegmentSize`, or 1MB by default. -> This function can be called repeatedly until a `done` tuple -> is returned, indicating the body has been fully received. +> This function will return the next segment of the body. > > Cowboy will properly handle chunked transfer-encoding by > default. If any other transfer-encoding or content-encoding > has been used for the request, custom decoding functions > can be used. They must be specified using `init_stream/4`. > +> The amount of data returned by this function may vary +> depending on the current state of the request. If data +> is already available in the buffer then it is used fully, +> otherwise Cowboy will read up to `MaxReadSize` bytes from +> the socket. By default Cowboy will read up to 1MB of data. +> It is then decoded, which may grow or shrink it, depending +> on the encoding headers, before it is finally returned. +> > After the body has been streamed fully, Cowboy will remove > the transfer-encoding header from the `Req` object, and add > the content-length header if it wasn't already there. @@ -564,7 +614,8 @@ Response related exports > > If a `Length` is provided, it will be sent in the > content-length header in the response. It is recommended -> to set the length if it can be known in advance. +> to set the length if it can be known in advance. Otherwise, +> the transfer-encoding header will be set to identity. > > This function will only be called if the response is sent > using the `reply/2` or `reply/3` function. |