From fe3492a98de29942477b061cd02c92246f4bf85a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 28 Mar 2016 15:36:42 +0200 Subject: Initial commit, new website system --- docs/en/cowboy/2.0/guide/sub_protocols/index.html | 206 ++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/en/cowboy/2.0/guide/sub_protocols/index.html (limited to 'docs/en/cowboy/2.0/guide/sub_protocols') diff --git a/docs/en/cowboy/2.0/guide/sub_protocols/index.html b/docs/en/cowboy/2.0/guide/sub_protocols/index.html new file mode 100644 index 00000000..c75da6a4 --- /dev/null +++ b/docs/en/cowboy/2.0/guide/sub_protocols/index.html @@ -0,0 +1,206 @@ + + + + + + + + + + + + Nine Nines: Sub protocols + + + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Sub protocols

+ +

Sub protocols are used for creating new types of handlers that +provide extra functionality in a reusable way. Cowboy uses this +mechanism to provide its loop, REST and Websocket handlers.

+

This chapter will explain how to create your own sub protocols +and handler types.

+
+

Usage

+
+

To switch to a sub protocol, the init/2 callback must return +the name of the sub protocol module. Everything past this point +is handled by the sub protocol.

+
+
+
init(Req, _Opts) ->
+        {cowboy_websocket, Req, #state{}}.
+

The return value may also have a Timeout value and/or the +atom hibernate. These options are useful for long living +connections. When they are not provided, the timeout value +defaults to infinity and the hibernate value to run.

+

The following snippet switches to the my_protocol sub +protocol, sets the timeout value to 5 seconds and enables +hibernation:

+
+
+
init(Req, _Opts) ->
+        {my_protocol, Req, #state{}, 5000, hibernate}.
+

If a sub protocol does not make use of these options, it should +crash if it receives anything other than the default values.

+
+
+
+

Upgrade

+
+

After the init/2 function returns, Cowboy will then call the +upgrade/6 function. This is the only callback defined by the +cowboy_sub_protocol behavior.

+

The function is named upgrade because it mimics the mechanism +of HTTP protocol upgrades. For some sub protocols, like Websocket, +an actual upgrade is performed. For others, like REST, this is +only an upgrade at Cowboy’s level and the client has nothing to +do about it.

+

The upgrade callback receives the Req object, the middleware +environment, the handler and its options, and the aforementioned +timeout and hibernate values.

+
+
+
upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
+        %% Sub protocol code here.
+

This callback is expected to behave like a middleware and to +return an updated environment and Req object.

+

Sub protocols are expected to call the cowboy_handler:terminate/4 +function when they terminate. This function will make sure that +the optional terminate/3 callback is called, if present.

+
+
+ + + +
+ +
+ + +

+ Cowboy + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +
+
+
+
+ + + + + + + + + + + + -- cgit v1.2.3