#ifndef	ACL_VSTREAM_INCLUDE_H
#define	ACL_VSTREAM_INCLUDE_H

#ifdef  __cplusplus
extern "C" {
#endif

#include "acl_define.h"
#include <time.h>
#include <sys/types.h>

#ifdef	ACL_UNIX
#include <sys/time.h>
#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h>
#include <netinet/in.h>
#endif

#include "acl_array.h"
#include "acl_htable.h"
#include "acl_vstring.h"

#define	ACL_VSTREAM_EOF		(-1)		/* no more space or data */

#ifdef	ACL_UNIX
# ifndef	O_RDONLY
#  define	O_RDONLY	0
# endif
# ifndef	O_WRONLY
#  define	O_WRONLY	1
# endif
# ifndef	O_RDWR
#  define	O_RDWR		2
# endif
#endif

#define	ACL_VSTREAM_BUFSIZE	4096

typedef struct ACL_VSTREAM	ACL_VSTREAM;

typedef int (*ACL_VSTREAM_RD_FN)(ACL_SOCKET fd, void *buf, size_t size,
	int timeout, ACL_VSTREAM *fp, void *context);
typedef int (*ACL_VSTREAM_WR_FN)(ACL_SOCKET fd, const void *buf,
	size_t size, int timeout, ACL_VSTREAM *fp, void *context);
typedef int (*ACL_VSTREAM_WV_FN)(ACL_SOCKET fd, const struct iovec *vec,
	int count, int timeout, ACL_VSTREAM *fp, void *context);
typedef int (*ACL_FSTREAM_RD_FN)(ACL_FILE_HANDLE fh, void *buf, size_t size,
	int timeout, ACL_VSTREAM *fp, void *context);
typedef int (*ACL_FSTREAM_WR_FN)(ACL_FILE_HANDLE fh, const void *buf,
	size_t size, int timeout, ACL_VSTREAM *fp, void *context);
typedef int (*ACL_FSTREAM_WV_FN)(ACL_FILE_HANDLE fh, const struct iovec *vec,
	int count, int timeout, ACL_VSTREAM *fp, void *context);

/* 当关闭或释放一个数据流时, 需要回调一些释放函数, 此结果定义了该回调
 * 函数的句柄类型 ---add by zsx, 2006.6.20
 */
typedef struct ACL_VSTREAM_CLOSE_HANDLE {
	void (*close_fn)(ACL_VSTREAM*, void*);
	void *context;
} ACL_VSTREAM_CLOSE_HANDLE;

/* 数据读写流类型定义 */
struct ACL_VSTREAM {
	union {
		ACL_SOCKET      sock;   /**< the master socket */
		ACL_FILE_HANDLE h_file; /**< the file handle */
	} fd;

	int   is_nonblock;              /**< just for WINDOWS, because the ioctlsocket is too weak */
	int   type;                     /**< defined as: ACL_VSTREAM_TYPE_XXX */
#define	ACL_VSTREAM_TYPE_SOCK           (1 << 0)
#define	ACL_VSTREAM_TYPE_FILE           (1 << 1)
#define	ACL_VSTREAM_TYPE_LISTEN		(1 << 2)
#define	ACL_VSTREAM_TYPE_LISTEN_INET    (1 << 3)
#define	ACL_VSTREAM_TYPE_LISTEN_UNIX    (1 << 4)
#define ACL_VSTREAM_TYPE_LISTEN_IOCP    (1 << 5)

	acl_off_t offset;               /**< cached seek info */
	acl_off_t sys_offset;           /**< cached seek info */

	unsigned char *wbuf;            /**< used when call acl_vstream_buffed_writen */
	int   wbuf_size;                /**< used when call acl_vstream_buffed_writen */
	int   wbuf_dlen;                /**< used when call acl_vstream_buffed_writen */

	unsigned char *read_buf;        /**< read buff */
	int   read_buf_len;             /**< read_buf's capacity */
	int   read_cnt;                 /**< data's length in read_buf */
	unsigned char *read_ptr;        /**< pointer to next position in read_buf */
	int   sys_read_ready;           /**< if the system buffer has some data */

	acl_off_t total_read_cnt;       /**< total read count of the fp */
	acl_off_t total_write_cnt;      /**< total write count of the fp */

	void *ioctl_read_ctx;           /**< only for acl_ioctl_xxx in acl_ioctl.c */
	void *ioctl_write_ctx;          /**< only for acl_ioctl_xxx in acl_ioctl.c */
	void *fdp;                      /**< only for event */

	unsigned int flag;              /**< defined as: ACL_VSTREAM_FLAG_XXX */
#define	ACL_VSTREAM_FLAG_READ           (1 << 0)
#define	ACL_VSTREAM_FLAG_WRITE          (1 << 1)
#define	ACL_VSTREAM_FLAG_RW             (1 << 2)
#define ACL_VSTREAM_FLAG_CACHE_SEEK     (1 << 3)
#define	ACL_VSTREAM_FLAG_DEFER_FREE	(1 << 4)	/**< 延迟关闭 */

#define	ACL_VSTREAM_FLAG_ERR            (1 << 10)	/**< 其它错误 */
#define	ACL_VSTREAM_FLAG_EOF            (1 << 11)	/**< 结束 */
#define	ACL_VSTREAM_FLAG_TIMEOUT        (1 << 12)	/**< 超时 */
#define	ACL_VSTREAM_FLAG_RDSHORT        (1 << 13)	/**< 读的不够 */
#define ACL_VSTREAM_FLAG_BAD  (ACL_VSTREAM_FLAG_ERR \
                               | ACL_VSTREAM_FLAG_EOF \
                               | ACL_VSTREAM_FLAG_TIMEOUT)
#define	ACL_VSTREAM_FLAG_CLIENT         (1 << 14)
#define	ACL_VSTREAM_FLAG_CONNECT        (1 << 15)
#define	ACL_VSTREAM_FLAG_SOCKPAIR       (1 << 16)

#define	ACL_VSTREAM_FLAG_TAGYES	        (1 << 17) /* 若读到要求的标志位的要求则置位 */
#define	ACL_VSTREAM_FLAG_TAGNO          (1 << 18) /* 没有找到标志位 */

#define	ACL_VSTREAM_FLAG_CONNECTING     (1 << 19) /* 正在连接过程中 */
#define	ACL_VSTREAM_FLAG_PREREAD	(1 << 20) /* 对于 acl_vstream_can_read 调用过程是否允许预读 */

	char  errbuf[128];              /**< error info */
	int   errnum;                   /**< record the system errno here */
	int   rw_timeout;               /**< read/write timeout */
	char *addr_local;               /**< the local addr of the fp */
	char *addr_peer;                /**< the peer addr of the fp */
	struct sockaddr_in *sa_local;
	struct sockaddr_in *sa_peer;
	size_t sa_local_size;
	size_t sa_peer_size;
	size_t sa_local_len;
	size_t sa_peer_len;
	char *path;                     /**< the path just for file operation */
	void *context;                  /**< the application's special data */

	ACL_ARRAY *close_handle_lnk;    /**< before this fp is free,
	                                 * function in close_handle_lnk
	                                 * will be called.
	                                 * add by zsx, 2006.6.20
	                                 */
	int (*sys_getc)(ACL_VSTREAM*);  /**< called by ACL_VSTREAM_GETC()/1 */
	ACL_VSTREAM_RD_FN read_fn;      /**< system socket read API */
	ACL_VSTREAM_WR_FN write_fn;     /**< system socket write API */
	ACL_VSTREAM_WV_FN writev_fn;    /**< system socket writev API */

	ACL_FSTREAM_RD_FN fread_fn;     /**< system file read API */
	ACL_FSTREAM_WR_FN fwrite_fn;    /**< system file write API */
	ACL_FSTREAM_WV_FN fwritev_fn;   /**< system file writev API */

	int (*close_fn)(ACL_SOCKET);    /**< system socket close API */
	int (*fclose_fn)(ACL_FILE_HANDLE);  /**< system file close API */

	unsigned int oflags;            /**< the system's open flags */
	/* general flags(ANSI):
	 * O_RDONLY: 0x0000, O_WRONLY: 0x0001, O_RDWR: 0x0002, O_APPEND: 0x0008,
	 * O_CREAT: 0x0100, O_TRUNC: 0x0200, O_EXCL: 0x0400;
	 * just for win32:
	 * O_TEXT: 0x4000, O_BINARY: 0x8000, O_RAW: O_BINARY,
	 * O_SEQUENTIAL: 0x0020, O_RANDOM: 0x0010.
	 */

	int   nrefer;                   /**< refer count, used for engine moudle */

#ifdef WIN32
	int   pid;
	HANDLE hproc;
	ACL_SOCKET iocp_sock;
#elif defined(ACL_UNIX)
	pid_t pid;
#endif
	ACL_HTABLE *objs_table;
};

