A pure virtual wrapper class for asynchronous reading and writing to data streams. This class is intended to be overridden for specific stream types (such as file streams, memory streams, and tunnel session streams). The class sends state events when the stream is ready for reading or writing. The methods shown are not thread-safe, and can be called on any thread.
libjingle provides the following extensions to this class:
|FileStream||Used to read and write to a local file. It does not support notifications.|
|MemoryStream||Used to transfer in-memory data.|
|NullStream||A dummy stream that does not write or read any data. Used when some kind of stream pointer is needed, but the output/input data isn't used.|
|StringStream||Reads from/writes to a std::string.|
|TarStream||Reads from/writes to a tar-encoded set of files or directories. Used by the file share example.|
class StreamInterface : public sigslot::has_slots<>
|virtual void Close() = 0||Closes the stream. This will not send an SE_CLOSE error, because it is a deliberate action.|
|virtual bool GetSize(size_t *size) const = 0||Retrieves the number of bytes to be read, if known. Returns True if this value can be returned, False otherwise. Not supported by TunnelStream.|
|virtual StreamState GetState() = 0||A StreamState value describing the state of the stream. This is the same value sent by the stream's SignalEvent signal. Note that this does not return the current read/write state of the stream; read/write state is only sent by the SignalEvent signal.|
|virtual StreamResult Read(void *buffer, size_t buffer_len, size_t *read, int *error)=0||
Reads a specified number of bytes from the stream. Does not return the number of bytes read if any error occurs.
|StreamResult ReadAll(void *buffer, size_t buffer_len, size_t *read, int *error)||
Calls Read repeatedly until an error is retrieved or buffer is filled . Returns the number of bytes read whether or not an error occurred.
|StreamResult ReadLine(std::string *line)||Reads data until a \n is encountered or the whole buffer is read.|
|virtual bool ReserveSize(size_t size) = 0;||Specifies how much data will be written to a stream. Enables a class to preallocate memory more efficiently.|
|virtual bool Rewind() = 0||Resets the current read/write position to the start of the stream. Returns True if successful, False otherwise. Not supported by TunnelStream.|
Constructor. Takes no arguments. You should never call the constructor since this is a pure virtual class.
|virtual StreamResult Write(const void *data, size_t data_len, size_t *written, int *error)=0||
Writes a specified number of bytes to the stream. Does not return the number of bytes written if any error occurs.
|StreamResult WriteAll(const void *data, size_t data_len, size_t *written, int *error)||Calls Write repeatedly until an error occurs, or all the data in data is written. Returns the number of bytes written whether or not an error occurred. Parameters are the same as for Write.|
- SignalEvent sigslot::signal3<StreamInterface* stream, int event, int err>
Sent whenever an event occurs on the stream. Note that although event might indicate that the stream is readable or writable, this is not a guarantee. If you attempt to read to or write from a stream marked as SE_READ or SE_WRITE, it might still fail with SR_BLOCK. However, if it does fail, wait for SignalEvent to send SE_OPEN and try again. Once a stream sends SE_CLOSE, the application should close it by calling Close. A stream that sends SE_CLOSE will not become active again.
- stream is the stream sending this event.
- event is a bitwise combination of StreamEvent values that indicate the new state of the stream.
- err If event is SE_CLOSE, then err is an error associated with the event; otherwise, err is undefined. Error messages bubble up from several different places; the most common error messages are ECONNABORTED and ECONNRESET, defined in socket.h.
Declaration file: talk/base/stream.h