doc/sources/tutorial-hpack.rst

   1 Tutorial: HPACK API
   2 ===================
   3
   4 In this tutorial, we describe basic use of HPACK API in nghttp2
   5 library.  We briefly describe APIs for deflating and inflating header
   6 fields.  The example of using these APIs are presented as complete
   7 source code `deflate.c`_.
   8
   9 Deflating (encoding) headers
  10 ----------------------------
  11
  12 First we need to initialize :type:`nghttp2_hd_deflater` object using
  13 `nghttp2_hd_deflate_new()` function::
  14
  15     int nghttp2_hd_deflate_new(nghttp2_hd_deflater **deflater_ptr,
  16                                size_t deflate_hd_table_bufsize_max);
  17
  18 This function allocates :type:`nghttp2_hd_deflater` object and
  19 initializes it and assigns its pointer to ``*deflater_ptr`` passed by
  20 parameter.  The *deflate_hd_table_bufsize_max* is the upper bound of
  21 header table size the deflater will use.  This will limit the memory
  22 usage in deflater object for dynamic header table.  If you doubt, just
  23 specify 4096 here, which is the default upper bound of dynamic header
  24 table buffer size.
  25
  26 To encode header fields, `nghttp2_hd_deflate_hd()` function::
  27
  28     ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater,
  29                                   uint8_t *buf, size_t buflen,
  30                                   const nghttp2_nv *nva, size_t nvlen);
  31
  32 The *deflater* is the deflater object initialized by
  33 `nghttp2_hd_deflate_new()` function described above.  The *buf* is a
  34 pointer to buffer to store encoded byte string.  The *buflen* is
  35 capacity of *buf*.  The *nva* is a pointer to :type:`nghttp2_nv`,
  36 which is an array of header fields to deflate.  The *nvlen* is the
  37 number of header fields which *nva* contains.
  38
  39 It is important to initialize and assign all members of
  40 :type:`nghttp2_nv`.  If a header field should not be inserted in
  41 dynamic header table for a security reason, set
  42 :macro:`NGHTTP2_NV_FLAG_NO_INDEX` flag in :member:`nghttp2_nv.flags`.
  43
  44 `nghttp2_hd_deflate_hd()` processes all headers given in *nva*.  The
  45 *nva* must include all request or response header fields to be sent in
  46 one HEADERS (or optionally following (multiple) CONTINUATION
  47 frame(s)).  The *buf* must have enough space to store the encoded
  48 result.  Otherwise, the function will fail.  To estimate the upper
  49 bound of encoded result, use `nghttp2_hd_deflate_bound()` function::
  50
  51     size_t nghttp2_hd_deflate_bound(nghttp2_hd_deflater *deflater,
  52                                     const nghttp2_nv *nva, size_t nvlen);
  53
  54 Pass this function with the same paramters *deflater*, *nva* and
  55 *nvlen* which will be passed to `nghttp2_hd_deflate_hd()`.
  56
  57 The subsequent call of `nghttp2_hd_deflate_hd()` will use current
  58 encoder state and perform differential encoding which is the
  59 fundamental compression gain for HPACK.
  60
  61 Once `nghttp2_hd_deflate_hd()` fails, it cannot be undone and its
  62 further call with the same deflater object shall fail.  So it is very
  63 important to use `nghttp2_hd_deflate_bound()` to know the required
  64 size of buffer.
  65
  66 To delete :type:`nghttp2_hd_deflater` object, use `nghttp2_hd_deflate_del()`
  67 function.
  68
  69 Inflating (decoding) headers
  70 ----------------------------
  71
  72 We use :type:`nghttp2_hd_inflater` object to inflate compressed header
  73 data.  To initialize the object, use `nghttp2_hd_inflate_new()`::
  74
  75     int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr);
  76
  77 To inflate header data, use `nghttp2_hd_inflate_hd()` function::
  78
  79     ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater,
  80                                   nghttp2_nv *nv_out, int *inflate_flags,
  81                                   uint8_t *in, size_t inlen, int in_final);
  82
  83 The *inflater* is the inflater object initialized above.  The *nv_out*
  84 is a pointer to :type:`nghttp2_nv` to store the result.  The *in* is a
  85 pointer to input data and *inlen* is its length.  The caller is not
  86 required to specify whole deflated header data to *in* at once.  It
  87 can call this function multiple times for portion of the data in
  88 streaming way.  If *in_final* is nonzero, it tells the function that
  89 the passed data is the final sequence of deflated header data.  The
  90 *inflate_flags* is output parameter and successful call of this
  91 function stores a set of flags in it.  It will be described later.
  92
  93 This function returns when each header field is inflated.  When this
  94 happens, the function sets :macro:`NGHTTP2_HD_INFLATE_EMIT` flag to
  95 *inflate_flag* parameter and header field is stored in *nv_out*.  The
  96 return value indicates the number of data read from *in* to processed
  97 so far.  It may be less than *inlen*.  The caller should call the
  98 function repeatedly until all data are processed by adjusting *in* and
  99 *inlen* with the processed bytes.
 100
 101 If *in_final* is nonzero and all given data was processed, the
 102 function sets :macro:`NGHTTP2_HD_INFLATE_FINAL` flag to
 103 *inflate_flag*.  If the caller sees this flag set, call
 104 `nghttp2_hd_inflate_end_headers()` function.
 105
 106 If *in_final* is zero and :macro:`NGHTTP2_HD_INFLATE_EMIT` flag is not
 107 set, it indicates that all given data was processed.  The caller is
 108 required to pass subsequent data.
 109
 110 It is important to note that the function may produce one or more
 111 header fields even if *inlen* is 0 when *in_final* is nonzero, due to
 112 differential encoding.
 113
 114 The example use of `nghttp2_hd_inflate_hd()` is shown in
 115 `inflate_header_block()` function in `deflate.c`_.
 116
 117 To delete :type:`nghttp2_hd_inflater` object, use `nghttp2_hd_inflate_del()`
 118 function.