extern ACL_API ACL_VSTREAM acl_vstream_fstd[];  /**< pre-defined streams */
#define ACL_VSTREAM_IN          (&acl_vstream_fstd[0]) /**< 标准输入 */
#define ACL_VSTREAM_OUT         (&acl_vstream_fstd[1]) /**< 标准输出 */
#define ACL_VSTREAM_ERR         (&acl_vstream_fstd[2]) /**< 标准错误输出 */

/*--------------------------------------------------------------------------*/
/**
 * 初始化ACL_VSTREAM流的函数库
 * 对于WIN32来说，如果想要用标准输入输出，则需要调用此函数进行初始化
 */
ACL_API void acl_vstream_init(void);

/**
 * 功能: 探测流中有多少数据, 包含缓冲区中的数据与系统缓冲区的数据
 * @param fp {ACL_VSTREAM*} 流指针, 不能为空
 * @return ret {int}, ret > 0 OK; ret <= 0 Error
 * 注: 仅适应于网络套接字
 */
ACL_API int acl_vstream_peekfd(ACL_VSTREAM *fp);

/**
 * 克隆一个ACL_VSTREAM流，除ioctl_read_ctx, ioctl_write_ctx, fdp
 * 外所有数据都拷贝，如果是动态内存数据，则新的流将在内部动态分配
 * 内存且将源数据进行拷贝
 * @param stream_src {ACL_VSTREAM*} 源流指针
 * @return {ACL_VSTREAM*} 目的流指针
 */
ACL_API ACL_VSTREAM *acl_vstream_clone(const ACL_VSTREAM *stream_src);

/**
 * 设置数据流的类型，该函数将根据所给类型设定用于该数据流上的读、写、关闭函数
 * @param fp {ACL_VSTREAM*} 流指针, 不能为空
 * @param type {int} 数据流的类型，defined above: ACL_VSTREAM_TYPE_XXX
 * @return ret {int}, ret >= 0 OK; ret < 0 Error
 */
ACL_API int acl_vstream_set_fdtype(ACL_VSTREAM *fp, int type);

/**
 * 分配一文件句柄所对应的数据流
 * @param fh {ACL_FILE_HANDLE} 文件句柄
 * @param oflags {unsigned int} 标志位, We're assuming that O_RDONLY: 0x0000,
 *  O_WRONLY: 0x0001, O_RDWR: 0x0002, O_APPEND: 0x0008, O_CREAT: 0x0100,
 *  O_TRUNC: 0x0200, O_EXCL: 0x0400; just for win32, O_TEXT: 0x4000,
 *  O_BINARY: 0x8000, O_RAW: O_BINARY, O_SEQUENTIAL: 0x0020, O_RANDOM: 0x0010.
 *  同时设置
 * @return {ACL_VSTREAM*} 数据流句柄
 */
