1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
= gun:ws_upgrade(3)
== Name
gun:ws_upgrade - Upgrade to Websocket
== Description
[source,erlang]
----
ws_upgrade(ConnPid, Path)
-> ws_upgrade(ConnPid, Path, [])
ws_upgrade(ConnPid, Path, Headers)
-> StreamRef
ws_upgrade(ConnPid, Path, Headers, WsOpts)
-> StreamRef
ConnPid :: pid()
Path :: iodata()
Headers :: gun:req_headers()
WsOpts :: gun:ws_opts()
StreamRef :: gun:stream_ref()
----
Upgrade to Websocket.
The behavior of this function depends on the protocol
selected.
HTTP/1.1 cannot handle Websocket and HTTP requests
concurrently. The upgrade, if successful, will result
in the complete takeover of the connection. Any
subsequent HTTP requests will be rejected.
Gun does not currently support Websocket over HTTP/2.
By default Gun will take the Websocket options from
the connection's `ws_opts`.
Websocket subprotocol negotiation is enabled when
the `protocols` option is given. It takes a subprotocol
name and a module implementing the
link:man:gun_ws_protocol(3)[gun_ws_protocol(3)] behavior.
== Arguments
ConnPid::
The pid of the Gun connection process.
Path::
Path to the resource.
Headers::
Additional request headers.
WsOpts::
Configuration for the Websocket protocol.
== 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
* *1.0*: Function introduced.
== Examples
.Upgrade to Websocket
[source,erlang]
----
StreamRef = gun:ws_upgrade(ConnPid, "/ws", [
{<<"sec-websocket-protocol">>, <<"chat">>}
]).
receive
{gun_upgrade, ConnPid, StreamRef, [<<"websocket">>], _} ->
ok
after 5000 ->
error(timeout)
end.
----
.Upgrade to Websocket with different options
[source,erlang]
----
StreamRef = gun:ws_upgrade(ConnPid, "/ws", [], #{
compress => false
}).
----
.Upgrade to Websocket with protocol negotiation
[source,erlang]
----
StreamRef = gun:ws_upgrade(ConnPid, "/ws", [], #{
protocols => [
{<<"mqtt">>, gun_ws_mqtt_h},
{<<"v12.stomp">>, gun_ws_stomp_h}
]
}).
----
== See also
link:man:gun(3)[gun(3)],
link:man:gun:ws_send(3)[gun:ws_send(3)],
link:man:gun_upgrade(3)[gun_upgrade(3)],
link:man:gun_ws(3)[gun_ws(3)],
link:man:gun_ws_protocol(3)[gun_ws_protocol(3)]
|
