nghttp2_hpack_decoder_read
==========================

Synopsis
--------

*#include <nghttp2v2/nghttp2.h>*

.. function:: nghttp2_ssize nghttp2_hpack_decoder_read( nghttp2_hpack_decoder *dec, nghttp2_hpack_nv *dest, uint8_t *pflags, const uint8_t *src, size_t srclen, int fin)

    
    `nghttp2_hpack_decoder_read` reads the encoded HPACK stream given
    by the buffer pointed by *src* of length *srclen* bytes.  *\*pflags*
    must be non-NULL pointer.  *dest* must be non-NULL pointer.
    
    If this function succeeds, it assigns flags to *\*pflags*.  If
    *\*pflags* has :macro:`NGHTTP2_HPACK_DECODE_FLAG_EMIT` set, a
    decoded HTTP field is assigned to *dest*.  If *\*pflags* has
    :macro:`NGHTTP2_HPACK_DECODE_FLAG_FINAL` set, the entire HTTP field
    section has been successfully decoded.
    
    When an HTTP field is decoded, the caller receives it in *dest*.
    :member:`dest->name <nghttp2_hpack_nv.name>` and
    :member:`dest->value <nghttp2_hpack_nv.value>` are reference
    counted buffer, and their reference counts are already incremented
    for application use.  Therefore, when the caller finishes
    processing *dest*, it must call `nghttp2_rcbuf_decref(dest->name)
    <nghttp2_rcbuf_decref>` and `nghttp2_rcbuf_decref(dest->value)
    <nghttp2_rcbuf_decref>`, or memory leak might occur.  These
    :type:`nghttp2_rcbuf` objects hold the pointer to
    :type:`nghttp2_mem` that is passed to `nghttp2_hpack_decoder_new`.
    As long as these objects are alive, the pointed :type:`nghttp2_mem`
    object must be available.  Otherwise, `nghttp2_rcbuf_decref` causes
    undefined behavior.
    
    This function returns the number of bytes read, or one of the
    following negative error codes:
    
    :macro:`NGHTTP2_ERR_NOMEM`
        Out of memory.
    :macro:`NGHTTP2_ERR_HPACK_FATAL`
        *dec* is in unrecoverable error state, and cannot be used
        anymore.