ACL_API ACL_VSTREAM *acl_vstream_fhopen(ACL_FILE_HANDLE fh, unsigned int oflags);

/**
 * 分配一个数据流
 * @param fd {ACL_SOCKET} 描述符(可以为网络描述字也可以为文件描述字)
 * @param oflags {unsigned int} 标志位, We're assuming that O_RDONLY: 0x0000,
 *  O_WRONLY: 0x0001, O_RDWR: 0x0002, O_APPEND: 0x0008, O_CREAT: 0x0100,
 *  O_TRUNC: 0x0200, O_EXCL: 0x0400; just for win32, O_TEXT: 0x4000,
 *  O_BINARY: 0x8000, O_RAW: O_BINARY, O_SEQUENTIAL: 0x0020, O_RANDOM: 0x0010.
 * @param buflen {size_t} 内置缓冲区的大小
 * @param rw_timeo {int} 读写超时时间(以秒为单位)
 * @param fdtype {int} ACL_VSTREAM_TYPE_FILE, ACL_VSTREAM_TYPE_SOCK,
 *  ACL_VSTREAM_TYPE_LISTEN | ACL_VSTREAM_TYPE_LISTEN_INET | ACL_VSTREAM_TYPE_LISTEN_UNIX
 * @return ret {ACL_VSTREAM*}, ret == NULL: 出错, ret != NULL: OK
 */
ACL_API ACL_VSTREAM *acl_vstream_fdopen(ACL_SOCKET fd, unsigned int oflags,
		size_t buflen, int rw_timeo, int fdtype);

/**
 * 打开一个文件的数据流
 * @param path {const char*} 文件名
 * @param oflags {unsigned int} 标志位, We're assuming that O_RDONLY: 0x0000,
 *  O_WRONLY: 0x0001, O_RDWR: 0x0002, O_APPEND: 0x0008, O_CREAT: 0x0100,
 *  O_TRUNC: 0x0200, O_EXCL: 0x0400; just for win32, O_TEXT: 0x4000,
 *  O_BINARY: 0x8000, O_RAW: O_BINARY, O_SEQUENTIAL: 0x0020, O_RANDOM: 0x0010.
 * @param mode {int} 打开文件句柄时的模式(如: 0600)
 * @param buflen {size_t} 内置缓冲区的大小
 * @return ret {ACL_VSTREAM*}, ret== NULL: 出错, ret != NULL: OK
 */
ACL_API ACL_VSTREAM *acl_vstream_fopen(const char *path, unsigned int oflags,
		int mode, size_t buflen);

/**
 * 读取整个文件内容于内存中
 * @param path {const char*} 文件名, 如: /opt/acl/conf/service/test.cf
 * @return {char*} 存有文件全部内容的缓冲区, 用完后用户需要调用 acl_myfree
 *  释放该内存区
 */
ACL_API char *acl_vstream_loadfile(const char *path);

/**
 * 读取整个文件内容于内存中
 * @param path {const char*} 文件名, 如: /opt/acl/conf/service/test.cf
 * @param size {ssize_t*} 如果非空，则该值存储返回的缓冲区大小，如果读取内容
 *  出错，则该值会被置 -1
 * @return {char*} 存有文件全部内容的缓冲区, 用完后用户需要调用 acl_myfree
 *  释放该内存区
 */
ACL_API char *acl_vstream_loadfile2(const char *path, ssize_t *size);

/**
 * 设置流的各个参数
 * @param fp {ACL_VSTREAM*} 流指针
 * @param name {int} 所设置的参数类型中的第一个参数类型名,
 *  defined as ACL_VSTREAM_CTL_
 */
ACL_API void acl_vstream_ctl(ACL_VSTREAM *fp, int name,...);
#define ACL_VSTREAM_CTL_END         0
#define ACL_VSTREAM_CTL_READ_FN     1
#define ACL_VSTREAM_CTL_WRITE_FN    2
#define ACL_VSTREAM_CTL_PATH        3
#define ACL_VSTREAM_CTL_FD          4
#define ACL_VSTREAM_CTL_TIMEOUT     5
#define ACL_VSTREAM_CTL_CONTEXT     6
#define	ACL_VSTREAM_CTL_CTX         ACL_VSTREAM_CTL_CONTEXT
#define ACL_VSTREAM_CTL_CACHE_SEEK  7

/**
 * 定位文件指针
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @param offset {acl_off_t} 偏移量
 * @param whence {int} 偏移方向, SEEK_SET, SEEK_CUR, SEEK_END
 * @return ret {acl_off_t}, ret >= 0: 正确, ret < 0: 出错
 * 注： acl_vstream_fseek() 效率更高些, 其充分利用了缓冲区的功能,
 *      且比 acl_vstream_fseek2() 少调用一次 lseek() 系统调用.
 */
ACL_API acl_off_t acl_vstream_fseek(ACL_VSTREAM *fp, acl_off_t offset, int whence);

/**
 * 定位文件指针
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @param offset {acl_off_t} 偏移量
 * @param whence {int} 移动方向：SEEK_SET（从文件起始位置后移动）,
 *  SEEK_CUR（从当前文件指针位置向后移动）, SEEK_END（从文件尾向前移动）
 * @return ret {acl_off_t}, ret >= 0: 正确, ret < 0: 出错
 * @deprecated 该函数的效率较低
 */
ACL_API acl_off_t acl_vstream_fseek2(ACL_VSTREAM *fp, acl_off_t offset, int whence);

/**
 * 返回当前文件指针所在位置
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @return {acl_off_t} 当前文件指针所在位置, -1 表示出错
 */
ACL_API acl_off_t acl_vstream_ftell(ACL_VSTREAM *fp);

