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 "api/array_view.h" 17 #include "rtc_base/buffer.h" 18 #include "rtc_base/system/rtc_export.h" 19 #include "rtc_base/third_party/sigslot/sigslot.h" 20 #include "rtc_base/thread.h" 21 22 namespace rtc { 23 24 /////////////////////////////////////////////////////////////////////////////// 25 // StreamInterface is a generic asynchronous stream interface, supporting read, 26 // write, and close operations, and asynchronous signalling of state changes. 27 // The interface is designed with file, memory, and socket implementations in 28 // mind. Some implementations offer extended operations, such as seeking. 29 /////////////////////////////////////////////////////////////////////////////// 30 31 // The following enumerations are declared outside of the StreamInterface 32 // class for brevity in use. 33 34 // The SS_OPENING state indicates that the stream will signal open or closed 35 // in the future. 36 enum StreamState { SS_CLOSED, SS_OPENING, SS_OPEN }; 37 38 // Stream read/write methods return this value to indicate various success 39 // and failure conditions described below. 40 enum StreamResult { SR_ERROR, SR_SUCCESS, SR_BLOCK, SR_EOS }; 41 42 // StreamEvents are used to asynchronously signal state transitionss. The flags 43 // may be combined. 44 // SE_OPEN: The stream has transitioned to the SS_OPEN state 45 // SE_CLOSE: The stream has transitioned to the SS_CLOSED state 46 // SE_READ: Data is available, so Read is likely to not return SR_BLOCK 47 // SE_WRITE: Data can be written, so Write is likely to not return SR_BLOCK 48 enum StreamEvent { SE_OPEN = 1, SE_READ = 2, SE_WRITE = 4, SE_CLOSE = 8 }; 49 50 class RTC_EXPORT StreamInterface { 51 public: ~StreamInterface()52 virtual ~StreamInterface() {} 53 54 StreamInterface(const StreamInterface&) = delete; 55 StreamInterface& operator=(const StreamInterface&) = delete; 56 57 virtual StreamState GetState() const = 0; 58 59 // Read attempts to fill buffer of size buffer_len. Write attempts to send 60 // data_len bytes stored in data. The variables read and write are set only 61 // on SR_SUCCESS (see below). Likewise, error is only set on SR_ERROR. 62 // Read and Write return a value indicating: 63 // SR_ERROR: an error occurred, which is returned in a non-null error 64 // argument. Interpretation of the error requires knowledge of the 65 // stream's concrete type, which limits its usefulness. 66 // SR_SUCCESS: some number of bytes were successfully written, which is 67 // returned in a non-null read/write argument. 68 // SR_BLOCK: the stream is in non-blocking mode, and the operation would 69 // block, or the stream is in SS_OPENING state. 70 // SR_EOS: the end-of-stream has been reached, or the stream is in the 71 // SS_CLOSED state. 72 73 virtual StreamResult Read(rtc::ArrayView<uint8_t> buffer, 74 size_t& read, 75 int& error) = 0; 76 virtual StreamResult Write(rtc::ArrayView<const uint8_t> data, 77 size_t& written, 78 int& error) = 0; 79 80 // Attempt to transition to the SS_CLOSED state. SE_CLOSE will not be 81 // signalled as a result of this call. 82 virtual void Close() = 0; 83 84 // Streams may signal one or more StreamEvents to indicate state changes. 85 // The first argument identifies the stream on which the state change occured. 86 // The second argument is a bit-wise combination of StreamEvents. 87 // If SE_CLOSE is signalled, then the third argument is the associated error 88 // code. Otherwise, the value is undefined. 89 // Note: Not all streams will support asynchronous event signalling. However, 90 // SS_OPENING and SR_BLOCK returned from stream member functions imply that 91 // certain events will be raised in the future. 92 sigslot::signal3<StreamInterface*, int, int> SignalEvent; 93 94 // Return true if flush is successful. 95 virtual bool Flush(); 96 97 // 98 // CONVENIENCE METHODS 99 // 100 // These methods are implemented in terms of other methods, for convenience. 101 // 102 103 // WriteAll is a helper function which repeatedly calls Write until all the 104 // data is written, or something other than SR_SUCCESS is returned. Note that 105 // unlike Write, the argument 'written' is always set, and may be non-zero 106 // on results other than SR_SUCCESS. The remaining arguments have the 107 // same semantics as Write. 108 [[deprecated("Use version with ArrayView")]] StreamResult 109 WriteAll(const void* data, size_t data_len, size_t* written, int* error); 110 111 #pragma clang diagnostic push 112 #pragma clang diagnostic ignored "-Wdeprecated-declarations" 113 // TODO(bugs.webrc.org/14632): Remove pragmas and change underlying 114 // implementation when downstream code is converted. WriteAll(ArrayView<const uint8_t> data,size_t & written,int & error)115 StreamResult WriteAll(ArrayView<const uint8_t> data, 116 size_t& written, 117 int& error) { 118 return WriteAll(data.data(), data.size(), &written, &error); 119 } 120 #pragma clang diagnostic pop 121 122 protected: 123 StreamInterface(); 124 }; 125 126 } // namespace rtc 127 128 #endif // RTC_BASE_STREAM_H_ 129