nghttp3_qpack_decoder_read_request
==================================

Synopsis
--------

*#include <nghttp3/nghttp3.h>*

.. function:: nghttp3_ssize nghttp3_qpack_decoder_read_request( nghttp3_qpack_decoder *decoder, nghttp3_qpack_stream_context *sctx, nghttp3_qpack_nv *nv, uint8_t *pflags, const uint8_t *src, size_t srclen, int fin)

    
    `nghttp3_qpack_decoder_read_request` reads request stream.  The
    request stream is given as the buffer pointed by *src* of length
    *srclen*.  *sctx* is the stream context, and it must be created by
    `nghttp3_qpack_stream_context_new`.  *\*pflags* must be non-NULL
    pointer.  *nv* must be non-NULL pointer.
    
    If this function succeeds, it assigns flags to *\*pflags*.  If
    *\*pflags* has :macro:`NGHTTP3_QPACK_DECODE_FLAG_EMIT` set, a
    decoded HTTP field is assigned to *nv*.  If *\*pflags* has
    :macro:`NGHTTP3_QPACK_DECODE_FLAG_FINAL` set, an entire HTTP field
    section has been successfully decoded.  If *\*pflags* has
    :macro:`NGHTTP3_QPACK_DECODE_FLAG_BLOCKED` set, decoding is blocked
    due to required insert count.
    
    When an HTTP field is decoded, an application receives it in *nv*.
    :member:`nv->name <nghttp3_qpack_nv.name>` and :member:`nv->value
    <nghttp3_qpack_nv.value>` are reference counted buffer, and their
    reference counts are already incremented for application use.
    Therefore, when application finishes processing *nv*, it must call
    `nghttp3_rcbuf_decref(nv->name) <nghttp3_rcbuf_decref>` and
    `nghttp3_rcbuf_decref(nv->value) <nghttp3_rcbuf_decref>`, or memory
    leak might occur.  These :type:`nghttp3_rcbuf` objects hold the
    pointer to :type:`nghttp3_mem` that is passed to
    `nghttp3_qpack_decoder_new` (or either `nghttp3_conn_client_new` or
    `nghttp3_conn_server_new` if it is used indirectly).  As long as
    these objects are alive, the pointed :type:`nghttp3_mem` object
    must be available.  Otherwise, `nghttp3_rcbuf_decref` will cause
    undefined behavior.
    
    This function returns the number of bytes read, or one of the
    following negative error codes:
    
    :macro:`NGHTTP3_ERR_NOMEM`
        Out of memory.
    :macro:`NGHTTP3_ERR_QPACK_FATAL`
        *decoder* is in unrecoverable error state, and cannot be used
        anymore.
    :macro:`NGHTTP3_ERR_QPACK_DECOMPRESSION_FAILED`
        Could not interpret field line representations.
    :macro:`NGHTTP3_ERR_QPACK_HEADER_TOO_LARGE`
        HTTP field is too large.