mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 20:50:24 +00:00
94 lines
2.4 KiB
Text
94 lines
2.4 KiB
Text
= cowboy_req:read_urlencoded_body(3)
|
|
|
|
== Name
|
|
|
|
cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body
|
|
|
|
== Description
|
|
|
|
[source,erlang]
|
|
----
|
|
read_urlencoded_body(Req :: cowboy_req:req())
|
|
-> read_urlencoded_body(Req, #{})
|
|
|
|
read_urlencoded_body(Req :: cowboy_req:req(), Opts)
|
|
-> {ok, Body, Req}
|
|
|
|
Opts :: cowboy_req:read_body_opts()
|
|
Body :: [{Key :: binary(), Value :: binary() | true}]
|
|
----
|
|
|
|
Read and parse a urlencoded request body.
|
|
|
|
This function reads the request body and parses it as
|
|
`application/x-www-form-urlencoded`. It returns a list
|
|
of key/values.
|
|
|
|
The urlencoded media type is used by Web browsers when
|
|
submitting HTML forms using the POST method.
|
|
|
|
Cowboy needs to read the full body before parsing. By default
|
|
it will read bodies of size up to 64KB. It is possible to
|
|
provide options to read larger bodies if required.
|
|
|
|
Cowboy will automatically handle protocol details including
|
|
the expect header, chunked transfer-encoding and others.
|
|
|
|
Once the body has been read, Cowboy sets the content-length
|
|
header if it was not previously provided.
|
|
|
|
This function can only be called once. Calling it again will
|
|
result in undefined behavior.
|
|
|
|
== Arguments
|
|
|
|
Req::
|
|
|
|
The Req object.
|
|
|
|
Opts::
|
|
|
|
A map of body reading options. Please refer to
|
|
link:man:cowboy_req:read_body(3)[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 a list of key/values found
|
|
in the body.
|
|
|
|
The Req object returned in the tuple must be used from 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 `body_qs/1,2`.
|
|
|
|
== Examples
|
|
|
|
.Read a urlencoded body
|
|
[source,erlang]
|
|
----
|
|
{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0),
|
|
{_, Lang} = lists:keyfind(<<"lang">>, 1, Body).
|
|
----
|
|
|
|
.Allow large urlencoded bodies
|
|
[source,erlang]
|
|
----
|
|
{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0, #{length => 1000000}).
|
|
----
|
|
|
|
== See also
|
|
|
|
link:man:cowboy_req(3)[cowboy_req(3)],
|
|
link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)],
|
|
link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)],
|
|
link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)],
|
|
link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)],
|
|
link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)]
|