aboutsummaryrefslogtreecommitdiffstats
path: root/guide
diff options
context:
space:
mode:
Diffstat (limited to 'guide')
-rw-r--r--guide/toc.md1
-rw-r--r--guide/ws_handlers.md25
2 files changed, 19 insertions, 7 deletions
diff --git a/guide/toc.md b/guide/toc.md
index 18c16e6..c406629 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -25,7 +25,6 @@ Cowboy User Guide
* Usage
* [Websocket handlers](ws_handlers.md)
* Purpose
- * Callbacks
* Usage
* [REST handlers](rest_handlers.md)
* Purpose
diff --git a/guide/ws_handlers.md b/guide/ws_handlers.md
index 226ada0..c1e551e 100644
--- a/guide/ws_handlers.md
+++ b/guide/ws_handlers.md
@@ -16,15 +16,28 @@ is implemented by most browsers today, although for backward
compatibility reasons a solution like [Bullet](https://github.com/extend/bullet)
might be preferred.
-Callbacks
----------
-
-@todo Describe the callbacks.
-
Usage
-----
-@todo Explain how to use them.
+Websocket handlers are a bridge between the client and your system.
+They can receive data from the client, through `websocket_handle/3`,
+or from the system, through `websocket_info/3`. It is up to the
+handler to decide to process this data, and optionally send a reply
+to the client.
+
+The first thing to do to be able to handle websockets is to tell
+Cowboy that it should upgrade the connection to use the Websocket
+protocol, as follow.
+
+``` erlang
+init({tcp, http}, Req, Opts) ->
+ {upgrade, protocol, cowboy_websocket}.
+```
+
+Cowboy will then switch the protocol and call `websocket_init`,
+followed by zero or more calls to `websocket_data` and
+`websocket_info`. Then, when the connection is shutting down,
+`websocket_terminate` will be called.
The following handler sends a message every second. It also echoes
back what it receives.