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