Home | History | Annotate | Download | only in webrtc 
      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 {
     45   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 {
     70   DataBuffer(const rtc::Buffer& data, bool binary)
     71       : data(data),
     72         binary(binary) {
     73   }
     74   // For convenience for unit tests.
     75   explicit DataBuffer(const std::string& text)
     76       : data(text.data(), text.length()),
     77         binary(false) {
     78   }
     79   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.
     95   virtual void OnBufferedAmountChange(uint64_t previous_amount){};
     96 
     97  protected:
     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 
    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.
    137   virtual bool ordered() const { return false; }
    138   virtual uint16_t maxRetransmitTime() const { return 0; }
    139   virtual uint16_t maxRetransmits() const { return 0; }
    140   virtual std::string protocol() const { return std::string(); }
    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:
    154   virtual ~DataChannelInterface() {}
    155 };
    156 
    157 }  // namespace webrtc
    158 
    159 #endif  // TALK_APP_WEBRTC_DATACHANNELINTERFACE_H_
    160