aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_websocket_handler.ezdoc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-07-06 13:10:35 +0200
committerLoïc Hoguin <[email protected]>2014-07-06 13:10:35 +0200
commit078d686a0ac0aed212db97d73bd1e4a9387a4956 (patch)
tree6bbc6111fdbdfedd3bb351bf3b01c63fac0d7143 /doc/src/manual/cowboy_websocket_handler.ezdoc
parent1a71a733c37df70c15ebfd28157b10915cd738d1 (diff)
downloadcowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.tar.gz
cowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.tar.bz2
cowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.zip
Provide installable man pages
make docs: generate Markdown and man pages in doc/ make install-docs: install man pages to be usable directly Docs are generated from the ezdoc files in doc/src/.
Diffstat (limited to 'doc/src/manual/cowboy_websocket_handler.ezdoc')
-rw-r--r--doc/src/manual/cowboy_websocket_handler.ezdoc133
1 files changed, 133 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy_websocket_handler.ezdoc b/doc/src/manual/cowboy_websocket_handler.ezdoc
new file mode 100644
index 0000000..0d31a54
--- /dev/null
+++ b/doc/src/manual/cowboy_websocket_handler.ezdoc
@@ -0,0 +1,133 @@
+::: 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.