diff options
Diffstat (limited to 'docs/en/gun/1.0/guide/websocket/index.html')
| -rw-r--r-- | docs/en/gun/1.0/guide/websocket/index.html | 62 |
1 files changed, 17 insertions, 45 deletions
diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index b34a290d..a77f1319 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -7,8 +7,6 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.37.1" /> - <title>Nine Nines: Websocket</title> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> @@ -66,8 +64,6 @@ <div class="paragraph"><p>This chapter describes how to use the Gun client for communicating with a Websocket server.</p></div> -<div class="paragraph"><p>@todo recovering from connection failure -reconnecting to Websocket etc.</p></div> <div class="sect1"> <h2 id="_http_upgrade">HTTP upgrade</h2> <div class="sectionbody"> @@ -76,7 +72,7 @@ you must first request for the connection to be upgraded. Only HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS.</p></div> -<div class="paragraph"><p>You must use the <code>gun_ws:upgrade/{2,3,4}</code> function to upgrade +<div class="paragraph"><p>You must use the <code>gun:ws_upgrade/2,3,4</code> function to upgrade to Websocket. This function can be called anytime after connection, so you can send HTTP requests before upgrading to Websocket.</p></div> <div class="listingblock"> @@ -96,14 +92,12 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>, [ - {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>} + {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>} ])<span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/{2,3}</code> +<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/2,3</code> call when opening the connection, or using the <code>gun:ws_upgrade/4</code>. -The fourth argument is those same options. This function call -will crash if the options are incorrect, unlike when passing -them through <code>gun:open/{2,3}</code>.</p></div> -<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_ws_upgrade</code> message is sent. +The fourth argument is those same options.</p></div> +<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_upgrade</code> message is sent. If the server does not understand Websocket or refused the upgrade, a <code>gun_response</code> message is sent. If Gun couldn’t perform the upgrade due to an error (for example attempting @@ -118,19 +112,16 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_ws_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>); - {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>}); - {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>}) - <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span> + {<span style="color: #FF6600">gun_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"websocket"</span><span style="color: #990000">>></span>], <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>); + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>}); + {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>}) + <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span> <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>Note that you shouldn’t use the <code>reply_to</code> request option -for connections you plan to upgrade, because only the -owner of the connection will receive messages about it.</p></div> </div> </div> <div class="sect1"> @@ -139,8 +130,7 @@ owner of the connection will receive messages about it.</p></div> <div class="paragraph"><p>Once the Websocket upgrade has completed successfully, you no longer have access to functions for performing requests. You can only send and receive Websocket messages.</p></div> -<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send one or more messages to the server.</p></div> -<div class="paragraph"><p>@todo Implement sending of N frames</p></div> +<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send messages to the server.</p></div> <div class="listingblock"> <div class="title">Send a text frame</div> <div class="content"><!-- Generator: GNU source-highlight @@ -148,20 +138,8 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>})<span style="color: #990000">.</span></tt></pre></div></div> -<div class="listingblock"> -<div class="title">Send a text frame, a binary frame and then close the connection</div> -<div class="content"><!-- Generator: GNU source-highlight -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><tt><span style="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, [ - {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>}, - {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">BinaryValue</span>}, - <span style="color: #FF6600">close</span> -])<span style="color: #990000">.</span></tt></pre></div></div> <div class="paragraph"><p>Note that if you send a close frame, Gun will close the connection -cleanly and will not attempt to reconnect afterwards, similar to -calling <code>gun:shutdown/1</code>.</p></div> +cleanly and will not attempt to reconnect afterwards.</p></div> </div> </div> <div class="sect1"> @@ -175,15 +153,9 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> - {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span> - <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</span>) + {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Frame</span>) <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> -<div class="paragraph"><p>@todo auto ping has not been implemented yet</p></div> -<div class="paragraph"><p>Gun will automatically send ping messages to the server to keep -the connection alive, however if the connection dies and Gun has -to reconnect it will not upgrade to Websocket automatically, you -need to perform the operation when you receive the <code>gun_error</code> -message.</p></div> </div> </div> |