yate学习--yateclass.h--class YATE_API Stream

/**
 * 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;
};