QUIC_CONNECTION_EVENT structure

The payload for QUIC connection events.

Syntax

typedef struct QUIC_CONNECTION_EVENT {
    QUIC_CONNECTION_EVENT_TYPE Type;
    union {
        struct {
            BOOLEAN SessionResumed;
            _Field_range_(>, 0)
            uint8_t NegotiatedAlpnLength;
            _Field_size_(NegotiatedAlpnLength)
            const uint8_t* NegotiatedAlpn;
        } CONNECTED;
        struct {
            QUIC_STATUS Status;
            QUIC_UINT62 ErrorCode; // Wire format error code.
        } SHUTDOWN_INITIATED_BY_TRANSPORT;
        struct {
            QUIC_UINT62 ErrorCode;
        } SHUTDOWN_INITIATED_BY_PEER;
        struct {
            BOOLEAN HandshakeCompleted          : 1;
            BOOLEAN PeerAcknowledgedShutdown    : 1;
            BOOLEAN AppCloseInProgress          : 1;
        } SHUTDOWN_COMPLETE;
        struct {
            const QUIC_ADDR* Address;
        } LOCAL_ADDRESS_CHANGED;
        struct {
            const QUIC_ADDR* Address;
        } PEER_ADDRESS_CHANGED;
        struct {
            HQUIC Stream;
            QUIC_STREAM_OPEN_FLAGS Flags;
        } PEER_STREAM_STARTED;
        struct {
            uint16_t BidirectionalCount;
            uint16_t UnidirectionalCount;
        } STREAMS_AVAILABLE;
        struct {
            uint16_t IdealProcessor;
        } IDEAL_PROCESSOR_CHANGED;
        struct {
            BOOLEAN SendEnabled;
            uint16_t MaxSendLength;
        } DATAGRAM_STATE_CHANGED;
        struct {
            const QUIC_BUFFER* Buffer;
            QUIC_RECEIVE_FLAGS Flags;
        } DATAGRAM_RECEIVED;
        struct {
            /* inout */ void* ClientContext;
            QUIC_DATAGRAM_SEND_STATE State;
        } DATAGRAM_SEND_STATE_CHANGED;
        struct {
            uint16_t ResumptionStateLength;
            const uint8_t* ResumptionState;
        } RESUMED;
        struct {
            _Field_range_(>, 0)
            uint32_t ResumptionTicketLength;
            _Field_size_(ResumptionTicketLength)
            const uint8_t* ResumptionTicket;
        } RESUMPTION_TICKET_RECEIVED;
        struct {
            QUIC_CERTIFICATE* Certificate;
            uint32_t DeferredErrorFlags;
            QUIC_STATUS DeferredStatus;
            QUIC_CERTIFICATE_CHAIN* Chain;
        } PEER_CERTIFICATE_RECEIVED;
    };
} QUIC_CONNECTION_EVENT;

Parameters

Type

The QUIC_CONNECTION_EVENT_TYPE that indicates which type of event this is, and which payload to reference (if any) for additional information.

Remarks

QUIC_CONNECTION_EVENT_CONNECTED

This event is delivered when the handshake has completed. This means the peer has been securely authenticated. This happens after one full round trip on the client side. The server side considers the handshake complete once the client responds after this. Additional state can be found in the CONNECTED struct/union.

SessionResumed

A flag that indicates if a previous TLS session was successfully resumed.

NegotiatedAlpnLength

The length of the NegotiatedAlpn field.

NegotiatedAlpn

The buffer (not null terminated) that holds the ALPN that was negotiated during the handshake.

QUIC_CONNECTION_EVENT_SHUTDOWN_INITIATED_BY_TRANSPORT

This event is delivered whenever the transport (e.g. QUIC layer) determines the connection has been terminated. This can happen for a number of different reasons. Some are as follows.

The handshake fails (any number of reasons).
The connection is idle for long enough.
The connection disconnects (loses contact with peer; no acknowledgments).
The connection encounters a protocol violation.

Status

The platform status code that indicates the reason for the shutdown.

ErrorCode

The wire format error code that indicates the reason for the shutdown.

QUIC_CONNECTION_EVENT_SHUTDOWN_INITIATED_BY_PEER

This event is delivered when the peer application has terminated the application, with an application's protocol specific, 62-bit error code.

ErrorCode

The error code received from the peer for the shutdown.

QUIC_CONNECTION_EVENT_SHUTDOWN_COMPLETE

This event is the last one delivered to the application, and indicates the connection may now be safely closed.

HandshakeCompleted

A flag indicating if the QUIC handshake completed before the connection was shutdown.

PeerAcknowledgedShutdown

A flag indicating if the peer explicitly acknowledged the connection shutdown.

AppCloseInProgress

A flag indicating that the application called ConnectionClose on this connection.

QUIC_CONNECTION_EVENT_LOCAL_ADDRESS_CHANGED

This event is delivered when the local address used for the primary/active path communication has changed.

Address

The new local IP address.

QUIC_CONNECTION_EVENT_PEER_ADDRESS_CHANGED

This event is delivered when the remote address used for the primary/active path communication has changed.

Address

The new peer IP address.

QUIC_CONNECTION_EVENT_PEER_STREAM_STARTED

This event is delivered when the peer has created a new stream.

Stream

A handle to the newly peer-created stream.

Flags

A set of flags indicating describing the newly opened stream:

