From cc2e084d456c99b3d71f09c08f516195b6015dae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 27 Aug 2012 12:46:42 +0200 Subject: Update behaviours for R15B+ This effectively drops the R14B compatibility. The cowboy_req:req() type will be introduced in a future commit. It refers to the #http_req{} record. --- src/cowboy_websocket_handler.erl | 81 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 src/cowboy_websocket_handler.erl (limited to 'src/cowboy_websocket_handler.erl') diff --git a/src/cowboy_websocket_handler.erl b/src/cowboy_websocket_handler.erl new file mode 100644 index 0000000..34749ba --- /dev/null +++ b/src/cowboy_websocket_handler.erl @@ -0,0 +1,81 @@ +%% Copyright (c) 2011-2012, Loïc Hoguin +%% +%% Permission to use, copy, modify, and/or distribute this software for any +%% purpose with or without fee is hereby granted, provided that the above +%% copyright notice and this permission notice appear in all copies. +%% +%% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +%% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +%% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +%% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +%% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +%% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +%% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +%% @doc Handler for HTTP WebSocket requests. +%% +%% WebSocket handlers must implement five callbacks: init/3, +%% websocket_init/3, websocket_handle/3, +%% websocket_info/3 and websocket_terminate/3. +%% These callbacks will only be called if the connection is upgraded +%% to WebSocket in the HTTP handler's init/3 callback. +%% They are then called in that order, although websocket_handle/3 +%% will be called for each packet received, and websocket_info +%% for each message received. +%% +%% websocket_init/3 is meant for initialization. It receives +%% information about the transport and protocol used, along with the handler +%% options from the dispatch list. You can define a request-wide state here. +%% If you are going to want to compact the request, you should probably do it +%% here. +%% +%% websocket_handle/3 receives the data from the socket. It can reply +%% something, do nothing or close the connection. +%% +%% websocket_info/3 receives messages sent to the process. It has +%% the same reply format as websocket_handle/3 described above. Note +%% that unlike in a gen_server, when websocket_info/3 +%% replies something, it is always to the socket, not to the process that +%% originated the message. +%% +%% websocket_terminate/3 is meant for cleaning up. It also receives +%% the request and the state previously defined, along with a reason for +%% termination. +%% +%% All of websocket_init/3, websocket_handle/3 and +%% websocket_info/3 can decide to hibernate the process by adding +%% an extra element to the returned tuple, containing the atom +%% hibernate. Doing so helps save memory and improve CPU usage. +-module(cowboy_websocket_handler). + +-type opts() :: any(). +-type state() :: any(). +-type terminate_reason() :: {normal, closed} + | {normal, timeout} + | {error, closed} + | {error, badframe} + | {error, atom()}. + +-callback websocket_init(atom(), Req, opts()) + -> {ok, Req, state()} + | {ok, Req, state(), hibernate} + | {ok, Req, state(), timeout()} + | {ok, Req, state(), timeout(), hibernate} + | {shutdown, Req} + when Req::cowboy_req:req(). +-callback websocket_handle({text | binary | ping | pong, binary()}, Req, State) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {reply, {text | binary | ping | pong, binary()}, Req, State} + | {reply, {text | binary | ping | pong, binary()}, Req, State, hibernate} + | {shutdown, Req, State} + when Req::cowboy_req:req(), State::state(). +-callback websocket_info(any(), Req, State) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {reply, {text | binary | ping | pong, binary()}, Req, State} + | {reply, {text | binary | ping | pong, binary()}, Req, State, hibernate} + | {shutdown, Req, State} + when Req::cowboy_req:req(), State::state(). +-callback websocket_terminate(terminate_reason(), cowboy_req:req(), state()) + -> ok. -- cgit v1.2.3