From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 14 Jan 2016 13:35:25 +0100 Subject: Convert the documentation to Asciidoc A few small revisions were made, and Erlang.mk has been updated. --- doc/src/manual/cowboy_websocket.asciidoc | 143 +++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 doc/src/manual/cowboy_websocket.asciidoc (limited to 'doc/src/manual/cowboy_websocket.asciidoc') diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc new file mode 100644 index 0000000..ac9016b --- /dev/null +++ b/doc/src/manual/cowboy_websocket.asciidoc @@ -0,0 +1,143 @@ += cowboy_websocket(3) + +== Name + +cowboy_websocket - Websocket protocol + +== Description + +The `cowboy_websocket` module implements the Websocket protocol. + +This module is a sub protocol that defines four callbacks to +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 +specific to Websocket handlers and will be called as many times +as necessary until the Websocket connection is closed. + +The `init/2` callback can be used to negotiate Websocket protocol +extensions with the client. It is highly recommended to return a +timeout value from this callback to ensure that the process is +terminated when no data has been received during that timespan. +The default timeout is `infinity`, which should only be used if +you have alternate means of ending inactive connections. + +Cowboy will terminate the process right after closing the +Websocket connection. This means that there is no real need to +perform any cleanup in the optional `terminate/3` callback. + +== Meta values + +websocket_compress = boolean():: + Whether a websocket compression extension in in use. + +websocket_version = 7 | 8 | 13:: + The version of the Websocket protocol being used. + +== Terminate reasons + +The following values may be received as the terminate reason +in the optional `terminate/3` callback. + +normal:: + The connection was closed normally before establishing a Websocket + connection. This typically happens if an `ok` tuple is returned + from the `init/2` callback. + +remote:: + The remote endpoint closed the connection without giving any + further details. + +{remote, Code, Payload}:: + The remote endpoint closed the connection with the given + `Code` and `Payload` as the reason. + +stop:: + The handler requested to close the connection, either by returning + a `stop` tuple or by sending a `close` frame. + +timeout:: + The connection has been closed due to inactivity. The timeout + value can be configured from `init/2`. + +{crash, Class, Reason}:: + A crash occurred in the handler. `Class` and `Reason` can be + used to obtain more information about the crash. The function + `erlang:get_stacktrace/0` can also be called to obtain the + stacktrace of the process when the crash occurred. + +{error, badencoding}:: + A text frame was sent by the client with invalid encoding. All + text frames must be valid UTF-8. + +{error, badframe}:: + A protocol error has been detected. + +{error, closed}:: + The socket has been closed brutally without a close frame being + received first. + +{error, Reason}:: + A socket error ocurred. + +== Callbacks + +=== websocket_handle(InFrame, Req, 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} + +InFrame = {text | binary | ping | pong, binary()} +Req = cowboy_req:req() +State = any() +OutFrame = cow_ws:frame() +---- + +Handle the data received from the Websocket connection. + +This function will be called every time data is received +from the Websocket connection. + +The `stop` 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) -> 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} + +Info = any() +Req = cowboy_req:req() +State = any() +OutFrame = cow_ws: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 `stop` 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. -- cgit v1.2.3