1 /* Copyright 2019 The WebRTC project authors. All Rights Reserved. 2 * 3 * Use of this source code is governed by a BSD-style license 4 * that can be found in the LICENSE file in the root of the source 5 * tree. An additional intellectual property rights grant can be found 6 * in the file PATENTS. All contributing project authors may 7 * be found in the AUTHORS file in the root of the source tree. 8 */ 9 10 // This is an experimental interface and is subject to change without notice. 11 12 #ifndef API_TRANSPORT_DATA_CHANNEL_TRANSPORT_INTERFACE_H_ 13 #define API_TRANSPORT_DATA_CHANNEL_TRANSPORT_INTERFACE_H_ 14 15 #include "absl/types/optional.h" 16 #include "api/rtc_error.h" 17 #include "rtc_base/copy_on_write_buffer.h" 18 19 namespace webrtc { 20 21 // Supported types of application data messages. 22 enum class DataMessageType { 23 // Application data buffer with the binary bit unset. 24 kText, 25 26 // Application data buffer with the binary bit set. 27 kBinary, 28 29 // Transport-agnostic control messages, such as open or open-ack messages. 30 kControl, 31 }; 32 33 // Parameters for sending data. The parameters may change from message to 34 // message, even within a single channel. For example, control messages may be 35 // sent reliably and in-order, even if the data channel is configured for 36 // unreliable delivery. 37 struct SendDataParams { 38 SendDataParams() = default; 39 SendDataParams(const SendDataParams&) = default; 40 41 DataMessageType type = DataMessageType::kText; 42 43 // Whether to deliver the message in order with respect to other ordered 44 // messages with the same channel_id. 45 bool ordered = false; 46 47 // If set, the maximum number of times this message may be 48 // retransmitted by the transport before it is dropped. 49 // Setting this value to zero disables retransmission. 50 // Must be non-negative. |max_rtx_count| and |max_rtx_ms| may not be set 51 // simultaneously. 52 absl::optional<int> max_rtx_count; 53 54 // If set, the maximum number of milliseconds for which the transport 55 // may retransmit this message before it is dropped. 56 // Setting this value to zero disables retransmission. 57 // Must be non-negative. |max_rtx_count| and |max_rtx_ms| may not be set 58 // simultaneously. 59 absl::optional<int> max_rtx_ms; 60 }; 61 62 // Sink for callbacks related to a data channel. 63 class DataChannelSink { 64 public: 65 virtual ~DataChannelSink() = default; 66 67 // Callback issued when data is received by the transport. 68 virtual void OnDataReceived(int channel_id, 69 DataMessageType type, 70 const rtc::CopyOnWriteBuffer& buffer) = 0; 71 72 // Callback issued when a remote data channel begins the closing procedure. 73 // Messages sent after the closing procedure begins will not be transmitted. 74 virtual void OnChannelClosing(int channel_id) = 0; 75 76 // Callback issued when a (remote or local) data channel completes the closing 77 // procedure. Closing channels become closed after all pending data has been 78 // transmitted. 79 virtual void OnChannelClosed(int channel_id) = 0; 80 81 // Callback issued when the data channel becomes ready to send. 82 // This callback will be issued immediately when the data channel sink is 83 // registered if the transport is ready at that time. This callback may be 84 // invoked again following send errors (eg. due to the transport being 85 // temporarily blocked or unavailable). 86 virtual void OnReadyToSend() = 0; 87 88 // Callback issued when the data channel becomes unusable (closed). 89 // TODO(https://crbug.com/webrtc/10360): Make pure virtual when all 90 // consumers updated. OnTransportClosed()91 virtual void OnTransportClosed() {} 92 }; 93 94 // Transport for data channels. 95 class DataChannelTransportInterface { 96 public: 97 virtual ~DataChannelTransportInterface() = default; 98 99 // Opens a data |channel_id| for sending. May return an error if the 100 // specified |channel_id| is unusable. Must be called before |SendData|. 101 virtual RTCError OpenChannel(int channel_id) = 0; 102 103 // Sends a data buffer to the remote endpoint using the given send parameters. 104 // |buffer| may not be larger than 256 KiB. Returns an error if the send 105 // fails. 106 virtual RTCError SendData(int channel_id, 107 const SendDataParams& params, 108 const rtc::CopyOnWriteBuffer& buffer) = 0; 109 110 // Closes |channel_id| gracefully. Returns an error if |channel_id| is not 111 // open. Data sent after the closing procedure begins will not be 112 // transmitted. The channel becomes closed after pending data is transmitted. 113 virtual RTCError CloseChannel(int channel_id) = 0; 114 115 // Sets a sink for data messages and channel state callbacks. Before media 116 // transport is destroyed, the sink must be unregistered by setting it to 117 // nullptr. 118 virtual void SetDataSink(DataChannelSink* sink) = 0; 119 120 // Returns whether this data channel transport is ready to send. 121 // Note: the default implementation always returns false (as it assumes no one 122 // has implemented the interface). This default implementation is temporary. 123 virtual bool IsReadyToSend() const = 0; 124 }; 125 126 } // namespace webrtc 127 128 #endif // API_TRANSPORT_DATA_CHANNEL_TRANSPORT_INTERFACE_H_ 129