aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/guide/http.asciidoc12
-rw-r--r--doc/src/manual/gun.asciidoc2
-rw-r--r--doc/src/manual/gun.headers.asciidoc86
-rw-r--r--doc/src/manual/gun.patch.asciidoc12
-rw-r--r--doc/src/manual/gun.post.asciidoc12
-rw-r--r--doc/src/manual/gun.put.asciidoc12
-rw-r--r--doc/src/manual/gun.request.asciidoc16
7 files changed, 120 insertions, 32 deletions
diff --git a/doc/src/guide/http.asciidoc b/doc/src/guide/http.asciidoc
index 652030a..fb0c7dc 100644
--- a/doc/src/guide/http.asciidoc
+++ b/doc/src/guide/http.asciidoc
@@ -108,7 +108,7 @@ desirable. The request body of a PATCH method may be a partial
representation or a list of instructions on how to update the
resource.
-The `gun:post/4,5`, `gun:put/4,5` and `gun:patch/4,5` functions
+The functions `gun:post/4,5`, `gun:put/4,5` and `gun:patch/4,5`
take a body as their fourth argument. These functions do
not require any body-specific header to be set, although
it is always recommended to set the content-type header.
@@ -127,13 +127,9 @@ StreamRef = gun:post(ConnPid, "/organizations/ninenines", [
], Body).
----
-The `gun:post/3`, `gun:put/3` and `gun:patch/3` functions
-do not take a body in their arguments. If a body is to be
-provided later on, using the `gun:data/4` function, then
-the request headers must indicate this. This can be done
-by setting the content-length or content-type request
-headers. If these headers are not set then Gun will assume
-the request has no body.
+The functions `gun:post/3,4`, `gun:put/3,4` and `gun:patch/3,4`
+do not take a body in their arguments: the body must be
+provided later on using the `gun:data/4` function.
It is recommended to send the content-length header if you
know it in advance, although this is not required. If it
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index a210635..1b4e6d7 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -29,6 +29,7 @@ Requests:
* link:man:gun:post(3)[gun:post(3)] - Process the enclosed representation according to a resource's own semantics
* link:man:gun:put(3)[gun:put(3)] - Create or replace a resource
* link:man:gun:delete(3)[gun:delete(3)] - Delete a resource
+* link:man:gun:headers(3)[gun:headers(3)] - Initiate the given request
* link:man:gun:request(3)[gun:request(3)] - Perform the given request
* link:man:gun:data(3)[gun:data(3)] - Stream the body of a request
@@ -313,6 +314,7 @@ undocumented and must be set to `gun_ws_h`.
== Changelog
+* *2.0*: Function `gun:headers/4,5` introduced.
* *1.3*: Add the CONNECT destination's `protocols` option and
deprecate the previously introduced `protocol` option.
* *1.2*: Introduce the type `connect_destination()`.
diff --git a/doc/src/manual/gun.headers.asciidoc b/doc/src/manual/gun.headers.asciidoc
new file mode 100644
index 0000000..bab1b82
--- /dev/null
+++ b/doc/src/manual/gun.headers.asciidoc
@@ -0,0 +1,86 @@
+= gun:headers(3)
+
+== Name
+
+gun:headers - Initiate the given request
+
+== Description
+
+[source,erlang]
+----
+headers(ConnPid, Method, Path, Headers)
+ -> headers(ConnPid, Method, Path, Headers, #{})
+
+headers(ConnPid, Method, Path, Headers, ReqOpts)
+ -> StreamRef
+
+ConnPid :: pid()
+Method :: binary()
+Path :: iodata()
+Headers :: [{binary(), iodata()}]
+ReqOpts :: gun:req_opts()
+StreamRef :: reference()
+----
+
+Initiate the given request.
+
+This is a general purpose function that should only be
+used when other method-specific functions do not apply.
+
+The function `headers/4,5` initiates a request but does
+not send the request body. It must be sent separately
+using link:man:gun:data(3)[gun:data(3)].
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Method::
+
+Method to be used for the request.
+
+Path::
+
+Path to the resource.
+
+Headers::
+
+Additional request headers.
+
+ReqOpts::
+
+Request options.
+
+== Return value
+
+A reference that identifies the newly created stream is
+returned. It is this reference that must be passed in
+subsequent calls and will be received in messages related
+to this new stream.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Initiate a request
+[source,erlang]
+----
+StreamRef = gun:headers(ConnPid, <<"PUT">>,
+ "/lang/fr_FR/hello",
+ [{<<"content-type">>, <<"text/plain">>}]).
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:request(3)[gun:request(3)],
+link:man:gun:await(3)[gun:await(3)],
+link:man:gun:await_body(3)[gun:await_body(3)],
+link:man:gun_push(3)[gun_push(3)],
+link:man:gun_inform(3)[gun_inform(3)],
+link:man:gun_response(3)[gun_response(3)],
+link:man:gun_data(3)[gun_data(3)]
diff --git a/doc/src/manual/gun.patch.asciidoc b/doc/src/manual/gun.patch.asciidoc
index 3f7baa9..c240a4d 100644
--- a/doc/src/manual/gun.patch.asciidoc
+++ b/doc/src/manual/gun.patch.asciidoc
@@ -9,6 +9,9 @@ gun:patch - Apply a set of changes to a resource
[source,erlang]
----
patch(ConnPid, Path, Headers)
+ -> patch(ConnPid, Path, Headers, #{})
+
+patch(ConnPid, Path, Headers, ReqOpts)
-> StreamRef
patch(ConnPid, Path, Headers, Body)
@@ -30,10 +33,8 @@ Apply a set of changes to a resource.
The behavior of this function varies depending on whether
a body is provided.
-The function `patch/3` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
+The function `patch/3,4` does not send a body. It must be
+sent separately using link:man:gun:data(3)[gun:data(3)].
The function `patch/4,5` sends the entire request, including
the request body, immediately. It is therefore not possible
@@ -75,6 +76,9 @@ to this new stream.
== Changelog
+* *2.0*: Implicit body detection has been removed. The body
+ must now be provided either directly (even if empty)
+ or using separate calls.
* *1.0*: Function introduced.
== Examples
diff --git a/doc/src/manual/gun.post.asciidoc b/doc/src/manual/gun.post.asciidoc
index e548824..aed8b3f 100644
--- a/doc/src/manual/gun.post.asciidoc
+++ b/doc/src/manual/gun.post.asciidoc
@@ -9,6 +9,9 @@ gun:post - Process the enclosed representation according to a resource's own sem
[source,erlang]
----
post(ConnPid, Path, Headers)
+ -> post(ConnPid, Path, Headers, #{})
+
+post(ConnPid, Path, Headers, ReqOpts)
-> StreamRef
post(ConnPid, Path, Headers, Body)
@@ -31,10 +34,8 @@ own semantics.
The behavior of this function varies depending on whether
a body is provided.
-The function `post/3` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
+The function `post/3,4` does not send a body. It must be
+sent separately using link:man:gun:data(3)[gun:data(3)].
The function `post/4,5` sends the entire request, including
the request body, immediately. It is therefore not possible
@@ -73,6 +74,9 @@ to this new stream.
== Changelog
+* *2.0*: Implicit body detection has been removed. The body
+ must now be provided either directly (even if empty)
+ or using separate calls.
* *1.0*: Function introduced.
== Examples
diff --git a/doc/src/manual/gun.put.asciidoc b/doc/src/manual/gun.put.asciidoc
index 4f0cb39..a60849b 100644
--- a/doc/src/manual/gun.put.asciidoc
+++ b/doc/src/manual/gun.put.asciidoc
@@ -9,6 +9,9 @@ gun:put - Create or replace a resource
[source,erlang]
----
put(ConnPid, Path, Headers)
+ -> put(ConnPid, Path, Headers, #{})
+
+put(ConnPid, Path, Headers, ReqOpts)
-> StreamRef
put(ConnPid, Path, Headers, Body)
@@ -30,10 +33,8 @@ Create or replace a resource.
The behavior of this function varies depending on whether
a body is provided.
-The function `put/3` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
+The function `put/3,4` does not send a body. It must be
+sent separately using link:man:gun:data(3)[gun:data(3)].
The function `put/4,5` sends the entire request, including
the request body, immediately. It is therefore not possible
@@ -72,6 +73,9 @@ to this new stream.
== Changelog
+* *2.0*: Implicit body detection has been removed. The body
+ must now be provided either directly (even if empty)
+ or using separate calls.
* *1.0*: Function introduced.
== Examples
diff --git a/doc/src/manual/gun.request.asciidoc b/doc/src/manual/gun.request.asciidoc
index ec169ac..f5c1cd8 100644
--- a/doc/src/manual/gun.request.asciidoc
+++ b/doc/src/manual/gun.request.asciidoc
@@ -8,9 +8,6 @@ gun:request - Perform the given request
[source,erlang]
----
-request(ConnPid, Method, Path, Headers)
- -> StreamRef
-
request(ConnPid, Method, Path, Headers, Body)
-> request(ConnPid, Method, Path, Headers, Body, #{})
@@ -31,15 +28,6 @@ Perform the given request.
This is a general purpose function that should only be
used when other method-specific functions do not apply.
-The behavior of this function varies depending on whether
-a body is provided.
-
-The function `request/4` expects either a content-length
-or content-type header to indicate that a body will be
-sent afterwards. Gun will assume the request has no body
-otherwise. The body can then be sent using
-link:man:gun:data(3)[gun:data(3)].
-
The function `request/5,6` sends the entire request, including
the request body, immediately. It is therefore not possible
to use link:man:gun:data(3)[gun:data(3)] after that. You
@@ -81,6 +69,9 @@ to this new stream.
== Changelog
+* *2.0*: Implicit body detection has been removed. The body
+ must now be provided either directly (even if empty)
+ or using link:man:gun:headers(3)[gun:headers(3)].
* *1.0*: Function introduced.
== Examples
@@ -97,6 +88,7 @@ StreamRef = gun:request(ConnPid, <<"PUT">>,
== See also
link:man:gun(3)[gun(3)],
+link:man:gun:headers(3)[gun:headers(3)],
link:man:gun:await(3)[gun:await(3)],
link:man:gun:await_body(3)[gun:await_body(3)],
link:man:gun_push(3)[gun_push(3)],