aboutsummaryrefslogtreecommitdiffstats
path: root/manual/cowboy_websocket_handler.md
diff options
context:
space:
mode:
Diffstat (limited to 'manual/cowboy_websocket_handler.md')
-rw-r--r--manual/cowboy_websocket_handler.md131
1 files changed, 0 insertions, 131 deletions
diff --git a/manual/cowboy_websocket_handler.md b/manual/cowboy_websocket_handler.md
deleted file mode 100644
index f0480b1..0000000
--- a/manual/cowboy_websocket_handler.md
+++ /dev/null
@@ -1,131 +0,0 @@
-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.