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
41namespace webrtc {
42
43struct 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
68struct 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
87class 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
98class 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