doc/nghttp2_hd_inflate_hd.rst

   1
   2 nghttp2_hd_inflate_hd
   3 =====================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: ssize_t nghttp2_hd_inflate_hd(nghttp2_hd_inflater *inflater, nghttp2_nv *nv_out, int *inflate_flags, uint8_t *in, size_t inlen, int in_final)
  11
  12
  13     Inflates name/value block stored in *in* with length *inlen*.  This
  14     function performs decompression.  For each successful emission of
  15     header name/value pair, :macro:`NGHTTP2_HD_INFLATE_EMIT` is set in
  16     *\*inflate_flags* and name/value pair is assigned to the *nv_out*
  17     and the function returns.  The caller must not free the members of
  18     *nv_out*.
  19
  20     The *nv_out* may include pointers to the memory region in the *in*.
  21     The caller must retain the *in* while the *nv_out* is used.
  22
  23     The application should call this function repeatedly until the
  24     ``(*inflate_flags) & NGHTTP2_HD_INFLATE_FINAL`` is nonzero and
  25     return value is non-negative.  This means the all input values are
  26     processed successfully.  Then the application must call
  27     `nghttp2_hd_inflate_end_headers()` to prepare for the next header
  28     block input.
  29
  30     The caller can feed complete compressed header block.  It also can
  31     feed it in several chunks.  The caller must set *in_final* to
  32     nonzero if the given input is the last block of the compressed
  33     header.
  34
  35     This function returns the number of bytes processed if it succeeds,
  36     or one of the following negative error codes:
  37
  38     :macro:`NGHTTP2_ERR_NOMEM`
  39         Out of memory.
  40     :macro:`NGHTTP2_ERR_HEADER_COMP`
  41         Inflation process has failed.
  42     :macro:`NGHTTP2_ERR_BUFFER_ERROR`
  43         The heder field name or value is too large.
  44
  45     Example follows::
  46
  47         int inflate_header_block(nghttp2_hd_inflater *hd_inflater,
  48                                  uint8_t *in, size_t inlen, int final)
  49         {
  50             ssize_t rv;
  51
  52             for(;;) {
  53                 nghttp2_nv nv;
  54                 int inflate_flags = 0;
  55
  56                 rv = nghttp2_hd_inflate_hd(hd_inflater, &nv, &inflate_flags,
  57                                            in, inlen, final);
  58
  59                 if(rv < 0) {
  60                     fprintf(stderr, "inflate failed with error code %zd", rv);
  61                     return -1;
  62                 }
  63
  64                 in += rv;
  65                 inlen -= rv;
  66
  67                 if(inflate_flags & NGHTTP2_HD_INFLATE_EMIT) {
  68                     fwrite(nv.name, nv.namelen, 1, stderr);
  69                     fprintf(stderr, ": ");
  70                     fwrite(nv.value, nv.valuelen, 1, stderr);
  71                     fprintf(stderr, "\n");
  72                 }
  73                 if(inflate_flags & NGHTTP2_HD_INFLATE_FINAL) {
  74                     nghttp2_hd_inflate_end_headers(hd_inflater);
  75                     break;
  76                 }
  77                 if((inflate_flags & NGHTTP2_HD_INFLATE_EMIT) == 0 &&
  78                    inlen == 0) {
  79                    break;
  80                 }
  81             }
  82
  83             return 0;
  84         }
  85