umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-15 04:30:25 +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... %% Register process here...
{cowboy_websocket, Req, State}. {cowboy_websocket, Req, State}.
websocket_info(post_init, Req, State) -> websocket_info(post_init, State) ->
%% Perform post_init initialization here... %% Perform post_init initialization here...
{ok, Req, State}. {ok, State}.
---- ----
=== Handling frames from the client === 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 ping or pong frame arrives from the client. Note that in the
case of ping and pong frames, no action is expected as Cowboy case of ping and pong frames, no action is expected as Cowboy
automatically replies to ping frames. automatically replies to ping frames.
@ -89,15 +89,15 @@ ignores all others.
[source,erlang] [source,erlang]
---- ----
websocket_handle(Frame = {text, _}, Req, State) -> websocket_handle(Frame = {text, _}, State) ->
{reply, Frame, Req, State}; {reply, Frame, State};
websocket_handle(_Frame, Req, State) -> websocket_handle(_Frame, State) ->
{ok, Req, State}. {ok, State}.
---- ----
=== Handling Erlang messages === Handling Erlang messages
Cowboy will call `websocket_info/3` whenever an Erlang message Cowboy will call `websocket_info/2` whenever an Erlang message
arrives. arrives.
The handler can decide to send frames to the socket, stop The handler can decide to send frames to the socket, stop
@ -108,10 +108,10 @@ and ignores all others.
[source,erlang] [source,erlang]
---- ----
websocket_info({log, Text}, Req, State) -> websocket_info({log, Text}, State) ->
{reply, {text, Text}, Req, State}; {reply, {text, Text}, State};
websocket_info(_Info, Req, State) -> websocket_info(_Info, State) ->
{ok, Req, State}. {ok, State}.
---- ----
=== Sending frames to the socket === Sending frames to the socket
@ -126,13 +126,13 @@ tuple.
[source,erlang] [source,erlang]
---- ----
websocket_info(hello_world, Req, State) -> websocket_info(hello_world, State) ->
{reply, [ {reply, [
{text, "Hello"}, {text, "Hello"},
{text, <<"world!">>}, {text, <<"world!">>},
{binary, <<0:8000>>} {binary, <<0:8000>>}
], Req, State}; ], State};
%% More websocket_info/3 clauses here... %% More websocket_info/2 clauses here...
---- ----
Note that the payload for text and binary frames is of type 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 callbacks are common to all handler types and are documented
in the manual for the link:cowboy_handler.asciidoc[cowboy_handler] module. 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 specific to Websocket handlers and will be called as many times
as necessary until the Websocket connection is closed. as necessary until the Websocket connection is closed.
@ -84,18 +84,17 @@ timeout::
== Callbacks == Callbacks
=== websocket_handle(InFrame, Req, State) -> Ret === websocket_handle(InFrame, State) -> Ret
[source,erlang] [source,erlang]
---- ----
Ret = {ok, Req, State} Ret = {ok, State}
| {ok, Req, State, hibernate} | {ok, State, hibernate}
| {reply, OutFrame | [OutFrame], Req, State} | {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], Req, State, hibernate} | {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, Req, State} | {stop, State}
InFrame = {text | binary | ping | pong, binary()} InFrame = {text | binary | ping | pong, binary()}
Req = cowboy_req:req()
State = any() State = any()
OutFrame = cow_ws:frame() 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 it receives new data from the Websocket connection or an
Erlang message. Erlang message.
=== websocket_info(Info, Req, State) -> Ret === websocket_info(Info, State) -> Ret
[source,erlang] [source,erlang]
---- ----
Ret = {ok, Req, State} Ret = {ok, State}
| {ok, Req, State, hibernate} | {ok, State, hibernate}
| {reply, OutFrame | [OutFrame], Req, State} | {reply, OutFrame | [OutFrame], State}
| {reply, OutFrame | [OutFrame], Req, State, hibernate} | {reply, OutFrame | [OutFrame], State, hibernate}
| {stop, Req, State} | {stop, State}
Info = any() Info = any()
Req = cowboy_req:req()
State = any() State = any()
OutFrame = cow_ws:frame() OutFrame = cow_ws:frame()
---- ----