dwnx_conn_writev_stream

Synopsis

#include <dwnx/dwnx.h>

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 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 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 DWNX_ERR_WRITE_MORE.

If all given data is encoded as STREAM frame in dest, and if flags & 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 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 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 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 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 DWNX_ERR_WRITE_MORE, DWNX_ERR_STREAM_DATA_BLOCKED, and 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:

DWNX_ERR_NOMEM: Out of memory
DWNX_ERR_STREAM_NOT_FOUND: Stream does not exist
DWNX_ERR_STREAM_SHUT_WR: Stream is half closed (local); or stream is being reset.
DWNX_ERR_CALLBACK_FAILURE: User callback failed
DWNX_ERR_INVALID_ARGUMENT: The total length of stream data is too large.
DWNX_ERR_STREAM_DATA_BLOCKED: Stream is blocked because of flow control.
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.
DWNX_ERR_NOBUF: Buffer is too small.

If any other negative error is returned, close the connection.