1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/*
* Copyright 2012 The WebRTC project authors. All Rights Reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
// This file contains interfaces for DataChannels
// http://dev.w3.org/2011/webrtc/editor/webrtc.html#rtcdatachannel
#ifndef API_DATA_CHANNEL_INTERFACE_H_
#define API_DATA_CHANNEL_INTERFACE_H_
#include <stddef.h>
#include <stdint.h>
#include <string>
#include "absl/types/optional.h"
#include "api/priority.h"
#include "api/rtc_error.h"
#include "rtc_base/checks.h"
#include "rtc_base/copy_on_write_buffer.h"
#include "rtc_base/ref_count.h"
#include "rtc_base/system/rtc_export.h"
namespace webrtc {
// C++ version of: https://www.w3.org/TR/webrtc/#idl-def-rtcdatachannelinit
// TODO(deadbeef): Use absl::optional for the "-1 if unset" things.
struct DataChannelInit {
// Deprecated. Reliability is assumed, and channel will be unreliable if
// maxRetransmitTime or MaxRetransmits is set.
bool reliable = false;
// True if ordered delivery is required.
bool ordered = true;
// The max period of time in milliseconds in which retransmissions will be
// sent. After this time, no more retransmissions will be sent.
//
// Cannot be set along with `maxRetransmits`.
// This is called `maxPacketLifeTime` in the WebRTC JS API.
// Negative values are ignored, and positive values are clamped to [0-65535]
absl::optional<int> maxRetransmitTime;
// The max number of retransmissions.
//
// Cannot be set along with `maxRetransmitTime`.
// Negative values are ignored, and positive values are clamped to [0-65535]
absl::optional<int> maxRetransmits;
// This is set by the application and opaque to the WebRTC implementation.
std::string protocol;
// True if the channel has been externally negotiated and we do not send an
// in-band signalling in the form of an "open" message. If this is true, `id`
// below must be set; otherwise it should be unset and will be negotiated
// in-band.
bool negotiated = false;
// The stream id, or SID, for SCTP data channels. -1 if unset (see above).
int id = -1;
// https://w3c.github.io/webrtc-priority/#new-rtcdatachannelinit-member
absl::optional<Priority> priority;
};
// At the JavaScript level, data can be passed in as a string or a blob, so
// this structure's `binary` flag tells whether the data should be interpreted
// as binary or text.
struct DataBuffer {
DataBuffer(const rtc::CopyOnWriteBuffer& data, bool binary)
: data(data), binary(binary) {}
// For convenience for unit tests.
explicit DataBuffer(const std::string& text)
: data(text.data(), text.length()), binary(false) {}
size_t size() const { return data.size(); }
rtc::CopyOnWriteBuffer data;
// Indicates if the received data contains UTF-8 or binary data.
// Note that the upper layers are left to verify the UTF-8 encoding.
// TODO(jiayl): prefer to use an enum instead of a bool.
bool binary;
};
// Used to implement RTCDataChannel events.
//
// The code responding to these callbacks should unwind the stack before
// using any other webrtc APIs; re-entrancy is not supported.
class DataChannelObserver {
public:
// The data channel state have changed.
virtual void OnStateChange() = 0;
// A data buffer was successfully received.
virtual void OnMessage(const DataBuffer& buffer) = 0;
// The data channel's buffered_amount has changed.
virtual void OnBufferedAmountChange(uint64_t sent_data_size) {}
protected:
virtual ~DataChannelObserver() = default;
};
class RTC_EXPORT DataChannelInterface : public rtc::RefCountInterface {
public:
// C++ version of: https://www.w3.org/TR/webrtc/#idl-def-rtcdatachannelstate
// Unlikely to change, but keep in sync with DataChannel.java:State and
// RTCDataChannel.h:RTCDataChannelState.
enum DataState {
kConnecting,
kOpen, // The DataChannel is ready to send data.
kClosing,
kClosed
};
static const char* DataStateString(DataState state) {
switch (state) {
case kConnecting:
return "connecting";
case kOpen:
return "open";
case kClosing:
return "closing";
case kClosed:
return "closed";
}
RTC_CHECK(false) << "Unknown DataChannel state: " << state;
return "";
}
// Used to receive events from the data channel. Only one observer can be
// registered at a time. UnregisterObserver should be called before the
// observer object is destroyed.
virtual void RegisterObserver(DataChannelObserver* observer) = 0;
virtual void UnregisterObserver() = 0;
// The label attribute represents a label that can be used to distinguish this
// DataChannel object from other DataChannel objects.
virtual std::string label() const = 0;
// The accessors below simply return the properties from the DataChannelInit
// the data channel was constructed with.
virtual bool reliable() const = 0;
// TODO(deadbeef): Remove these dummy implementations when all classes have
// implemented these APIs. They should all just return the values the
// DataChannel was created with.
virtual bool ordered() const;
// TODO(hta): Deprecate and remove the following two functions.
virtual uint16_t maxRetransmitTime() const;
virtual uint16_t maxRetransmits() const;
virtual absl::optional<int> maxRetransmitsOpt() const;
virtual absl::optional<int> maxPacketLifeTime() const;
virtual std::string protocol() const;
virtual bool negotiated() const;
// Returns the ID from the DataChannelInit, if it was negotiated out-of-band.
// If negotiated in-band, this ID will be populated once the DTLS role is
// determined, and until then this will return -1.
virtual int id() const = 0;
virtual Priority priority() const { return Priority::kLow; }
virtual DataState state() const = 0;
// When state is kClosed, and the DataChannel was not closed using
// the closing procedure, returns the error information about the closing.
// The default implementation returns "no error".
virtual RTCError error() const { return RTCError(); }
virtual uint32_t messages_sent() const = 0;
virtual uint64_t bytes_sent() const = 0;
virtual uint32_t messages_received() const = 0;
virtual uint64_t bytes_received() const = 0;
// Returns the number of bytes of application data (UTF-8 text and binary
// data) that have been queued using Send but have not yet been processed at
// the SCTP level. See comment above Send below.
// Values are less or equal to MaxSendQueueSize().
virtual uint64_t buffered_amount() const = 0;
// Begins the graceful data channel closing procedure. See:
// https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel-13#section-6.7
virtual void Close() = 0;
// Sends `data` to the remote peer. If the data can't be sent at the SCTP
// level (due to congestion control), it's buffered at the data channel level,
// up to a maximum of MaxSendQueueSize().
// Returns false if the data channel is not in open state or if the send
// buffer is full.
// TODO(webrtc:13289): Return an RTCError with information about the failure.
virtual bool Send(const DataBuffer& buffer) = 0;
// Amount of bytes that can be queued for sending on the data channel.
// Those are bytes that have not yet been processed at the SCTP level.
static uint64_t MaxSendQueueSize();
protected:
~DataChannelInterface() override = default;
};
} // namespace webrtc
#endif // API_DATA_CHANNEL_INTERFACE_H_
|
