Improve Documentation for Listener Callbacks

[nibanks]

Discussed in #4698

^{Originally posted by Streamlet December 10, 2024}
The documents for quic functions is very detail, but there is few for callbacks.
Would you add more documents for each parameters of each kind of callbacks?

[Streamlet]

Not only listener callbacks, but also Connection callnacks and Stream callacks

[Streamlet]

QUIC_LISTENER_EVENT_NEW_CONNECTION      = 0,
QUIC_LISTENER_EVENT_STOP_COMPLETE       = 1,





QUIC_CONNECTION_EVENT_CONNECTED                         = 0,
QUIC_CONNECTION_EVENT_SHUTDOWN_INITIATED_BY_TRANSPORT   = 1,
QUIC_CONNECTION_EVENT_SHUTDOWN_INITIATED_BY_PEER        = 2,
QUIC_CONNECTION_EVENT_SHUTDOWN_COMPLETE                 = 3,
QUIC_CONNECTION_EVENT_LOCAL_ADDRESS_CHANGED             = 4,
QUIC_CONNECTION_EVENT_PEER_ADDRESS_CHANGED              = 5,
QUIC_CONNECTION_EVENT_PEER_STREAM_STARTED               = 6,
QUIC_CONNECTION_EVENT_STREAMS_AVAILABLE                 = 7,
QUIC_CONNECTION_EVENT_PEER_NEEDS_STREAMS                = 8,
QUIC_CONNECTION_EVENT_IDEAL_PROCESSOR_CHANGED           = 9,
QUIC_CONNECTION_EVENT_DATAGRAM_STATE_CHANGED            = 10,
QUIC_CONNECTION_EVENT_DATAGRAM_RECEIVED                 = 11,
QUIC_CONNECTION_EVENT_DATAGRAM_SEND_STATE_CHANGED       = 12,
QUIC_CONNECTION_EVENT_RESUMED                           = 13,
QUIC_CONNECTION_EVENT_RESUMPTION_TICKET_RECEIVED        = 14,
QUIC_CONNECTION_EVENT_PEER_CERTIFICATE_RECEIVED         = 15,
QUIC_CONNECTION_EVENT_RELIABLE_RESET_NEGOTIATED         = 16,
QUIC_CONNECTION_EVENT_ONE_WAY_DELAY_NEGOTIATED          = 17,
QUIC_CONNECTION_EVENT_NETWORK_STATISTICS                = 18,





QUIC_STREAM_EVENT_START_COMPLETE            = 0,
QUIC_STREAM_EVENT_RECEIVE                   = 1,
QUIC_STREAM_EVENT_SEND_COMPLETE             = 2,
QUIC_STREAM_EVENT_PEER_SEND_SHUTDOWN        = 3,
QUIC_STREAM_EVENT_PEER_SEND_ABORTED         = 4,
QUIC_STREAM_EVENT_PEER_RECEIVE_ABORTED      = 5,
QUIC_STREAM_EVENT_SEND_SHUTDOWN_COMPLETE    = 6,
QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE         = 7,
QUIC_STREAM_EVENT_IDEAL_SEND_BUFFER_SIZE    = 8,
QUIC_STREAM_EVENT_PEER_ACCEPTED             = 9,
QUIC_STREAM_EVENT_CANCEL_ON_LOSS            = 10,

[Streamlet]

and members of these structures:

QUIC_LISTENER_EVENT
QUIC_CONNECTION_EVENT
QUIC_STREAM_EVENT

[Streamlet]

and return values for each callback.

for QUIC_STREAM_EVENT_RECEIVE, QUIC_STATUS_CONTINUE can be returned, as Using Streams says.

simply return QUIC_STATUS_SUCCESS for all other cases? is there any special cases like QUIC_STREAM_EVENT_RECEIVE?

[Streamlet]

For a Quic server, which event comes first? QUIC_LISTENER_EVENT_NEW_CONNECTION or QUIC_CONNECTION_EVENT_CONNECTED?

[Streamlet]

For a Quic server, which event comes first? QUIC_LISTENER_EVENT_NEW_CONNECTION or QUIC_CONNECTION_EVENT_CONNECTED?

Will they be triggered both ?

[anrossi]

For a Quic server, which event comes first? QUIC_LISTENER_EVENT_NEW_CONNECTION or QUIC_CONNECTION_EVENT_CONNECTED?

The MsQuicListener will receive the QUIC_LISTENER_EVENT_NEW_CONNECTION first, and the application must set the connection callback and callback context if it accepts the connection; if it rejects the connection, it returns error.
If the connection is accepted, and the handshake completes successfully, then QUIC_CONNECTION_EVENT_CONNECTED will happen on the connection callback.

[Streamlet]

The MsQuicListener will receive the QUIC_LISTENER_EVENT_NEW_CONNECTION first, and the application must set the connection callback and callback context if it accepts the connection; If the connection is accepted, and the handshake completes successfully, then QUIC_CONNECTION_EVENT_CONNECTED will happen on the connection callback.

OK, I understand this part.

if it rejects the connection, it returns error.

Is it means application should returns QUIC_STATUS_(!SUCCESS) in the listen callback function?
then the Connection handler should be shutdown-close by application or quic library?

code sample:

QUIC_STATUS QuicPeer::ListenerCallback(HQUIC hListener, QUIC_LISTENER_EVENT *pEvent) {
  switch (pEvent->Type) {



  case QUIC_LISTENER_EVENT_NEW_CONNECTION: {
    API_TABLE->SetCallbackHandler(pEvent->NEW_CONNECTION.Connection, Quic::Peer::StaticConnectionCallback, this);
    QUIC_STATUS eQuicStatus = API_TABLE->ConnectionSetConfiguration(pEvent->NEW_CONNECTION.Connection, configuration_);
    if (QUIC_FAILED(eQuicStatus)) {
      return eQuicStatus;  // Here right? Need to close pEvent->NEW_CONNECTION.Connection?
    }

    // Then save the pEvent->NEW_CONNECTION.Connection
    break;



  case QUIC_LISTENER_EVENT_STOP_COMPLETE:
    // if pEvent->STOP_COMPLETE.AppCloseInProgress, we will call ListenerClose immediately after calling ListenerStop
    if (!pEvent->STOP_COMPLETE.AppCloseInProgress) {
      API_TABLE->ListenerClose(hListener);
    }
    break;



  default:
    break;
  }

  return QUIC_STATUS_SUCCESS;
}

[Streamlet]

For client mode, if ConnectionStart will trigger client side QUIC_CONNECTION_EVENT_CONNECTED or not?