src/third_party/libjingle/source/talk/app/webrtc/datachannelinterface.h

   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 "talk/base/basictypes.h"
  37 #include "talk/base/buffer.h"
  38 #include "talk/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 talk_base::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   talk_base::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 talk_base::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_