/**
 * 将源文件进程截断
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @param length {acl_off_t} 数据长度(>=0)
 * @return {int} 0: ok, -1: error
 */
ACL_API int acl_file_ftruncate(ACL_VSTREAM *fp, acl_off_t length);

/**
 * 将源文件进程截断
 * @param path {const char*} 文件名(可以是全路径或相对路径)
 * @param length {acl_off_t} 数据长度(>=0)
 * @return {int} 0: ok, -1: error
 */
ACL_API int acl_file_truncate(const char *path, acl_off_t length);

/**
 * 查看一个文件流句柄的属性
 * @param fp {ACL_VSTREAM *} 文件流句柄
 * @param buf {acl_stat *} 存储结果的结构地址
 * @return {int} 0: ok; -1: error
 */
ACL_API int acl_vstream_fstat(ACL_VSTREAM *fp, struct acl_stat *buf);

/**
 * 查看一个文件的大小
 * @param fp {ACL_VSTREAM *} 文件流句柄
 * @return {int} >= 0: ok;  -1: error
 */
ACL_API acl_int64 acl_vstream_fsize(ACL_VSTREAM *fp);

/**
 * 从fp 流中读取一个字节
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @return {int} ACL_VSTREAM_EOF(出错) 或所读到的某个字节的ASCII
 *  或为 ACL_VSTREAM_EOF: 读出错或对方关闭了连接, 应该关闭该数据流
 */
ACL_API int acl_vstream_getc(ACL_VSTREAM *fp);
#define	acl_vstream_get_char	acl_vstream_getc

/**
 * 从 fp 流中非阻塞地一次性最大读取 size 个字节
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @param buf {char*} 用户传来的内存缓存区
 * @param size {int} buf 缓存区的空间大小
 * @return {int} 所读取的字节数 n, 如果 n == ACL_VSTREAM_EOF 表明出错, 否则
 *         n >= 0 正确.
 */
ACL_API int acl_vstream_nonb_readn(ACL_VSTREAM *fp, char *buf, int size);

/**
 * 判断一个给定的数据流是否已经被系统关闭了，当数据流缓存区没有数据时，
 * 该函数会调用系统的读函数（即读一个字节）来判断是否socket出错或已经
 * 关闭；如成功读取一个字节，则说明socket正常，同时将所读的数据放回缓存
 * 区, 如果读返回ACL_VSTREAM_EOF, 便需要判断错误号是否被关闭
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @return {int}, 0 说明该socket正常; -1 该socket出错或已经被系统关闭
 */
ACL_API int acl_vstream_probe_status(ACL_VSTREAM *fp);

/**
 * 将一个字符放回数据流中
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @param ch {int} 字符的 ASCII 码 
 * @return {int} 字符的 ASCII 码, 该函数应不会出错, 除非内部内存分配失败而产生
 *  core 文件.
 */
ACL_API int acl_vstream_ungetc(ACL_VSTREAM *fp, int ch);

/**
 * 将指定长度的数据放回至数据流中
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @param ptr {const void *} 需要放回至流中的数据的起始地址
 * @param length {size_t} 需要放回至流中的数据的长度
 * @return {int} 被成功放回至流中的数据长度, 应该永不会出错, 除非内部内存分配
 *  失败而自动产生 core 文件!
 */
ACL_API int acl_vstream_unread(ACL_VSTREAM *fp, const void *ptr, size_t length);

/**
 * 从数据流中读取一行数据, 直到读到  "\n" 或读结束为止, 正常情况下包括 "\n"
 * @param fp {ACL_VSTREAM*} 数据流
 * @param vptr {void*} 用户所给的内存缓冲区指针
 * @param maxlen {size_t} vptr 缓冲区的大小
 * @return  ret {int}, ret == ACL_VSTREAM_EOF:  读出错或对方关闭了连接, 
 *  应该关闭本地数据流; n > 0:  读到 了 n 个字节的数据, 如果该 n 个数据
 *  的最后一个非 0 字符为 "\n" 表明读到了一个完整的行, 否则表明读到了 n
 *  个数据但对方未发送 "\n" 就关闭了连接; 还可以通过检查
 *  (fp->flag & ACL_VSTREAM_FLAG_TAGYES)
 *	不等于 0 来判断是否读到了 "\n", 如果非 0 则表示读到了 "\n".
 */
ACL_API int acl_vstream_gets(ACL_VSTREAM *fp, void *vptr, size_t maxlen);
#define	acl_vstream_readline	acl_vstream_gets
#define	acl_vstream_fgets	acl_vstream_gets

/**
 * 从数据流中读取一行数据, 直到读到 "\n" 或读结束为止, 返回的结果中不包括 "\n"
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param vptr {void*} 用户所给的内存缓冲区指针
 * @param maxlen {size_t} vptr 缓冲区的大小
 * @return ret {int}, ret == ACL_VSTREAM_EOF:  读出错或对方关闭了连接,
 *  应该关闭本地数据流, n == 0: 读到了一行数据, 但该行数据仅有 "\r\n",
 *  n > 0:  读到 了 n 个字节的数据.
 */
ACL_API int acl_vstream_gets_nonl(ACL_VSTREAM *fp, void *vptr, size_t maxlen);

/**
 * 从数据流中获得以字符串为标志结束位的内容
 * @param fp {ACL_VSTREAM*} 类型指针
 * @param vptr {void*} 数据存储缓冲区
 * @param maxlen {size_t} vptr 缓冲区大小
 * @param tag {const char*} 字符串标志
 * @param taglen {size_t} tag 中内容的长度大小
 * @return ret {int}, ret == ACL_VSTREAM_EOF:  读出错或对方关闭了连接, 
 *  应该关闭本地数据流, n > 0:  读到 了 n 个字节的数据, 如果读到了所需要的
 *  标志串, 则 fp 流中 (fp->flag & ACL_VSTREAM_FLAG_TAGYES) 不等于 0.
 */
