ngtcp2_conn_write_connection_close
==================================

Synopsis
--------

*#include <ngtcp2/ngtcp2.h>*

.. function:: ngtcp2_ssize ngtcp2_conn_write_connection_close( ngtcp2_conn *conn, ngtcp2_path *path, ngtcp2_pkt_info *pi, uint8_t *dest, size_t destlen, const ngtcp2_ccerr *ccerr, ngtcp2_tstamp ts)

    
    `ngtcp2_conn_write_connection_close` writes a packet which contains
    CONNECTION_CLOSE frame(s) (type 0x1c or 0x1d) in the buffer pointed
    by *dest* whose capacity is *destlen*.
    
    For client, *destlen* should be at least
    :macro:`NGTCP2_MAX_UDP_PAYLOAD_SIZE`.
    
    If *path* is not ``NULL``, this function stores the network path
    with which the packet should be sent.  Each addr field must point
    to the buffer which should be at least
    sizeof(:type:`ngtcp2_sockaddr_union`) bytes long.  The assignment
    might not be done if nothing is written to *dest*.
    
    If *pi* is not ``NULL``, this function stores packet metadata in it
    if it succeeds.  The metadata includes ECN markings.
    
    If :member:`ccerr->type <ngtcp2_ccerr.type>` ==
    :enum:`ngtcp2_ccerr_type.NGTCP2_CCERR_TYPE_TRANSPORT`, this
    function sends CONNECTION_CLOSE (type 0x1c) frame.  If
    :member:`ccerr->type <ngtcp2_ccerr.type>` ==
    :enum:`ngtcp2_ccerr_type.NGTCP2_CCERR_TYPE_APPLICATION`, it sends
    CONNECTION_CLOSE (type 0x1d) frame.  Otherwise, it does not produce
    any data, and returns 0.
    
    *destlen* could be shorten by some factors (e.g., server side
    amplification limit).  This function returns
    :macro:`NGTCP2_ERR_NOBUF` if the resulting buffer is too small even
    if the given buffer has enough space.
    
    This function must not be called from inside the callback
    functions.
    
    At the moment, successful call to this function makes connection
    close.  We may change this behaviour in the future to allow
    graceful shutdown.
    
    This function returns the number of bytes written in *dest* if it
    succeeds, or one of the following negative error codes:
    
    :macro:`NGTCP2_ERR_NOMEM`
        Out of memory
    :macro:`NGTCP2_ERR_NOBUF`
        Buffer is too small
    :macro:`NGTCP2_ERR_INVALID_STATE`
        The current state does not allow sending CONNECTION_CLOSE
        frame.
    :macro:`NGTCP2_ERR_PKT_NUM_EXHAUSTED`
        Packet number is exhausted, and cannot send any more packet.
    :macro:`NGTCP2_ERR_CALLBACK_FAILURE`
        User callback failed