1 /* 2 * Copyright 2004 The WebRTC Project Authors. All rights reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef RTC_BASE_STREAM_H_ 12 #define RTC_BASE_STREAM_H_ 13 14 #include <memory> 15 16 #include "rtc_base/buffer.h" 17 #include "rtc_base/constructor_magic.h" 18 #include "rtc_base/message_handler.h" 19 #include "rtc_base/system/rtc_export.h" 20 #include "rtc_base/third_party/sigslot/sigslot.h" 21 #include "rtc_base/thread.h" 22 23 namespace rtc { 24 25 /////////////////////////////////////////////////////////////////////////////// 26 // StreamInterface is a generic asynchronous stream interface, supporting read, 27 // write, and close operations, and asynchronous signalling of state changes. 28 // The interface is designed with file, memory, and socket implementations in 29 // mind. Some implementations offer extended operations, such as seeking. 30 /////////////////////////////////////////////////////////////////////////////// 31 32 // The following enumerations are declared outside of the StreamInterface 33 // class for brevity in use. 34 35 // The SS_OPENING state indicates that the stream will signal open or closed 36 // in the future. 37 enum StreamState { SS_CLOSED, SS_OPENING, SS_OPEN }; 38 39 // Stream read/write methods return this value to indicate various success 40 // and failure conditions described below. 41 enum StreamResult { SR_ERROR, SR_SUCCESS, SR_BLOCK, SR_EOS }; 42 43 // StreamEvents are used to asynchronously signal state transitionss. The flags 44 // may be combined. 45 // SE_OPEN: The stream has transitioned to the SS_OPEN state 46 // SE_CLOSE: The stream has transitioned to the SS_CLOSED state 47 // SE_READ: Data is available, so Read is likely to not return SR_BLOCK 48 // SE_WRITE: Data can be written, so Write is likely to not return SR_BLOCK 49 enum StreamEvent { SE_OPEN = 1, SE_READ = 2, SE_WRITE = 4, SE_CLOSE = 8 }; 50 51 struct StreamEventData : public MessageData { 52 int events, error; StreamEventDataStreamEventData53 StreamEventData(int ev, int er) : events(ev), error(er) {} 54 }; 55 56 class RTC_EXPORT StreamInterface : public MessageHandler { 57 public: 58 enum { MSG_POST_EVENT = 0xF1F1, MSG_MAX = MSG_POST_EVENT }; 59 60 ~StreamInterface() override; 61 62 virtual StreamState GetState() const = 0; 63 64 // Read attempts to fill buffer of size buffer_len. Write attempts to send 65 // data_len bytes stored in data. The variables read and write are set only 66 // on SR_SUCCESS (see below). Likewise, error is only set on SR_ERROR. 67 // Read and Write return a value indicating: 68 // SR_ERROR: an error occurred, which is returned in a non-null error 69 // argument. Interpretation of the error requires knowledge of the 70 // stream's concrete type, which limits its usefulness. 71 // SR_SUCCESS: some number of bytes were successfully written, which is 72 // returned in a non-null read/write argument. 73 // SR_BLOCK: the stream is in non-blocking mode, and the operation would 74 // block, or the stream is in SS_OPENING state. 75 // SR_EOS: the end-of-stream has been reached, or the stream is in the 76 // SS_CLOSED state. 77 virtual StreamResult Read(void* buffer, 78 size_t buffer_len, 79 size_t* read, 80 int* error) = 0; 81 virtual StreamResult Write(const void* data, 82 size_t data_len, 83 size_t* written, 84 int* error) = 0; 85 // Attempt to transition to the SS_CLOSED state. SE_CLOSE will not be 86 // signalled as a result of this call. 87 virtual void Close() = 0; 88 89 // Streams may signal one or more StreamEvents to indicate state changes. 90 // The first argument identifies the stream on which the state change occured. 91 // The second argument is a bit-wise combination of StreamEvents. 92 // If SE_CLOSE is signalled, then the third argument is the associated error 93 // code. Otherwise, the value is undefined. 94 // Note: Not all streams will support asynchronous event signalling. However, 95 // SS_OPENING and SR_BLOCK returned from stream member functions imply that 96 // certain events will be raised in the future. 97 sigslot::signal3<StreamInterface*, int, int> SignalEvent; 98 99 // Like calling SignalEvent, but posts a message to the specified thread, 100 // which will call SignalEvent. This helps unroll the stack and prevent 101 // re-entrancy. 102 void PostEvent(Thread* t, int events, int err); 103 // Like the aforementioned method, but posts to the current thread. 104 void PostEvent(int events, int err); 105 106 // Return true if flush is successful. 107 virtual bool Flush(); 108 109 // 110 // CONVENIENCE METHODS 111 // 112 // These methods are implemented in terms of other methods, for convenience. 113 // 114 115 // WriteAll is a helper function which repeatedly calls Write until all the 116 // data is written, or something other than SR_SUCCESS is returned. Note that 117 // unlike Write, the argument 'written' is always set, and may be non-zero 118 // on results other than SR_SUCCESS. The remaining arguments have the 119 // same semantics as Write. 120 StreamResult WriteAll(const void* data, 121 size_t data_len, 122 size_t* written, 123 int* error); 124 125 protected: 126 StreamInterface(); 127 128 // MessageHandler Interface 129 void OnMessage(Message* msg) override; 130 131 private: 132 RTC_DISALLOW_COPY_AND_ASSIGN(StreamInterface); 133 }; 134 135 /////////////////////////////////////////////////////////////////////////////// 136 // StreamAdapterInterface is a convenient base-class for adapting a stream. 137 // By default, all operations are pass-through. Override the methods that you 138 // require adaptation. Streams should really be upgraded to reference-counted. 139 // In the meantime, use the owned flag to indicate whether the adapter should 140 // own the adapted stream. 141 /////////////////////////////////////////////////////////////////////////////// 142 143 class StreamAdapterInterface : public StreamInterface, 144 public sigslot::has_slots<> { 145 public: 146 explicit StreamAdapterInterface(StreamInterface* stream, bool owned = true); 147 148 // Core Stream Interface 149 StreamState GetState() const override; 150 StreamResult Read(void* buffer, 151 size_t buffer_len, 152 size_t* read, 153 int* error) override; 154 StreamResult Write(const void* data, 155 size_t data_len, 156 size_t* written, 157 int* error) override; 158 void Close() override; 159 160 bool Flush() override; 161 162 void Attach(StreamInterface* stream, bool owned = true); 163 StreamInterface* Detach(); 164 165 protected: 166 ~StreamAdapterInterface() override; 167 168 // Note that the adapter presents itself as the origin of the stream events, 169 // since users of the adapter may not recognize the adapted object. 170 virtual void OnEvent(StreamInterface* stream, int events, int err); stream()171 StreamInterface* stream() { return stream_; } 172 173 private: 174 StreamInterface* stream_; 175 bool owned_; 176 RTC_DISALLOW_COPY_AND_ASSIGN(StreamAdapterInterface); 177 }; 178 179 } // namespace rtc 180 181 #endif // RTC_BASE_STREAM_H_ 182