ACL_API int acl_vstream_readtags(ACL_VSTREAM *fp, void *vptr, size_t maxlen,
		const char *tag, size_t taglen);

/**
 * 循环读取 maxlen 个数据, 直到读到 maxlen 个字节为止或读出错
 * @param fp {ACL_VSTREAM*} 数据流
 * @param vptr {void*} 用户的数据缓冲区指针地址
 * @param maxlen {size_t} vptr 数据缓冲区的空间大小
 * @return ret {int}, ret == ACL_VSTREAM_EOF:  读出错或对方关闭了连接, 应该
 *  关闭本地数据流 n > 0:  成功读取了 maxlen 个字节的数据
 *  如果实际读取的字节数与 maxlen 不相等也返回错误(ACL_VSTREAM_EOF)
 */
ACL_API int acl_vstream_readn(ACL_VSTREAM *fp, void *vptr, size_t maxlen);

/**
 * 将 fp 缓冲区内的数据拷贝到 vptr 中
 * @param fp {ACL_VSTREAM*} 数据流
 * @param vptr {void*} 用户的数据缓冲区指针地址
 * @param maxlen {size_t} vptr 数据缓冲区的空间大小
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示出错, 应该关闭本地数据流,
 *  ret >= 0: 成功从 fp 数据流的缓冲区中读取了 ret 个字节的数据
 */
ACL_API int acl_vstream_bfcp_some(ACL_VSTREAM *fp, void *vptr, size_t maxlen);

/**
 * 从数据流中一次性读取 n 个数据, 该 n 有可能会小于用户所需要的 maxlen
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param vptr {void*} 用户的数据缓冲区指针地址
 * @param maxlen {size_t} vptr 数据缓冲区的空间大小
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示出错, 应该关闭本地数据流,
 *  ret > 0:  表示读到了 ret 个字节的数据
 *  注: 如果缓冲区内有数据, 则直接把缓冲区内的数据复制到用户的缓冲区然后直接返回;
 *     如果缓冲区内无数据, 则需要调用系统读操作(有可能会阻塞在系统读操作上), 该
 *     次调用返回后则把读到数据复制到用户缓冲区返回.
 *     在这两种情况下都不能保证读到的字节数等于所要求的字节数, 若想读到所要求的
 *     字节后才返回则请调用 vstream_loop_readn() 函数.
 */
ACL_API int acl_vstream_read(ACL_VSTREAM *fp, void *vptr, size_t maxlen);

/**
 * 一次性从 ACL_VSTREAM 流或系统缓存区中读取一行数据, 包括回车换行符
 * (调用者自行解决WINDOWS与UNIX对于回车换行的兼容性问题), 如果未读到
 * 回车换行符, 也将数据拷贝至用户的内存缓冲区.
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param buf {ACL_VSTRING*} 数据缓冲区，当 buf->maxlen > 0 时，则限制每行数据
 *  的长度，即当 buf 中的数据长度达到 maxlen 时，即使没有读到完整一行数据，该
 *  函数也会返回，且会将 ready 置 1，调用者需调用 fp->flag 标志位中是否包含
 *  ACL_VSTREAM_FLAG_TAGYES 来判断是否读到一行数据
 * @param ready {int*} 是否按要求读到所需数据的标志位指针, 不能为空
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示出错, 应该关闭本地数据流,
 *  ret >= 0: 成功从 fp 数据流的缓冲区中读取了 ret 个字节的数据
 */
ACL_API int acl_vstream_gets_peek(ACL_VSTREAM *fp, ACL_VSTRING *buf, int *ready);

/**
 * 一次性从 ACL_VSTREAM 流或系统缓存区中读取一行数据, 如果未读到回车换行符,
 * 也将数据拷贝至用户的内存缓冲区, 如果读到回车换行符便将回车换行符自动去掉,
 * 并将回车换行符前的数据拷贝至用户内存区.
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param buf {ACL_VSTRING*} 数据缓冲区，当 buf->maxlen > 0 时，则限制每行数据
 *  的长度，即当 buf 中的数据长度达到 maxlen 时，即使没有读到完整一行数据，该
 *  函数也会返回，且会将 ready 置 1，调用者需调用 fp->flag 标志位中是否包含
 *  ACL_VSTREAM_FLAG_TAGYES 来判断是否读到一行数据
 * @param ready {int*} 是否按要求读到所需数据的标志位指针, 不能为空
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示出错, 应该关闭本地数据流,
 *  ret >= 0: 成功从 fp 数据流的缓冲区中读取了 ret 个字节的数据, 如果仅
 *  读到了一个空行, 则 ret == 0.
 */
ACL_API int acl_vstream_gets_nonl_peek(ACL_VSTREAM *fp, ACL_VSTRING *buf, int *ready);

/**
 * 一次性从 ACL_VSTREAM 流或系统缓存区中读取固定长度的数据, 如果未读到所要求的
 * 数据, 也将数据拷贝至用户内存缓冲区, 如果读到所要求的数据, 则将 ready 标志位置位.
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param buf {ACL_VSTRING*} 数据缓冲区
 * @param cnt {int} 所需要读的数据的长度
 * @param ready {int*} 是否按要求读到所需数据的标志位指针, 不能为空
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示出错, 应该关闭本地数据流,
 *  ret >= 0: 成功从 fp 数据流的缓冲区中读取了 ret 个字节的数据, 
 *  (*ready) != 0: 表示读到了所要求长度的数据.
 */
ACL_API int acl_vstream_readn_peek(ACL_VSTREAM *fp, ACL_VSTRING *buf, int cnt, int *ready);

