umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-14 20:30:23 +00:00
Code Issues Wiki Activity

Update websocket documentation: based on https://github.com/ninenines/cowboy/blob/master/examples/websocket/src/ws_handler.erl

Browse source
This commit is contained in:
Alex Prut 2016-08-31 12:42:50 +02:00
parent bae10829ba
commit b58093a3c7
2 changed files with 28 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

30
doc/src/guide/ws_handlers.asciidoc
View file

@ -69,14 +69,14 @@ init(Req, State) ->
%% Register process here...
{cowboy_websocket, Req, State}.
websocket_info(post_init, Req, State) ->
websocket_info(post_init, State) ->
%% Perform post_init initialization here...
{ok, Req, State}.
{ok, State}.
----
=== Handling frames from the client
Cowboy will call `websocket_handle/3` whenever a text, binary,
Cowboy will call `websocket_handle/2` whenever a text, binary,
ping or pong frame arrives from the client. Note that in the
case of ping and pong frames, no action is expected as Cowboy
automatically replies to ping frames.
@ -89,15 +89,15 @@ ignores all others.
[source,erlang]
----
websocket_handle(Frame = {text, _}, Req, State) ->
{reply, Frame, Req, State};
websocket_handle(_Frame, Req, State) ->
{ok, Req, State}.
websocket_handle(Frame = {text, _}, State) ->
{reply, Frame, State};
websocket_handle(_Frame, State) ->
{ok, State}.
----
=== Handling Erlang messages
Cowboy will call `websocket_info/3` whenever an Erlang message
Cowboy will call `websocket_info/2` whenever an Erlang message
arrives.
The handler can decide to send frames to the socket, stop
@ -108,10 +108,10 @@ and ignores all others.
[source,erlang]
----
websocket_info({log, Text}, Req, State) ->
{reply, {text, Text}, Req, State};
websocket_info(_Info, Req, State) ->
{ok, Req, State}.
websocket_info({log, Text}, State) ->
{reply, {text, Text}, State};
websocket_info(_Info, State) ->
{ok, State}.
----
=== Sending frames to the socket
@ -126,13 +126,13 @@ tuple.
[source,erlang]
----
websocket_info(hello_world, Req, State) ->
websocket_info(hello_world, State) ->
{reply, [
{text, "Hello"},
{text, <<"world!">>},
{binary, <<0:8000>>}
], Req, State};
%% More websocket_info/3 clauses here...
], State};
%% More websocket_info/2 clauses here...
----
Note that the payload for text and binary frames is of type

28
doc/src/manual/cowboy_websocket.asciidoc
View file

@ -13,7 +13,7 @@ be implemented by handlers. The `init/2` and `terminate/3`
callbacks are common to all handler types and are documented
in the manual for the link:cowboy_handler.asciidoc[cowboy_handler] module.
The `websocket_handle/3` and `websocket_info/3` callbacks are
The `websocket_handle/2` and `websocket_info/2` callbacks are
specific to Websocket handlers and will be called as many times
as necessary until the Websocket connection is closed.
@ -84,18 +84,17 @@ timeout::
== Callbacks
=== websocket_handle(InFrame, Req, State) -> Ret
=== websocket_handle(InFrame, State) -> Ret
[source,erlang]
----
Ret = {ok, Req, State}
| {ok, Req, State, hibernate}
| {reply, OutFrame | [OutFrame], Req, State}
| {reply, OutFrame | [OutFrame], Req, State, hibernate}
| {stop, Req, State}
Ret = {ok, State}
| {ok, State, hibernate}
| {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, State}
InFrame = {text | binary | ping | pong, binary()}
Req = cowboy_req:req()
State = any()
OutFrame = cow_ws:frame()
----
@ -113,18 +112,17 @@ The `hibernate` option will hibernate the process until
it receives new data from the Websocket connection or an
Erlang message.
=== websocket_info(Info, Req, State) -> Ret
=== websocket_info(Info, State) -> Ret
[source,erlang]
----
Ret = {ok, Req, State}
| {ok, Req, State, hibernate}
| {reply, OutFrame | [OutFrame], Req, State}
| {reply, OutFrame | [OutFrame], Req, State, hibernate}
| {stop, Req, State}
Ret = {ok, State}
| {ok, State, hibernate}
| {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, State}
Info = any()
Req = cowboy_req:req()
State = any()
OutFrame = cow_ws:frame()
----