StreamShutdown function
Starts the shutdown process on a stream.
Syntax
typedef
_IRQL_requires_max_(DISPATCH_LEVEL)
QUIC_STATUS
(QUIC_API * QUIC_STREAM_SHUTDOWN_FN)(
_In_ _Pre_defensive_ HQUIC Stream,
_In_ QUIC_STREAM_SHUTDOWN_FLAGS Flags,
_In_ _Pre_defensive_ QUIC_UINT62 ErrorCode // Application defined error code
);
Parameters
Stream
The valid handle to an open and started stream object.
Flags
The set of flags that controls the type and behavior of shutdown:
Value | Meaning |
---|---|
QUIC_STREAM_SHUTDOWN_FLAG_NONE 0 |
Invalid option for StreamShutdown . |
QUIC_STREAM_SHUTDOWN_FLAG_GRACEFUL 1 |
Indicates the app is gracefully shutting down the stream in the send direction. |
QUIC_STREAM_SHUTDOWN_FLAG_ABORT_SEND 2 |
Indicates the app is abortively shutting down the stream in the send direction. |
QUIC_STREAM_SHUTDOWN_FLAG_ABORT_RECEIVE 4 |
Indicates the app is abortively shutting down the stream in the receive direction. |
QUIC_STREAM_SHUTDOWN_FLAG_IMMEDIATE 8 |
Indicates the app does not want to wait for the acknowledgment of the shutdown before getting the QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE event. Only allowed for abortive shutdowns. |
QUIC_STREAM_SHUTDOWN_FLAG_ABORT
is provided as a helper and is simply a logic OR of QUIC_STREAM_SHUTDOWN_FLAG_ABORT_SEND
and QUIC_STREAM_SHUTDOWN_FLAG_ABORT_RECEIVE
.
ErrorCode
Used for the abortive shutdown cases (QUIC_STREAM_SHUTDOWN_FLAG_ABORT_SEND
and QUIC_STREAM_SHUTDOWN_FLAG_ABORT_RECEIVE
) to indicate the reason why the abort happened to the peer.
Return Value
The function returns a QUIC_STATUS. The app may use QUIC_FAILED
or QUIC_SUCCEEDED
to determine if the function failed or succeeded.
Remarks
This function allows an app to (either gracefully or abortively) shut down one or both directions of a stream. For abortive shutdowns, the app specifies an ErrorCode
that is transmitted to the peer to indicate why the shutdown happened. Graceful shutdowns have no error code as they are implied to be the normal operation of a stream.
If the app doesn't care to wait for the acknowledgment of an abortive shutdown, it can use the QUIC_STREAM_SHUTDOWN_FLAG_IMMEDIATE
flag, which will result in MsQuic immediately (not necessarily inline to the call though) indicating the QUIC_STREAM_EVENT_SHUTDOWN_COMPLETE
event to the app, after which, the app may safely StreamClose the stream. MsQuic will internally maintain the stream for as long as necessary and then clean it up.
The stream can also be gracefully shutdown via the QUIC_SEND_FLAG_FIN
flag. See StreamSend for more details.
Any stream (even one that hasn't been started) may be called to shutdown. If the stream has not been started yet, then the shutdown is effectively queued. If the app never calls StreamStart then the shutdown will never been sent out on the wire.
Reliable Reset
If an app decides to enable Preview Features, the shutdown path can be configured with the QUIC_PARAM_STREAM_RELIABLE_OFFSET Stream parameter, which determines the number of bytes a sender must deliver before it can shut down their SEND path.
See Also
StreamOpen
StreamClose
StreamStart
StreamSend
StreamReceiveComplete
StreamReceiveSetEnabled