/**
 * 一次性从 ACL_VSTREAM 流或系统缓存区中读取不固定长度的数据,
 * 只要能读到大于 0 个字节的数据则将 ready 标志位置位
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param buf {ACL_VSTRING*} 数据缓冲区
 * @return  ret {int}, ret == ACL_VSTREAM_EOF: 表示出错, 应该关闭本地数据流,
 *  ret >= 0: 成功从 fp 数据流的缓冲区中读取了 ret 个字节的数据.
 */
ACL_API int acl_vstream_read_peek(ACL_VSTREAM *fp, ACL_VSTRING *buf);

/**
 * 检查 ACL_VSTREAM 流是否可读或出错
 * @param fp {ACL_VSTREAM*} 数据流 
 * @return {int} 0: 表示无数据可读; ACL_VSTREAM_EOF 表示出错; > 0 表示有数据可读
 */
ACL_API int acl_vstream_can_read(ACL_VSTREAM *fp);

/**
 * 将文件流中的系统缓冲区及流缓冲区中的数据都直接同步至硬盘
 * @param fp {ACL_VSTREAM*} 文件流指针
 * @return {int} 0: ok; ACL_VSTREAM_EOF: error
 */
ACL_API int acl_vstream_fsync(ACL_VSTREAM *fp);

/**
 * 对于带缓冲方式的写，该函数保证缓冲区空间非空
 * @param fp {ACL_VSTREAM*} 数据流
 */
ACL_API void acl_vstream_buffed_space(ACL_VSTREAM *fp);

/**
 * 刷新写缓冲区里的数据
 * @param fp: socket 数据流
 * @return 刷新写缓冲区里的数据量或出错 ACL_VSTREAM_EOF
 */
ACL_API int acl_vstream_fflush(ACL_VSTREAM *fp);

/**
 * 带缓冲式写
 * @param fp {ACL_VSTREAM*} 数据流
 * @param vptr {const void*} 数据指针起始位置
 * @param dlen {size_t} 要写入的数据量
 * @return {int} 写入的数据量或出错 ACL_VSTREAM_EOF
 */
ACL_API int acl_vstream_buffed_writen(ACL_VSTREAM *fp, const void *vptr, size_t dlen);
#define	acl_vstream_buffed_fwrite	acl_vstream_buffed_writen

/**
 * 缓冲带格式的流输出, 类似于 vfprintf()
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param fmt {const char*} 数据格式
 * @param ap {va_list}
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示写出错, 应该关闭本地数据流,
 *  ret > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int acl_vstream_buffed_vfprintf(ACL_VSTREAM *fp, const char *fmt, va_list ap);

/**
 * 缓冲带格式的流输出, 类似于 fprintf()
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param fmt {const char*} 数据格式 
 * @param ... 变参序列
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示写出错, 应该关闭本地数据流,
 *  ret > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int ACL_PRINTF(2, 3) acl_vstream_buffed_fprintf(ACL_VSTREAM *fp,
	const char *fmt, ...);

/**
 * 向标准输出打印信息
 * @param fmt {const char*} 数据格式 
 * @param ... 变参序列
 * @return {int}, ACL_VSTREAM_EOF: 表示写出错, > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int acl_vstream_buffed_printf(const char*, ...);

/**
 * 向流缓冲区中写入一行数据
 * @param s {const char*} 源字符串
 * @param fp {ACL_VSTREAM*} 数据流
 * @return {int} 0 成功; ACL_VSTREAM_EOF 失败
 */
ACL_API int acl_vstream_buffed_fputs(const char *s, ACL_VSTREAM *fp);

/**
 * 向标准输出流缓冲区中写入一行数据
 * @param s {const char*} 源字符串
 * @return {int} 0 成功; ACL_VSTREAM_EOF 失败
 */
ACL_API int acl_vstream_buffed_puts(const char *s);

/**
* 一次性写入流操作, 返回实际写入的字节数.
* @param fp {ACL_VSTREAM*} 数据流 
* @param vptr {const void*} 数据区指针地址
* @param dlen {int} 待写的数据区数据长度
* @return ret {int}, ret == ACL_VSTREAM_EOF: 表示写出错, 应该关闭本地数据流,
*  ret > 0:  表示成功写了 ret 个字节的数据
*/
ACL_API int acl_vstream_write(ACL_VSTREAM *fp, const void *vptr, int dlen);

/**
 * 一次性写入流操作，采用 writev 模式，返回实际写入的字节数
 * @param fp {ACL_VSTREAM*}
 * @param vector {const struct iovec*}
 * @param count {int} vector 数组的长度
 * @return {int} 返回成功写入的字节数，如果出错，则返回CL_VSTREAM_EOF
 */
ACL_API int acl_vstream_writev(ACL_VSTREAM *fp, const struct iovec *vector, int count);

/**
 * 采用 writev 模式往流中写，直至全部数据写完为止或出错
 * @param fp {ACL_VSTREAM*}
 * @param vector {const struct iovec*}
 * @param count {int} vector 数组的长度
 * @return {int} 返回成功写入的字节数，如果出错，则返回CL_VSTREAM_EOF
 */
ACL_API int acl_vstream_writevn(ACL_VSTREAM *fp, const struct iovec *vector, int count);

/**
 * 带格式的流输出, 类似于 vfprintf()
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param fmt {const char*} 数据格式
 * @param ap {va_list}
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示写出错, 应该关闭本地数据流,
 *  ret > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int acl_vstream_vfprintf(ACL_VSTREAM *fp, const char *fmt, va_list ap);

/**
 * 带格式的流输出, 类似于 fprintf()
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param fmt {const char*} 数据格式 
 * @param ... 变参序列
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示写出错, 应该关闭本地数据流,
 *  ret > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int ACL_PRINTF(2, 3) acl_vstream_fprintf(ACL_VSTREAM *fp,
	const char *fmt, ...);

/**
 * 向标准输出打印信息
 * @param fmt {const char*} 数据格式 
 * @param ... 变参序列
 * @return {int}, ACL_VSTREAM_EOF: 表示写出错, > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int acl_vstream_printf(const char*, ...);

/**
 * 向流中写入一行数据
 * @param s {const char*} 源字符串
 * @param fp {ACL_VSTREAM*} 数据流
 * @return {int} 0 成功; ACL_VSTREAM_EOF 失败
 */
