diff options
Diffstat (limited to 'manual/cowboy_websocket_handler.md')
| -rw-r--r-- | manual/cowboy_websocket_handler.md | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/manual/cowboy_websocket_handler.md b/manual/cowboy_websocket_handler.md new file mode 100644 index 0000000..f0480b1 --- /dev/null +++ b/manual/cowboy_websocket_handler.md @@ -0,0 +1,131 @@ +cowboy_websocket_handler +======================== + +The `cowboy_websocket_handler` behaviour defines the interface used +by Websocket handlers. + +The `init/3` and `websocket_init/3` callbacks will always be called, +followed by zero or more calls to `websocket_handle/3` and +`websocket_info/3`. The `websocket_terminate/3` will always +be called last. + +Types +----- + +None. + +Callbacks +--------- + +### init({TransportName, ProtocolName}, Req, Opts) + -> {upgrade, protocol, cowboy_websocket} + | {upgrade, protocol, cowboy_websocket, Req, Opts} + +> Types: +> * TransportName = tcp | ssl | atom() +> * ProtocolName = http | atom() +> * Req = cowboy_req:req() +> * Opts = any() +> +> Upgrade the protocol to `cowboy_websocket`. + +### websocket_init(TransportName, Req, Opts) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {ok, Req, State, Timeout} + | {ok, Req, State, Timeout, hibernate} + | {shutdown, Req} + +> Types: +> * TransportName = tcp | ssl | atom() +> * Req = cowboy_req:req() +> * Opts = any() +> * State = any() +> * Timeout = timeout() +> +> Initialize the state for this session. +> +> This function is called before the upgrade to Websocket occurs. +> It can be used to negotiate Websocket protocol extensions +> with the client. It will typically be used to register this process +> to an event manager or a message queue in order to receive +> the messages the handler wants to process. +> +> The connection will stay up for a duration of up to `Timeout` +> milliseconds after it last received data from the socket, +> at which point it will stop and close the connection. +> By default this value is set to `infinity`. It is recommended +> to either set this value or ensure by any other mechanism +> that the handler will be closed after a certain period of +> inactivity. +> +> The `hibernate` option will hibernate the process until it +> starts receiving either data from the Websocket connection +> or Erlang messages. +> +> The `shutdown` return value can be used to close the connection +> before upgrading to Websocket. + +### websocket_handle(InFrame, Req, State) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {reply, OutFrame | [OutFrame], Req, State} + | {reply, OutFrame | [OutFrame], Req, State, hibernate} + | {shutdown, Req, State} + +> Types: +> * InFrame = {text | binary | ping | pong, binary()} +> * Req = cowboy_req:req() +> * State = any() +> * OutFrame = cowboy_websocket:frame() +> +> Handle the data received from the Websocket connection. +> +> This function will be called every time data is received +> from the Websocket connection. +> +> The `shutdown` return value can be used to close the +> connection. A close reply will also result in the connection +> being closed. +> +> 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) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {reply, OutFrame | [OutFrame], Req, State} + | {reply, OutFrame | [OutFrame], Req, State, hibernate} + | {shutdown, Req, State} + +> Types: +> * Info = any() +> * Req = cowboy_req:req() +> * State = any() +> * OutFrame = cowboy_websocket:frame() +> +> Handle the Erlang message received. +> +> This function will be called every time an Erlang message +> has been received. The message can be any Erlang term. +> +> The `shutdown` return value can be used to close the +> connection. A close reply will also result in the connection +> being closed. +> +> The `hibernate` option will hibernate the process until +> it receives another message or new data from the Websocket +> connection. + +### websocket_terminate(Reason, Req, State) -> ok + +> Types: +> * Reason = {normal, shutdown | timeout} | {remote, closed} | {remote, cowboy_websocket:close_code(), binary()} | {error, badencoding | badframe | closed | atom()} +> * Req = cowboy_req:req() +> * State = any() +> +> Perform any necessary cleanup of the state. +> +> The connection will be closed and the process stopped right +> after this call. |