Value	Meaning
QUIC_STREAM_OPEN_FLAG_NONE 0	No special behavior. Defaults to bidirectional stream.
QUIC_STREAM_OPEN_FLAG_UNIDIRECTIONAL 1	A unidirectional stream.
QUIC_STREAM_OPEN_FLAG_0_RTT 2	The stream was received in 0-RTT.

If a server wishes to use QUIC_STREAM_OPEN_FLAG_DELAY_ID_FC_UPDATES for the newly started stream, it may append this flag to Flags before it returns from the callback.

QUIC_CONNECTION_EVENT_STREAMS_AVAILABLE

This event indicates the number of streams the peer is willing to accept has changed.

BidirectionalCount

The number of bidirectional streams the peer is willing to accept.

UnidirectionalCount

The number of unidirectional streams the peer is willing to accept.

QUIC_CONNECTION_EVENT_PEER_NEEDS_STREAMS

This event indicates the peer is currently blocked on the number of parallel streams the app has configured it is willing to accept.

QUIC_CONNECTION_EVENT_IDEAL_PROCESSOR_CHANGED

This event indicates the processor or CPU that MsQuic has determined would be the best for processing the given connection.

IdealProcessor

The processor number that should be ideally used for processing the connection.

QUIC_CONNECTION_EVENT_DATAGRAM_STATE_CHANGED

This event indicates the current state for sending unreliable datagrams has changed.

SendEnabled

A flag that indicates datagrams are allowed to be sent.

MaxSendLength

When enabled, indicates the maximum length of a single datagram that can fit in a packet.

QUIC_CONNECTION_EVENT_DATAGRAM_RECEIVED

This event indicates a received unreliable datagram from the peer.

Buffer

Contains a pointer to the received data along with the length of the data.

Flags

A set of flags indicating describing the received datagram data:

Value	Meaning
QUIC_RECEIVE_FLAG_NONE 0	No special behavior.
QUIC_RECEIVE_FLAG_0_RTT 1	The data was received in 0-RTT.
QUIC_RECEIVE_FLAG_FIN 2	N/A. Only used for Stream data. Unused for datagrams.

QUIC_CONNECTION_EVENT_DATAGRAM_SEND_STATE_CHANGED

This event indicates a state change for a previous unreliable datagram send via DatagramSend.

ClientContext

The context pointer passed into DatagramSend as ClientSendContext.

State

The latest state for the sent datagram.

Value	Meaning
QUIC_DATAGRAM_SEND_SENT 1	Indicates the datagram has now been sent out on the network. This is the earliest the app may free the `Buffers` passed into DatagramSend.
QUIC_DATAGRAM_SEND_LOST_SUSPECT 2	The sent datagram is suspected to be lost. If desired, the app could retransmit the data now.
QUIC_DATAGRAM_SEND_LOST_DISCARDED 3	The sent datagram is lost and no longer tracked by MsQuic.
QUIC_DATAGRAM_SEND_ACKNOWLEDGED 4	The sent datagram has been acknowledged.
QUIC_DATAGRAM_SEND_ACKNOWLEDGED_SPURIOUS 5	The sent datagram has been acknowledged after previously being suspected as lost.
QUIC_DATAGRAM_SEND_CANCELED 6	The queued datagram was canceled; either because the connection was shutdown or the peer did not negotiate the feature.

QUIC_CONNECTION_EVENT_RESUMED

This event indicates that a previous session has been successfully resumed at the TLS layer. This event is delivered for the server side only. The server app must indicate acceptance or rejection of the resumption ticket by returning a successful or failure status code from the event. If rejected by the server app, then resumption is rejected and a normal handshake will be performed.

ResumptionStateLength

The length of the ResumptionState buffer.

ResumptionState

The resumption ticket data previously sent to the client via ConnectionSendResumptionTicket.

QUIC_CONNECTION_EVENT_RESUMPTION_TICKET_RECEIVED

This event indicates a TLS resumption ticket has been received from the server.

ResumptionTicketLength

The length of the ResumptionTicket buffer.

ResumptionTicket

The resumption ticket data received from the server. For a client to later resume the session in a new connection, it must pass this data to the new connection via the QUIC_PARAM_CONN_RESUMPTION_TICKET parameter.

QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED

This event indicates a certificate has been received from the peer.

Certificate

Pointer to a platform/TLS specific certificate. Valid only during the callback.

If QUIC_CREDENTIAL_FLAG_USE_PORTABLE_CERTIFICATES was specified in the QUIC_CREDENTIAL_CONFIG, this will be a QUIC_BUFFER containing the DER (binary) encoded remote X.509 certificate.

DeferredErrorFlags

Bit flag of errors encountered when doing deferring validation of the certificate. Valid only with QUIC_CREDENTIAL_FLAG_DEFER_CERTIFICATE_VALIDATION flag specified upfront. Only supported with Schannel currently.

DeferredStatus

Most severe error status when doing deferred validation of the certificate. Valid only with QUIC_CREDENTIAL_FLAG_DEFER_CERTIFICATE_VALIDATION flag specified upfront.

Chain

Pointer to a platform/TLS specific certificate chain. Valid only during the callback.

If QUIC_CREDENTIAL_FLAG_USE_PORTABLE_CERTIFICATES was specified in the QUIC_CREDENTIAL_CONFIG, this will be a QUIC_BUFFER containing the PKCS #7 DER (binary) encoded certificate chain.

Table of Contents