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/refcount.h" 39 40 41 namespace webrtc { 42 43 struct DataChannelInit { 44 DataChannelInit() 45 : reliable(false), 46 ordered(true), 47 maxRetransmitTime(-1), 48 maxRetransmits(-1), 49 negotiated(false), 50 id(-1) { 51 } 52 53 bool reliable; // Deprecated. 54 bool ordered; // True if ordered delivery is required. 55 int maxRetransmitTime; // The max period of time in milliseconds in which 56 // retransmissions will be sent. After this time, no 57 // more retransmissions will be sent. -1 if unset. 58 int maxRetransmits; // The max number of retransmissions. -1 if unset. 59 std::string protocol; // This is set by the application and opaque to the 60 // WebRTC implementation. 61 bool negotiated; // True if the channel has been externally negotiated 62 // and we do not send an in-band signalling in the 63 // form of an "open" message. 64 int id; // The stream id, or SID, for SCTP data channels. -1 65 // if unset. 66 }; 67 68 struct DataBuffer { 69 DataBuffer(const rtc::Buffer& data, bool binary) 70 : data(data), 71 binary(binary) { 72 } 73 // For convenience for unit tests. 74 explicit DataBuffer(const std::string& text) 75 : data(text.data(), text.length()), 76 binary(false) { 77 } 78 size_t size() const { return data.length(); } 79 80 rtc::Buffer data; 81 // Indicates if the received data contains UTF-8 or binary data. 82 // Note that the upper layers are left to verify the UTF-8 encoding. 83 // TODO(jiayl): prefer to use an enum instead of a bool. 84 bool binary; 85 }; 86 87 class DataChannelObserver { 88 public: 89 // The data channel state have changed. 90 virtual void OnStateChange() = 0; 91 // A data buffer was successfully received. 92 virtual void OnMessage(const DataBuffer& buffer) = 0; 93 94 protected: 95 virtual ~DataChannelObserver() {} 96 }; 97 98 class DataChannelInterface : public rtc::RefCountInterface { 99 public: 100 // Keep in sync with DataChannel.java:State and 101 // RTCDataChannel.h:RTCDataChannelState. 102 enum DataState { 103 kConnecting, 104 kOpen, // The DataChannel is ready to send data. 105 kClosing, 106 kClosed 107 }; 108 109 virtual void RegisterObserver(DataChannelObserver* observer) = 0; 110 virtual void UnregisterObserver() = 0; 111 // The label attribute represents a label that can be used to distinguish this 112 // DataChannel object from other DataChannel objects. 113 virtual std::string label() const = 0; 114 virtual bool reliable() const = 0; 115 116 // TODO(tommyw): Remove these dummy implementations when all classes have 117 // implemented these APIs. They should all just return the values the 118 // DataChannel was created with. 119 virtual bool ordered() const { return false; } 120 virtual uint16 maxRetransmitTime() const { return 0; } 121 virtual uint16 maxRetransmits() const { return 0; } 122 virtual std::string protocol() const { return std::string(); } 123 virtual bool negotiated() const { return false; } 124 125 virtual int id() const = 0; 126 virtual DataState state() const = 0; 127 // The buffered_amount returns the number of bytes of application data 128 // (UTF-8 text and binary data) that have been queued using SendBuffer but 129 // have not yet been transmitted to the network. 130 virtual uint64 buffered_amount() const = 0; 131 virtual void Close() = 0; 132 // Sends |data| to the remote peer. 133 virtual bool Send(const DataBuffer& buffer) = 0; 134 135 protected: 136 virtual ~DataChannelInterface() {} 137 }; 138 139 } // namespace webrtc 140 141 #endif // TALK_APP_WEBRTC_DATACHANNELINTERFACE_H_ 142