From 108a491f5515fdc2a7fe3ce8c310a261d6be3230 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 6 Jul 2011 17:42:20 +0200 Subject: Add documentation for the public interface. This is probably not perfect yet but it should be better than nothing. We'll improve things with feedback received from the many users. --- src/cowboy_http_websocket_handler.erl | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'src/cowboy_http_websocket_handler.erl') diff --git a/src/cowboy_http_websocket_handler.erl b/src/cowboy_http_websocket_handler.erl index 30cb2e1..b02c28d 100644 --- a/src/cowboy_http_websocket_handler.erl +++ b/src/cowboy_http_websocket_handler.erl @@ -12,9 +12,35 @@ %% 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 three callbacks: websocket_init/3, +%% websocket_handle/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 multiple time, +%% one time for each message or packet 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 messages sent to the process and +%% also the data sent to the socket. In the later case the information is +%% given as a tuple {websocket, Data}. It can reply something, do +%% nothing or close the connection. You can choose to hibernate the process +%% by returning hibernate to save memory and CPU. +%% +%% websocket_terminate/3 is meant for cleaning up. It also receives +%% the request and the state previously defined, along with a reason for +%% termination. -module(cowboy_http_websocket_handler). + -export([behaviour_info/1]). +%% @private -spec behaviour_info(_) -> undefined | [{websocket_handle, 3} | {websocket_init, 3} | {websocket_terminate, 3}, ...]. behaviour_info(callbacks) -> -- cgit v1.2.3