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 "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   enum DataState {  // Keep in sync with DataChannel.java:State.
    101     kConnecting,
    102     kOpen,  // The DataChannel is ready to send data.
    103     kClosing,
    104     kClosed
    105   };
    106 
    107   virtual void RegisterObserver(DataChannelObserver* observer) = 0;
    108   virtual void UnregisterObserver() = 0;
    109   // The label attribute represents a label that can be used to distinguish this
    110   // DataChannel object from other DataChannel objects.
    111   virtual std::string label() const = 0;
    112   virtual bool reliable() const = 0;
    113 
    114   // TODO(tommyw): Remove these dummy implementations when all classes have
    115   // implemented these APIs. They should all just return the values the
    116   // DataChannel was created with.
    117   virtual bool ordered() const { return false; }
    118   virtual uint16 maxRetransmitTime() const { return 0; }
    119   virtual uint16 maxRetransmits() const { return 0; }
    120   virtual std::string protocol() const { return std::string(); }
    121   virtual bool negotiated() const { return false; }
    122 
    123   virtual int id() const = 0;
    124   virtual DataState state() const = 0;
    125   // The buffered_amount returns the number of bytes of application data
    126   // (UTF-8 text and binary data) that have been queued using SendBuffer but
    127   // have not yet been transmitted to the network.
    128   virtual uint64 buffered_amount() const = 0;
    129   virtual void Close() = 0;
    130   // Sends |data| to the remote peer.
    131   virtual bool Send(const DataBuffer& buffer) = 0;
    132 
    133  protected:
    134   virtual ~DataChannelInterface() {}
    135 };
    136 
    137 }  // namespace webrtc
    138 
    139 #endif  // TALK_APP_WEBRTC_DATACHANNELINTERFACE_H_
    140