转载说明:
yate中所有基于流操作的基类:
/**
* Base class for encapsulating system dependent stream capable objects
* 封装能够基于系统的流对象的基类
* @short An abstract stream class capable of reading and writing
* @short 能够读和写的抽象类
*/
class YATE_API Stream
{
public:
/**
* Enumerate seek start position
* 开寻找位置的枚举
*/
enum SeekPos {
SeekBegin, // Seek from start of stream
SeekEnd, // Seek from stream end
SeekCurrent // Seek from current position
};
/**
* Destructor, terminates the stream
* 析构函数,结束流
*/
virtual ~Stream();
/**
* Get the error code of the last operation on this stream
* 获取最近操作这个流的错误码
* @return Error code generated by the last operation on this stream
* @返回最近操作这个流产生的错误码
*/
inline int error() const
{ return m_error; }
/**
* Closes the stream
* 关闭这个流
* @return True if the stream was (already) closed, false if an error occured
* @返回true,如果流被关闭了(已经被关闭了),false,发生了错误
*/
virtual bool terminate() = 0;
/**
* Check if the last error code indicates a retryable condition
* 检查最近的错误码,表明一个可重操作的条件
* @return True if error was temporary and operation should be retried
* @返回true,如果错误是临时的并且可重新操作的
*/
virtual bool canRetry() const;
/**
* Check if the last error code indicates a non blocking operation in progress
* 核查最近的错误码,表明一个正在进行的非阻塞操作
* @return True if a non blocking operation is in progress
* @返回true,如果正在进行一个非阻塞的操作
*/
virtual bool inProgress() const;
/**
* Check if this stream is valid
* 检查该流是否为有效的
* @return True if the stream is valid, false if it's invalid or closed
* @返回为true,如果该流有效,false,该流无效或者已经关闭
*/
virtual bool valid() const = 0;
/**
* Set the blocking or non-blocking operation mode of the stream
* 设置该流阻塞或者非阻塞模式
* @param block True if I/O operations should block, false for non-blocking
* @参数blcok,为true,如果I/O操作是阻塞,false,非阻塞
* @return True if operation was successfull, false if an error occured
* @返回true, 如果操作成功, false,发生了错误
*/
virtual bool setBlocking(bool block = true);
/**
* Write data to a connected stream
* 写数据到一个已经连接的流
* @param buffer Buffer for data transfer
* @参数buffer,数据传输的缓冲区
* @param length Length of the buffer
* @参数length,缓冲区的长度
* @return Number of bytes transferred, negative if an error occurred
* @返回已经传输的字节,负数,发生了错误
*/
virtual int writeData(const void* buffer, int length) = 0;
/**
* Write a C string to a connected stream
* 写入一个C的字符串到已经连接的流
* @param str String to send over the stream
* @参数str,要发送的字符串
* @return Number of bytes transferred, negative if an error occurred
* @返回已经传输的字节,负数,发生了错误
*/
int writeData(const char* str);
/**
* Write a String to a connected stream
* 写字符串到一个已经连接的流
* @param str String to send over the stream
* @参数str,要发送的字符串
* @return Number of bytes transferred, negative if an error occurred
* @返回已经传输的字节,负数,发生了错误
*/
inline int writeData(const String& str)
{ return writeData(str.c_str(), str.length()); }
/**
* Write a Data block to a connected stream
* 写数据块到一个已经连接的流
* @param buf DataBlock to send over the stream
* @参数buf,要发送的数据块
* @return Number of bytes transferred, negative if an error occurred
* @返回已经传输的字节,负数,发生了错误
*/
inline int writeData(const DataBlock& buf)
{ return writeData(buf.data(), buf.length()); }
/**
* Receive data from a connected stream
* 从一个连接的流中接收数据
* @param buffer Buffer for data transfer
* @参数buffer,数据传输的缓冲区
* @param length Length of the buffer
* @参数length,缓冲区的长度
* @return Number of bytes transferred, negative if an error occurred
* @返回已经传输的字节,负数,发生了错误
*/
virtual int readData(void* buffer, int length) = 0;
/**
* Find the length of the stream if it has one
* 如果流存在,找到该流的长度
* @return Length of the stream or zero if length is not defined
* @返回该流的长度,为 0 如果该流的长度没有定义
*/
virtual int64_t length();
/**
* Set the stream read/write pointer
* 设置该流的读/写指针
* @param pos The seek start as enumeration
* @参数pos,enumeration 中开始跳转的地址
* @param offset The number of bytes to move the pointer from starting position
* @参数offset, 从开始地址移动的指针的字节数
* @return The new position of the stream read/write pointer. Negative on failure
* @返回读/写指针的新位置,负数为失败
*/
virtual int64_t seek(SeekPos pos, int64_t offset = 0);
/**
* Set the read/write pointer from begin of stream
* 设置该流的读/写指针从流开始的位置
* @param offset The position in stream to move the pointer
* @参数offset, 从开始地址移动的指针的字节数
* @return The new position of the stream read/write pointer. Negative on failure
* @返回读/写指针的新位置,负数为失败
*/
inline int64_t seek(int64_t offset)
{ return seek(SeekBegin,offset); }
/**
* Allocate a new pair of unidirectionally pipe connected streams
* 分配流一对新的单向的管道
* @param reader Reference of a pointer receiving the newly allocated reading side of the pipe
* @参数reader,读取的指针
* @param writer Reference of a pointer receiving the newly allocated writing side of the pipe
* @参数writer,写入的指针
* @return True is the stream pipe was created successfully
* @返回true,流管道创建成功
*/
static bool allocPipe(Stream*& reader, Stream*& writer);
/**
* Allocate a new pair of bidirectionally connected streams
* 分配流一对新的双向
* @param str1 Reference of a pointer receiving the newly allocated 1st end of the pair
* @参数str1,第头端的接收引用指针
* @param str2 Reference of a pointer receiving the newly allocated 2nd end of the pair
* @参数str2,第尾端的接收引用指针
* @return True is the stream pair was created successfully
* @返回true,流创建成功
*/
static bool allocPair(Stream*& str1, Stream*& str2);
/**
* Check if operating system supports unidirectional stream pairs
* 检查操作系统是否支持单向的流
* @return True if unidirectional pipes can be created
* @返回true,如果单向管道被创建
*/
static bool supportsPipes();
/**
* Check if operating system supports bidirectional stream pairs
* 检查操作系统是否支持双向的流
* @return True if bidirectional pairs can be created
*/
static bool supportsPairs();
protected:
/**
* Default constructor
* 默认的构造函数
*/
inline Stream()
: m_error(0)
{ }
/**
* Clear the last error code
* 清除最后的错误码
*/
inline void clearError()
{ m_error = 0; }
int m_error;
};