diff options
Diffstat (limited to 'net/dcsctp/public/dcsctp_socket.h')
| -rw-r--r-- | net/dcsctp/public/dcsctp_socket.h | 148 |
1 files changed, 113 insertions, 35 deletions
diff --git a/net/dcsctp/public/dcsctp_socket.h b/net/dcsctp/public/dcsctp_socket.h index e7f21349bd..f07f54e044 100644 --- a/net/dcsctp/public/dcsctp_socket.h +++ b/net/dcsctp/public/dcsctp_socket.h @@ -18,12 +18,27 @@ #include "absl/types/optional.h" #include "api/array_view.h" #include "net/dcsctp/public/dcsctp_message.h" +#include "net/dcsctp/public/dcsctp_options.h" #include "net/dcsctp/public/packet_observer.h" #include "net/dcsctp/public/timeout.h" #include "net/dcsctp/public/types.h" namespace dcsctp { +// The socket/association state +enum class SocketState { + // The socket is closed. + kClosed, + // The socket has initiated a connection, which is not yet established. Note + // that for incoming connections and for reconnections when the socket is + // already connected, the socket will not transition to this state. + kConnecting, + // The socket is connected, and the connection is established. + kConnected, + // The socket is shutting down, and the connection is not yet closed. + kShuttingDown, +}; + // Send options for sending messages struct SendOptions { // If the message should be sent with unordered message delivery. @@ -59,6 +74,8 @@ enum class ErrorKind { kProtocolViolation, // The receive or send buffers have been exhausted. kResourceExhaustion, + // The client has performed an invalid operation. + kUnsupportedOperation, }; inline constexpr absl::string_view ToString(ErrorKind error) { @@ -79,19 +96,65 @@ inline constexpr absl::string_view ToString(ErrorKind error) { return "PROTOCOL_VIOLATION"; case ErrorKind::kResourceExhaustion: return "RESOURCE_EXHAUSTION"; + case ErrorKind::kUnsupportedOperation: + return "UNSUPPORTED_OPERATION"; } } -// Return value of SupportsStreamReset. -enum class StreamResetSupport { +enum class SendStatus { + // The message was enqueued successfully. As sending the message is done + // asynchronously, this is no guarantee that the message has been actually + // sent. + kSuccess, + // The message was rejected as the payload was empty (which is not allowed in + // SCTP). + kErrorMessageEmpty, + // The message was rejected as the payload was larger than what has been set + // as `DcSctpOptions.max_message_size`. + kErrorMessageTooLarge, + // The message could not be enqueued as the socket is out of resources. This + // mainly indicates that the send queue is full. + kErrorResourceExhaustion, + // The message could not be sent as the socket is shutting down. + kErrorShuttingDown, +}; + +inline constexpr absl::string_view ToString(SendStatus error) { + switch (error) { + case SendStatus::kSuccess: + return "SUCCESS"; + case SendStatus::kErrorMessageEmpty: + return "ERROR_MESSAGE_EMPTY"; + case SendStatus::kErrorMessageTooLarge: + return "ERROR_MESSAGE_TOO_LARGE"; + case SendStatus::kErrorResourceExhaustion: + return "ERROR_RESOURCE_EXHAUSTION"; + case SendStatus::kErrorShuttingDown: + return "ERROR_SHUTTING_DOWN"; + } +} + +// Return value of ResetStreams. +enum class ResetStreamsStatus { // If the connection is not yet established, this will be returned. - kUnknown, - // Indicates that Stream Reset is supported by the peer. - kSupported, - // Indicates that Stream Reset is not supported by the peer. + kNotConnected, + // Indicates that ResetStreams operation has been successfully initiated. + kPerformed, + // Indicates that ResetStreams has failed as it's not supported by the peer. kNotSupported, }; +inline constexpr absl::string_view ToString(ResetStreamsStatus error) { + switch (error) { + case ResetStreamsStatus::kNotConnected: + return "NOT_CONNECTED"; + case ResetStreamsStatus::kPerformed: + return "PERFORMED"; + case ResetStreamsStatus::kNotSupported: + return "NOT_SUPPORTED"; + } +} + // Callbacks that the DcSctpSocket will be done synchronously to the owning // client. It is allowed to call back into the library from callbacks that start // with "On". It has been explicitly documented when it's not allowed to call @@ -123,9 +186,9 @@ class DcSctpSocketCallbacks { virtual TimeMs TimeMillis() = 0; // Called when the library needs a random number uniformly distributed between - // `low` (inclusive) and `high` (exclusive). The random number used by the - // library are not used for cryptographic purposes there are no requirements - // on a secure random number generator. + // `low` (inclusive) and `high` (exclusive). The random numbers used by the + // library are not used for cryptographic purposes. There are no requirements + // that the random number generator must be secure. // // Note that it's NOT ALLOWED to call into this library from within this // callback. @@ -134,12 +197,11 @@ class DcSctpSocketCallbacks { // Triggered when the outgoing message buffer is empty, meaning that there are // no more queued messages, but there can still be packets in-flight or to be // retransmitted. (in contrast to SCTP_SENDER_DRY_EVENT). - // TODO(boivie): This is currently only used in benchmarks to have a steady - // flow of packets to send // // Note that it's NOT ALLOWED to call into this library from within this // callback. - virtual void NotifyOutgoingMessageBufferEmpty() = 0; + ABSL_DEPRECATED("Use OnTotalBufferedAmountLow instead") + virtual void NotifyOutgoingMessageBufferEmpty() {} // Called when the library has received an SCTP message in full and delivers // it to the upper layer. @@ -201,14 +263,16 @@ class DcSctpSocketCallbacks { virtual void OnIncomingStreamsReset( rtc::ArrayView<const StreamID> incoming_streams) = 0; - // If an outgoing message has expired before being completely sent. - // TODO(boivie) Add some kind of message identifier. - // TODO(boivie) Add callbacks for OnMessageSent and OnSentMessageAcked + // Will be called when the amount of data buffered to be sent falls to or + // below the threshold set when calling `SetBufferedAmountLowThreshold`. // // It is allowed to call into this library from within this callback. - virtual void OnSentMessageExpired(StreamID stream_id, - PPID ppid, - bool unsent) = 0; + virtual void OnBufferedAmountLow(StreamID stream_id) {} + + // Will be called when the total amount of data buffered (in the entire send + // buffer, for all streams) falls to or below the threshold specified in + // `DcSctpOptions::total_buffered_amount_low_threshold`. + virtual void OnTotalBufferedAmountLow() {} }; // The DcSctpSocket implementation implements the following interface. @@ -236,6 +300,25 @@ class DcSctpSocketInterface { // not already closed. No callbacks will be made after Close() has returned. virtual void Close() = 0; + // The socket state. + virtual SocketState state() const = 0; + + // The options it was created with. + virtual const DcSctpOptions& options() const = 0; + + // Update the options max_message_size. + virtual void SetMaxMessageSize(size_t max_message_size) = 0; + + // Sends the message `message` using the provided send options. + // Sending a message is an asynchrous operation, and the `OnError` callback + // may be invoked to indicate any errors in sending the message. + // + // The association does not have to be established before calling this method. + // If it's called before there is an established association, the message will + // be queued. + virtual SendStatus Send(DcSctpMessage message, + const SendOptions& send_options) = 0; + // Resetting streams is an asynchronous operation and the results will // be notified using `DcSctpSocketCallbacks::OnStreamsResetDone()` on success // and `DcSctpSocketCallbacks::OnStreamsResetFailed()` on failure. Note that @@ -251,27 +334,22 @@ class DcSctpSocketInterface { // Resetting streams can only be done on an established association that // supports stream resetting. Calling this method on e.g. a closed association // or streams that don't support resetting will not perform any operation. - virtual void ResetStreams( + virtual ResetStreamsStatus ResetStreams( rtc::ArrayView<const StreamID> outgoing_streams) = 0; - // Indicates if the peer supports resetting streams (RFC6525). Please note - // that the connection must be established for support to be known. - virtual StreamResetSupport SupportsStreamReset() const = 0; + // Returns the number of bytes of data currently queued to be sent on a given + // stream. + virtual size_t buffered_amount(StreamID stream_id) const = 0; - // Sends the message `message` using the provided send options. - // Sending a message is an asynchrous operation, and the `OnError` callback - // may be invoked to indicate any errors in sending the message. - // - // The association does not have to be established before calling this method. - // If it's called before there is an established association, the message will - // be queued. - void Send(DcSctpMessage message, const SendOptions& send_options = {}) { - SendMessage(std::move(message), send_options); - } + // Returns the number of buffered outgoing bytes that is considered "low" for + // a given stream. See `SetBufferedAmountLowThreshold`. + virtual size_t buffered_amount_low_threshold(StreamID stream_id) const = 0; - private: - virtual void SendMessage(DcSctpMessage message, - const SendOptions& send_options) = 0; + // Used to specify the number of bytes of buffered outgoing data that is + // considered "low" for a given stream, which will trigger an + // OnBufferedAmountLow event. The default value is zero (0). + virtual void SetBufferedAmountLowThreshold(StreamID stream_id, + size_t bytes) = 0; }; } // namespace dcsctp |