Starts listening for incoming connection requests.
typedef
_IRQL_requires_max_(PASSIVE_LEVEL)
QUIC_STATUS
(QUIC_API * QUIC_LISTENER_START_FN)(
_In_ _Pre_defensive_ HQUIC Listener,
_In_reads_(AlpnBufferCount) _Pre_defensive_
const QUIC_BUFFER* const AlpnBuffers,
_In_range_(>, 0) uint32_t AlpnBufferCount,
_In_opt_ const QUIC_ADDR* LocalAddress
);Listener
A valid handle to an open listener object.
AlpnBuffers
An array of QUIC_BUFFER structs that each contain a pointer and length to a different Application Layer Protocol Negotiation (ALPN) buffer, in order of preference, to be negotiated by the incoming connections.
AlpnBufferCount
The number of QUIC_BUFFER structs in AlpnBuffers.
LocalAddress
Optional pointer to a QUIC_ADDR to indicate the address and/or port to listen for connections on. May be NULL to let the networking stack choose.
The function returns a QUIC_STATUS. The app may use QUIC_FAILED or QUIC_SUCCEEDED to determine if the function failed or succeeded.
ListenerStart starts listening for incoming connections and callbacks on the listener may begin before the function call returns. Connection attempts that are received are indicated via QUIC_LISTENER_EVENT_NEW_CONNECTION event to the server application. The server application indicates acceptance of the connection attempt by calling SetCallbackHandler on the connection object, and returning QUIC_STATUS_SUCCESS from the QUIC_LISTENER_EVENT_NEW_CONNECTION callback. The server application must call ConnectionSetConfiguration on the connection, either before returning from the QUIC_LISTENER_EVENT_NEW_CONNECTION callback, or on its own after returning from the callback, otherwise the connection handshake will stall and timeout.
After returning QUIC_STATUS_SUCCESS from the QUIC_LISTENER_EVENT_NEW_CONNECTION callback, the server application owns the connection object and must eventually call ConnectionClose on it, otherwise a memory leak will occur.
The server application MUST NOT call ConnectionClose within the QUIC_LISTENER_EVENT_NEW_CONNECTION callback when returning failure, to reject a connection. This will result in a double-free in release builds, and an assert in debug builds. It's acceptable to call ConnectionClose within the QUIC_LISTENER_EVENT_NEW_CONNECTION callback if returning QUIC_STATUS_SUCCESS, or QUIC_STATUS_PENDING, since the server application owns the connection object then.
ALPNs specified in AlpnBuffers must be less than 255 bytes in length.
The server application may set any combination of local address and/or port number in the QUIC_ADDR pointed to by LocalAddress. If no port number is given, then the networking stack will choose an available port number, which can be queried by GetParam with QUIC_PARAM_LISTENER_LOCAL_ADDRESS.
MsQuic listens on dual-mode wildcard sockets for each unique port number, and performs address filtering, if necessary, within the QUIC layer. If another application is already listening on the same UDP port as an MsQuic application, despite being a different address family, the MsQuic application will fail to use that port, and ListenerStart will fail.