1 /* 2 * libjingle 3 * Copyright 2012 Google Inc. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 9 * this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 // This file contains interfaces for DataChannels 29 // http://dev.w3.org/2011/webrtc/editor/webrtc.html#rtcdatachannel 30 31 #ifndef TALK_APP_WEBRTC_DATACHANNELINTERFACE_H_ 32 #define TALK_APP_WEBRTC_DATACHANNELINTERFACE_H_ 33 34 #include <string> 35 36 #include "webrtc/base/basictypes.h" 37 #include "webrtc/base/buffer.h" 38 #include "webrtc/base/checks.h" 39 #include "webrtc/base/refcount.h" 40 41 42 namespace webrtc { 43 44 struct DataChannelInit { DataChannelInitDataChannelInit45 DataChannelInit() 46 : reliable(false), 47 ordered(true), 48 maxRetransmitTime(-1), 49 maxRetransmits(-1), 50 negotiated(false), 51 id(-1) { 52 } 53 54 bool reliable; // Deprecated. 55 bool ordered; // True if ordered delivery is required. 56 int maxRetransmitTime; // The max period of time in milliseconds in which 57 // retransmissions will be sent. After this time, no 58 // more retransmissions will be sent. -1 if unset. 59 int maxRetransmits; // The max number of retransmissions. -1 if unset. 60 std::string protocol; // This is set by the application and opaque to the 61 // WebRTC implementation. 62 bool negotiated; // True if the channel has been externally negotiated 63 // and we do not send an in-band signalling in the 64 // form of an "open" message. 65 int id; // The stream id, or SID, for SCTP data channels. -1 66 // if unset. 67 }; 68 69 struct DataBuffer { DataBufferDataBuffer70 DataBuffer(const rtc::Buffer& data, bool binary) 71 : data(data), 72 binary(binary) { 73 } 74 // For convenience for unit tests. DataBufferDataBuffer75 explicit DataBuffer(const std::string& text) 76 : data(text.data(), text.length()), 77 binary(false) { 78 } sizeDataBuffer79 size_t size() const { return data.size(); } 80 81 rtc::Buffer data; 82 // Indicates if the received data contains UTF-8 or binary data. 83 // Note that the upper layers are left to verify the UTF-8 encoding. 84 // TODO(jiayl): prefer to use an enum instead of a bool. 85 bool binary; 86 }; 87 88 class DataChannelObserver { 89 public: 90 // The data channel state have changed. 91 virtual void OnStateChange() = 0; 92 // A data buffer was successfully received. 93 virtual void OnMessage(const DataBuffer& buffer) = 0; 94 // The data channel's buffered_amount has changed. OnBufferedAmountChange(uint64_t previous_amount)95 virtual void OnBufferedAmountChange(uint64_t previous_amount){}; 96 97 protected: ~DataChannelObserver()98 virtual ~DataChannelObserver() {} 99 }; 100 101 class DataChannelInterface : public rtc::RefCountInterface { 102 public: 103 // Keep in sync with DataChannel.java:State and 104 // RTCDataChannel.h:RTCDataChannelState. 105 enum DataState { 106 kConnecting, 107 kOpen, // The DataChannel is ready to send data. 108 kClosing, 109 kClosed 110 }; 111 DataStateString(DataState state)112 static const char* DataStateString(DataState state) { 113 switch (state) { 114 case kConnecting: 115 return "connecting"; 116 case kOpen: 117 return "open"; 118 case kClosing: 119 return "closing"; 120 case kClosed: 121 return "closed"; 122 } 123 RTC_CHECK(false) << "Unknown DataChannel state: " << state; 124 return ""; 125 } 126 127 virtual void RegisterObserver(DataChannelObserver* observer) = 0; 128 virtual void UnregisterObserver() = 0; 129 // The label attribute represents a label that can be used to distinguish this 130 // DataChannel object from other DataChannel objects. 131 virtual std::string label() const = 0; 132 virtual bool reliable() const = 0; 133 134 // TODO(tommyw): Remove these dummy implementations when all classes have 135 // implemented these APIs. They should all just return the values the 136 // DataChannel was created with. ordered()137 virtual bool ordered() const { return false; } maxRetransmitTime()138 virtual uint16_t maxRetransmitTime() const { return 0; } maxRetransmits()139 virtual uint16_t maxRetransmits() const { return 0; } protocol()140 virtual std::string protocol() const { return std::string(); } negotiated()141 virtual bool negotiated() const { return false; } 142 143 virtual int id() const = 0; 144 virtual DataState state() const = 0; 145 // The buffered_amount returns the number of bytes of application data 146 // (UTF-8 text and binary data) that have been queued using SendBuffer but 147 // have not yet been transmitted to the network. 148 virtual uint64_t buffered_amount() const = 0; 149 virtual void Close() = 0; 150 // Sends |data| to the remote peer. 151 virtual bool Send(const DataBuffer& buffer) = 0; 152 153 protected: ~DataChannelInterface()154 virtual ~DataChannelInterface() {} 155 }; 156 157 } // namespace webrtc 158 159 #endif // TALK_APP_WEBRTC_DATACHANNELINTERFACE_H_ 160