dwnx_conn_writev_stream
=======================

Synopsis
--------

*#include <dwnx/dwnx.h>*

.. function:: dwnx_ssize dwnx_conn_writev_stream(dwnx_conn *conn, uint8_t *dest, size_t destlen, dwnx_ssize *pdatalen, uint32_t flags, int64_t stream_id, const dwnx_vec *datav, size_t datavcnt, dwnx_tstamp ts)

    
    `dwnx_conn_writev_stream` writes a single QMux record.  The caller
    can optionally pass the stream data.  The buffer of the record is
    pointed by *dest* of length *destlen*.  It returns the number of
    bytes written to the buffer pointed by *dest* if it succeeds.
    
    *destlen* should be at least :macro:`DWNX_DEFAULT_MAX_RECORD_SIZE`.
    The caller may provide a smaller sized buffer if the full sized TLS
    record cannot be sent because the congestion window is not wide
    open.
    
    Specifying -1 to *stream_id* means no new stream data to send.
    
    If *stream_id* is not -1, the stream data is specified as vector of
    data *datav*.  *datavcnt* specifies the number of :type:`dwnx_vec`
    that *datav* includes.  The number of data encoded in STREAM frame
    is stored in *\*pdatalen* if it is not NULL and this function
    succeeds, or it returns :macro:`DWNX_ERR_WRITE_MORE`.
    
    If all given data is encoded as STREAM frame in *dest*, and if
    *flags* & :macro:`DWNX_WRITE_STREAM_FLAG_FIN` is nonzero, fin flag
    is set to outgoing STREAM frame.  Otherwise, fin flag in STREAM
    frame is not set.
    
    This record may contain frames other than STREAM frame.  The record
    might not contain STREAM frame if other frames occupy the frame.
    In that case, *\*pdatalen* would be -1 if *pdatalen* is not NULL.
    
    Empty data is treated specially, and it is only accepted if no
    data, including the empty data, is submitted to a stream or
    :macro:`DWNX_WRITE_STREAM_FLAG_FIN` is set in *flags*.  If 0 length
    STREAM frame is successfully serialized, *\*pdatalen* would be 0.
    
    This function may return :macro:`DWNX_ERR_WRITE_MORE` error code.
    It indicates that there are more spaces in the record, the caller
    should call this function again to send another stream data.  If no
    stream data is available, specify *stream_id* to -1.
    
    This function may return :macro:`DWNX_ERR_STREAM_DATA_BLOCKED`
    error code.  It indicates that the flow control prevents from the
    data to be sent.  In this case, *\*pdatalen* is -1.
    
    This function may return :macro:`DWNX_ERR_STREAM_SHUT_WR` error
    code.  It indicates that the write side of the stream has been
    closed.  In this case, *\*pdatalen* is -1.
    
    If the other negative error codes are returned, QMux connection
    must be closed.
    
    The rule of this function call is keep calling this function until
    it returns 0 or a positive integer, or the negative error code
    other than :macro:`DWNX_ERR_WRITE_MORE`,
    :macro:`DWNX_ERR_STREAM_DATA_BLOCKED`, and
    :macro:`DWNX_ERR_STREAM_SHUT_WR`.  If the function returns 0, it
    means that there is nothing to send.
    
    This function must not be called from inside the callback
    functions.
    
    This function returns the number of bytes written in *dest* if it
    succeeds, or one of the following negative error codes:
    
    :macro:`DWNX_ERR_NOMEM`
        Out of memory
    :macro:`DWNX_ERR_STREAM_NOT_FOUND`
        Stream does not exist
    :macro:`DWNX_ERR_STREAM_SHUT_WR`
        Stream is half closed (local); or stream is being reset.
    :macro:`DWNX_ERR_CALLBACK_FAILURE`
        User callback failed
    :macro:`DWNX_ERR_INVALID_ARGUMENT`
        The total length of stream data is too large.
    :macro:`DWNX_ERR_STREAM_DATA_BLOCKED`
        Stream is blocked because of flow control.
    :macro:`DWNX_ERR_WRITE_MORE`
        Application can call this function to pack more stream data
        into the same record.  See above to know how it works.
    :macro:`DWNX_ERR_NOBUF`
        Buffer is too small.
    
    If any other negative error is returned, close the connection.