• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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