diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-06-06 16:25:12 +0100 |
---|---|---|
committer | Pauli <pauli@openssl.org> | 2023-07-17 08:17:58 +1000 |
commit | b3695154b5cfd8ac528b8c2794d2dc446899caae (patch) | |
tree | b99a290918363e7f386ba4d845e56d30f8c7b5ab /include | |
parent | 08d4b7eb7dac5d1c4d270f60d421a20e5df3c39a (diff) |
QUIC QSM: Update API documentation
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21135)
Diffstat (limited to 'include')
-rw-r--r-- | include/internal/quic_stream_map.h | 63 |
1 files changed, 42 insertions, 21 deletions
diff --git a/include/internal/quic_stream_map.h b/include/internal/quic_stream_map.h index e1ad864a72..5c31811aaa 100644 --- a/include/internal/quic_stream_map.h +++ b/include/internal/quic_stream_map.h @@ -634,11 +634,12 @@ int ossl_quic_stream_map_ensure_send_part_id(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs); /* - * Transitions from READY or SEND to the DATA_SENT state. Note that this is NOT - * the same as the point in time at which the final size of the stream becomes - * known (i.e., the time at which ossl_quic_sstream_fin()) is called as it - * occurs when we have SENT all data on a given stream send part, not merely - * buffered it. + * Transitions from SEND to the DATA_SENT state. Note that this is NOT the same + * as the point in time at which the final size of the stream becomes known + * (i.e., the time at which ossl_quic_sstream_fin()) is called as it occurs when + * we have SENT all data on a given stream send part, not merely buffered it. + * Note that this transition is NOT reversed in the event of some of that data + * being lost. * * Returns 1 if the state transition was successfully taken. Returns 0 if there * is no send part (caller error) or if the state transition cannot be taken @@ -651,12 +652,11 @@ int ossl_quic_stream_map_notify_all_data_sent(QUIC_STREAM_MAP *qsm, * Transitions from the DATA_SENT to DATA_RECVD state; should be called * when all transmitted stream data is ACKed by the peer. * - * Returns 1 if the state transition was successfully taken, or if the send part - * was already in the DATA_RECVD state. Returns 0 if there is no send part - * (caller error) or the state transition cannot be taken because the send part - * is not in the DATA_SENT or DATA_RECVD states. Because - * ossl_quic_stream_map_fin_send_part() should always be called prior to this - * function, the send state must already be in DATA_SENT in order for this + * Returns 1 if the state transition was successfully taken. Returns 0 if there + * is no send part (caller error) or the state transition cannot be taken + * because the send part is not in the DATA_SENT state. Because + * ossl_quic_stream_map_notify_all_data_sent() should always be called prior to + * this function, the send state must already be in DATA_SENT in order for this * function to succeed. */ int ossl_quic_stream_map_notify_totally_acked(QUIC_STREAM_MAP *qsm, @@ -685,9 +685,10 @@ int ossl_quic_stream_map_reset_stream_send_part(QUIC_STREAM_MAP *qsm, * part was in one of the states above) or if it is already in the RESET_RECVD * state (idempotent operation). * - * It returns 0 if not in the RESET_SENT state, as this function should only be - * called after we have already sent a RESET_STREAM frame and entered the - * RESET_SENT state. It also returns 0 if there is no send part (caller error). + * It returns 0 if not in the RESET_SENT or RESET_RECVD states, as this function + * should only be called after we have already sent a RESET_STREAM frame and + * entered the RESET_SENT state. It also returns 0 if there is no send part + * (caller error). */ int ossl_quic_stream_map_notify_reset_stream_acked(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs); @@ -699,9 +700,9 @@ int ossl_quic_stream_map_notify_reset_stream_acked(QUIC_STREAM_MAP *qsm, */ /* - * Transitions from the RECV to SIZE_KNOWN receive stream states. This should be - * called once a STREAM frame is received for the stream with the FIN bit set. - * final_size should be the final size of the stream in bytes. + * Transitions from the RECV receive stream state to the SIZE_KNOWN state. This + * should be called once a STREAM frame is received for the stream with the FIN + * bit set. final_size should be the final size of the stream in bytes. * * Returns 1 if the transition was taken. */ @@ -709,21 +710,41 @@ int ossl_quic_stream_map_notify_size_known_recv_part(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs, uint64_t final_size); -/* SIZE_KNOWN -> DATA_RECVD */ +/* + * Transitions from the SIZE_KNOWN receive stream state to the DATA_RECVD state. + * This should be called once all data for a receive stream is received. + * + * Returns 1 if the transition was taken. + */ int ossl_quic_stream_map_notify_totally_received(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs); -/* DATA_RECVD -> DATA_READ */ +/* + * Transitions from the DATA_RECVD receive stream state to the DATA_READ state. + * This shuld be called once all data for a receive stream is read by the + * application. + * + * Returns 1 if the transition was taken. + */ int ossl_quic_stream_map_notify_totally_read(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs); -/* RECV/SIZE_KNOWN/DATA_RECVD -> RESET_RECVD */ +/* + * Transitions from the RECV, SIZE_KNOWN or DATA_RECVD receive stream state to + * the RESET_RECVD state. This should be called on RESET_STREAM. + * + * Returns 1 if the transition was taken. + */ int ossl_quic_stream_map_notify_reset_recv_part(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs, uint64_t app_error_code, uint64_t final_size); -/* RESET_RECVD -> RESET_READ */ +/* + * Transitions from the RESET_RECVD receive stream state to the RESET_READ + * receive stream state. This should be called when the application is notified + * of a stream reset. + */ int ossl_quic_stream_map_notify_app_read_reset_recv_part(QUIC_STREAM_MAP *qsm, QUIC_STREAM *qs); |