doc/nghttp2_select_next_protocol.rst

   1
   2 nghttp2_select_next_protocol
   3 ============================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_select_next_protocol(unsigned char **out, unsigned char *outlen, const unsigned char *in, unsigned int inlen)
  11
  12
  13     A helper function for dealing with NPN in client side or ALPN in
  14     server side.  The *in* contains peer's protocol list in preferable
  15     order.  The format of *in* is length-prefixed and not
  16     null-terminated.  For example, ``h2`` and
  17     ``http/1.1`` stored in *in* like this::
  18
  19         in[0] = 2
  20         in[1..2] = "h2"
  21         in[3] = 8
  22         in[4..11] = "http/1.1"
  23         inlen = 12
  24
  25     The selection algorithm is as follows:
  26
  27     1. If peer's list contains HTTP/2 protocol the library supports,
  28        it is selected and returns 1. The following step is not taken.
  29
  30     2. If peer's list contains ``http/1.1``, this function selects
  31        ``http/1.1`` and returns 0.  The following step is not taken.
  32
  33     3. This function selects nothing and returns -1 (So called
  34        non-overlap case).  In this case, *out* and *outlen* are left
  35        untouched.
  36
  37     Selecting ``h2`` means that ``h2`` is written into *\*out* and its
  38     length (which is 2) is assigned to *\*outlen*.
  39
  40     For ALPN, refer to https://tools.ietf.org/html/rfc7301
  41
  42     See http://technotes.googlecode.com/git/nextprotoneg.html for more
  43     details about NPN.
  44
  45     For NPN, to use this method you should do something like::
  46
  47         static int select_next_proto_cb(SSL* ssl,
  48                                         unsigned char **out,
  49                                         unsigned char *outlen,
  50                                         const unsigned char *in,
  51                                         unsigned int inlen,
  52                                         void *arg)
  53         {
  54             int rv;
  55             rv = nghttp2_select_next_protocol(out, outlen, in, inlen);
  56             if (rv == -1) {
  57                 return SSL_TLSEXT_ERR_NOACK;
  58             }
  59             if (rv == 1) {
  60                 ((MyType*)arg)->http2_selected = 1;
  61             }
  62             return SSL_TLSEXT_ERR_OK;
  63         }
  64         ...
  65         SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj);
  66