diff options
author | Loïc Hoguin <[email protected]> | 2016-01-14 13:35:25 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2016-01-14 13:37:20 +0100 |
commit | 4023e7f4e429179fd9c2cce4487c33646c6bd327 (patch) | |
tree | 3c4e26d1b5592958e35297c82ad3069bdb642594 /doc/src/guide/handlers.ezdoc | |
parent | b7d666cfc746f55b0a72ef8d37f703885099daf7 (diff) | |
download | cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.tar.gz cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.tar.bz2 cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.zip |
Convert the documentation to Asciidoc
A few small revisions were made, and Erlang.mk has been updated.
Diffstat (limited to 'doc/src/guide/handlers.ezdoc')
-rw-r--r-- | doc/src/guide/handlers.ezdoc | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/doc/src/guide/handlers.ezdoc b/doc/src/guide/handlers.ezdoc deleted file mode 100644 index 9336488..0000000 --- a/doc/src/guide/handlers.ezdoc +++ /dev/null @@ -1,99 +0,0 @@ -::: Handlers - -Handlers are Erlang modules that handle HTTP requests. - -:: Plain HTTP handlers - -The most basic handler in Cowboy implements the mandatory -`init/2` callback, manipulates the request, optionally -sends a response and then returns. - -This callback receives the ^"Req object^req and the options -defined during the ^"router configuration^routing^. - -A handler that does nothing would look like this: - -``` erlang -init(Req, _Opts) -> - {ok, Req, #state{}}. -``` - -Despite sending no reply, a `204 No Content` reply will be -sent to the client, as Cowboy makes sure that a reply is -sent for every request. - -We need to use the Req object for sending a reply. - -``` erlang -init(Req, _Opts) -> - Req2 = cowboy_req:reply(200, [ - {<<"content-type">>, <<"text/plain">>} - ], <<"Hello World!">>, Req), - {ok, Req2, #state{}}. -``` - -As you can see we return a 3-tuple. `ok` means that the -handler ran successfully. The Req object is returned as -it may have been modified as is the case here: replying -returns a modified Req object that you need to return -back to Cowboy for proper operations. - -The last value of the tuple is a state that will be used -in every subsequent callbacks to this handler. Plain HTTP -handlers only have one additional callback, the optional -`terminate/3`. - -:: Other handlers - -The `init/2` callback can also be used to inform Cowboy -that this is a different kind of handler and that Cowboy -should switch to it. To do this you simply need to return -the module name of the handler type you want to switch to. - -Cowboy comes with three handler types you can switch to: -^"cowboy_rest^rest_handlers^, ^"cowboy_websocket^ws_handlers^ -and ^"cowboy_loop^loop_handlers^. In addition to those you -can define your own handler types. - -Switching is simple. Instead of returning `ok`, you simply -return the name of the handler type you want to use. The -following snippet switches to a Websocket handler: - -``` erlang -init(Req, _Opts) -> - {cowboy_websocket, Req, #state{}}. -``` - -You can also switch to your own custom handler type: - -``` erlang -init(Req, _Opts) -> - {my_handler_type, Req, #state{}}. -``` - -How to implement a custom handler type is described in the -^"Sub protocols^sub_protocols chapter. - -:: Cleaning up - -All handlers coming with Cowboy allow the use of the optional -`terminate/3` callback. - -``` erlang -terminate(_Reason, Req, State) -> - ok. -``` - -This callback is strictly reserved for any required cleanup. -You cannot send a response from this function. There is no -other return value. - -If you used the process dictionary, timers, monitors or may -be receiving messages, then you can use this function to clean -them up, as Cowboy might reuse the process for the next -keep-alive request. - -Note that while this function may be called in a Websocket -handler, it is generally not useful to do any clean up as -the process terminates immediately after calling this callback -when using Websocket. |