ACL_API int acl_vstream_fputs(const char *s, ACL_VSTREAM *fp);

/**
 * 向标准输出流中写入一行数据
 * @param s {const char*} 源字符串
 * @return {int} 0 成功; ACL_VSTREAM_EOF 失败
 */
ACL_API int acl_vstream_puts(const char *s);

/**
 * 循环向数据流中写 dlen 个字节的数据直至写完或出错为止
 * @param fp {ACL_VSTREAM*} 数据流 
 * @param vptr {const char*} 数据区指针地址
 * @param dlen {size_t} 待写的数据区数据长度
 * @return ret {int}, ret == ACL_VSTREAM_EOF: 表示写出错, 应该关闭本地数据流,
 *  ret > 0:  表示成功写了 dlen 个字节的数据
 */
ACL_API int acl_vstream_writen(ACL_VSTREAM *fp, const void *vptr, size_t dlen);
#define	acl_vstream_fwrite	acl_vstream_writen

/**
 * 释放一个数据流的内存空间, 但并不关闭 socket 描述符
 * @param fp {ACL_VSTREAM*} 数据流
 */
ACL_API void acl_vstream_free(ACL_VSTREAM *fp);

/**
 * 释放一个数据流的内存空间并关闭其所携带的 socket 描述符
 * @param fp {ACL_VSTREAM*} 数据流
 */
ACL_API int acl_vstream_close(ACL_VSTREAM *fp);
#define	acl_vstream_fclose	acl_vstream_close

/**
 * 调用数据流中的所有关闭回调函数同时清除这些回调函数
 * @param fp {ACL_VSTREAM*} 数据流
 */
ACL_API void acl_vstream_call_close_handles(ACL_VSTREAM *fp);

/**
 * 注册一个关闭函数
 * @param fp {ACL_VSTREAM*} 数据流
 * @param close_fn {void (*)(ACL_VSTREAM*, void*)} 关闭函数指针
 * @param context {void*} close_fn 所需要的参数
 */
ACL_API void acl_vstream_add_close_handle(ACL_VSTREAM *fp,
		void (*close_fn)(ACL_VSTREAM*, void*), void *context);

/**
 * 删除一个关闭句柄.
 * @param fp {ACL_VSTREAM*} 数据流
 * @param close_fn {void (*)(ACL_VSTREAM*, void*)} 关闭函数指针
 * @param context {void*} close_fn 所需要的参数
 */
ACL_API void acl_vstream_delete_close_handle(ACL_VSTREAM *fp,
		void (*close_fn)(ACL_VSTREAM*, void*), void *context);
/**
 * 清除一个数据流中所有的关闭句柄
 * @param fp {ACL_VSTREAM*} 数据流
 */
ACL_API void acl_vstream_clean_close_handle(ACL_VSTREAM *fp);

/**
 * 重新复位数据流的内部数据指针及计数值
 * @param fp {ACL_VSTREAM*} 数据流
 */
ACL_API void acl_vstream_reset(ACL_VSTREAM *fp);

/**
 * 取得当前数据流的错误状态
 * @param fp {ACL_VSTREAM*} 数据流
 * @return {const char*} 错误描述
 */
ACL_API const char *acl_vstream_strerror(ACL_VSTREAM *fp);

/*-----------------------  以下为常用的宏函数 ------------------------------*/
/**
 * 从fp 流中读取一个字节的宏实现，效率要比 acl_vstream_getc()/1 高
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @return {int} ACL_VSTREAM_EOF(出错) 或所读到的某个字节的ASCII,
 *  若为 ACL_VSTREAM_EOF: 读出错或对方关闭了连接, 应该关闭该数据流
 */
#define ACL_VSTREAM_GETC(stream_ptr) (                        \
    (stream_ptr)->read_cnt > 0 ?                              \
        (stream_ptr)->read_cnt--,                             \
        (stream_ptr)->offset++,                               \
        *(stream_ptr)->read_ptr++:                            \
        (stream_ptr)->sys_getc((stream_ptr)))

/**
 * 向 fp 流中写一个字节的宏实现
 * @param fp {ACL_VSTREAM*} 数据流指针
 * @return {int} ACL_VSTREAM_EOF(出错) 或所写入字节的 ASCII
 */
#define ACL_VSTREAM_PUTC(ch, stream_ptr) (                                   \
  (stream_ptr)->wbuf_size == 0 ?                                             \
    (acl_vstream_buffed_space((stream_ptr)),                                 \
        ((stream_ptr)->wbuf[(size_t) (stream_ptr)->wbuf_dlen++] = (ch)))     \
    : ((stream_ptr)->wbuf_dlen == stream_ptr->wbuf_size ?                    \
        (acl_vstream_fflush((stream_ptr)) == ACL_VSTREAM_EOF ?               \
          ACL_VSTREAM_EOF                                                    \
          : ((stream_ptr)->wbuf[(size_t) (stream_ptr)->wbuf_dlen++] = (ch))) \
        : ((stream_ptr)->wbuf[(size_t) (stream_ptr)->wbuf_dlen++] = (ch))))

/**
 * 由流获得套接字
 * @param stream_ptr {ACL_VSTREAM*}
 */
#define ACL_VSTREAM_SOCK(stream_ptr) ((stream_ptr)->fd.sock)

/**
 * 由流获得文件句柄
 * @param stream_ptr {ACL_VSTREAM*}
 */
#define ACL_VSTREAM_FILE(stream_ptr) ((stream_ptr)->fd.h_file)

/**
 * 获得文件流句柄的文件路径名
 * @param stream_ptr {ACL_VSTREAM*}
 */
#define	ACL_VSTREAM_PATH(stream_ptr) ((stream_ptr)->path)

/**
 * 当 ACL_VSTREAM 为文件流时，设置文件流的路径
 * @param fp {ACL_VSTREAM*} 文件流
 * @param path {const char*} 文件路径
 */
ACL_API void acl_vstream_set_path(ACL_VSTREAM *fp, const char *path);

/**
 * 当 ACL_VSTREAM 为网络流时，用此宏取得对方的地址
 */
#define	ACL_VSTREAM_PEER(stream_ptr) ((stream_ptr)->addr_peer)

/**
 * 当 ACL_VSTREAM 为网络流时，此函数设置远程连接地址
 * @param fp {ACL_VSTREAM*} 网络流，非空
 * @param addr {const char*} 远程连接地址，非空
 */
ACL_API void acl_vstream_set_peer(ACL_VSTREAM *fp, const char *addr);

/**
 * 当 ACL_VSTREAM 为网络流时，此函数设置远程连接地址
 * @param fp {ACL_VSTREAM*} 网络流，非空
 * @param sa {const struct sockaddr_in *} 远程连接地址，非空
 */
ACL_API void acl_vstream_set_peer_addr(ACL_VSTREAM *fp,
	const struct sockaddr_in *sa);

/**
 * 当 ACL_VSTREAM 为网络流时，用此宏取得本地的地址
 */
#define	ACL_VSTREAM_LOCAL(stream_ptr) ((stream_ptr)->addr_local)

/**
 * 当 ACL_VSTREAM 为网络流时，此函数设置本地地址
 * @param fp {ACL_VSTREAM*} 网络流，非空
 * @param addr {const char*} 本地地址，非空
 */
ACL_API void acl_vstream_set_local(ACL_VSTREAM *fp, const char *addr);

/**
 * 当 ACL_VSTREAM 为网络流时，此函数设置本地地址
 * @param fp {ACL_VSTREAM*} 网络流，非空
 * @param sa {const sockaddr_in*} 本地地址，非空
 */
ACL_API void acl_vstream_set_local_addr(ACL_VSTREAM *fp,
	const struct sockaddr_in *sa);

ACL_API int acl_vstream_add_object(ACL_VSTREAM *fp, const char *key, void *obj);
ACL_API int acl_vstream_del_object(ACL_VSTREAM *fp, const char *key);
ACL_API void *acl_vstream_get_object(ACL_VSTREAM *fp, const char *key);

/**
 * 设定流的读/写套接字
 * @param stream_ptr {ACL_VSTREAM*}
 * @param _fd {ACL_SOCKET} 套接字
 */
#define	ACL_VSTREAM_SET_SOCK(stream_ptr, _fd) do {            \
        ACL_VSTREAM *__stream_ptr = stream_ptr;               \
        __stream_ptr->fd.sock   = _fd;                        \
} while (0)

/**
 * 设置流中的文件句柄
 * @param stream_ptr {ACL_VSTREAM*}
 * @param _fh {ACL_FILE_HANDLE}
 */
#define	ACL_VSTREAM_SET_FILE(stream_ptr, _fh) do {            \
        ACL_VSTREAM *__stream_ptr = stream_ptr;               \
        __stream_ptr->fd.h_file = _fh;                        \
} while (0)

/* 一些比较快速的宏的运算模式 */

/**
 * 流中在读缓冲区中的数据量大小
 * @param stream_ptr {ACL_VSTREAM*) 类型的指针
 * @return -1: 表示出错, >= 0 此值即为流读缓冲区中的数据量大小
 */
#define	ACL_VSTREAM_BFRD_CNT(stream_ptr)                      \
	((stream_ptr) == NULL ? -1 : (stream_ptr)->read_cnt)

/**
 * 设定流的读写超时值
 * @param stream_ptr {ACL_VSTREAM*) 类型的指针
 * @param _rw_timeo {int} 超时值大小(以秒为单位)
 */
#define	ACL_VSTREAM_SET_RWTIMO(stream_ptr, _rw_timeo) do {    \
        ACL_VSTREAM *__stream_ptr  = stream_ptr;              \
        __stream_ptr->rw_timeout = _rw_timeo;                 \
} while (0)

/**
 * 将流置为结束状态
 * @param stream_ptr {ACL_VSTREAM*) 类型的指针
 */
#define	ACL_VSTREAM_SET_EOF(stream_ptr) do {                  \
        ACL_VSTREAM *__stream_ptr = stream_ptr;               \
        __stream_ptr->flag |= ACL_VSTREAM_FLAG_EOF;           \
} while (0)

/**
 * 判断数据流是否出了错
 * @param stream_ptr: ACL_VSTREAM 类型的指针
 * @return 0表示正常, 非0表示出错
 */
#define ACL_IF_VSTREAM_ERR(stream_ptr)                        \
	((stream_ptr)->flag & ACL_VSTREAM_FLAG_BAD)

#ifdef  __cplusplus
}
#endif

/**
 * 从数据流中取出与该流读写有关的系统错误号
 * @param stream_ptr {ACL_VSTREAM*) 类型的指针
 * @return err {int} 整形错误号，调用者可以用 strerror(err) 的方式查看具体含义
 */
#define	ACL_VSTREAM_ERRNO(stream_ptr) ((stream_ptr)->errnum)

/**
 * 判断一个流是否超时
 * @param stream_ptr {ACL_VSTREAM*) 类型的指针
 * @return {int} 0: 否; != 0: 是
 */
#define	acl_vstream_ftimeout(stream_ptr) \
        ((stream_ptr)->flag & ACL_VSTREAM_FLAG_TIMEOUT)

#endif