From e25a988d098a075f5519090c24237c3b97bc1323 Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Mon, 7 Nov 2005 15:47:28 +0000 Subject: Added file I/O and file access API git-svn-id: http://svn.pjsip.org/repos/pjproject/main@18 74dad513-b988-da41-8d7b-12977e46ad98 --- pjlib/include/pj/addr_resolv.h | 2 +- pjlib/include/pj/file_access.h | 91 ++++++++++++++++++++++++ pjlib/include/pj/file_io.h | 155 +++++++++++++++++++++++++++++++++++++++++ pjlib/include/pj/ioqueue.h | 20 ++++-- pjlib/include/pj/list.h | 7 +- pjlib/include/pj/pool.h | 2 +- pjlib/include/pj/types.h | 8 +++ pjlib/include/pj/xml.h | 18 ++--- pjlib/include/pjlib.h | 4 +- 9 files changed, 287 insertions(+), 20 deletions(-) create mode 100644 pjlib/include/pj/file_access.h create mode 100644 pjlib/include/pj/file_io.h (limited to 'pjlib/include') diff --git a/pjlib/include/pj/addr_resolv.h b/pjlib/include/pj/addr_resolv.h index 1a47cf0d..1da92082 100644 --- a/pjlib/include/pj/addr_resolv.h +++ b/pjlib/include/pj/addr_resolv.h @@ -14,7 +14,7 @@ PJ_BEGIN_DECL /** - * @defgroup pj_addr_resolve Address Resolution + * @defgroup pj_addr_resolve Network Address Resolution * @ingroup PJ_IO * @{ * diff --git a/pjlib/include/pj/file_access.h b/pjlib/include/pj/file_access.h new file mode 100644 index 00000000..473484d8 --- /dev/null +++ b/pjlib/include/pj/file_access.h @@ -0,0 +1,91 @@ +/* $Id */ +#ifndef __PJ_FILE_ACCESS_H__ +#define __PJ_FILE_ACCESS_H__ + +/** + * @file file_access.h + * @brief File manipulation and access. + */ +#include + +PJ_BEGIN_DECL + +/** + * @defgroup PJ_FILE_ACCESS File Access + * @ingroup PJ_IO + * @{ + * + */ + +/** + * This structure describes file information, to be obtained by + * calling #pj_file_getstat(). The time information in this structure + * is in local time. + */ +typedef struct pj_file_stat +{ + pj_off_t size; /**< Total file size. */ + pj_time_val atime; /**< Time of last access. */ + pj_time_val mtime; /**< Time of last modification. */ + pj_time_val ctime; /**< Time of last creation. */ +} pj_file_stat; + + +/** + * Returns non-zero if the specified file exists. + * + * @param filename The file name. + * + * @return Non-zero if the file exists. + */ +PJ_DECL(pj_bool_t) pj_file_exists(const char *filename); + +/** + * Returns the size of the file. + * + * @param filename The file name. + * + * @return The file size in bytes or -1 on error. + */ +PJ_DECL(pj_off_t) pj_file_size(const char *filename); + +/** + * Delete a file. + * + * @param filename The filename. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_file_delete(const char *filename); + +/** + * Move a \c oldname to \c newname. If \c newname already exists, + * it will be overwritten. + * + * @param oldname The file to rename. + * @param newname New filename to assign. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_file_move( const char *oldname, + const char *newname); + + +/** + * Return information about the specified file. The time information in + * the \c stat structure will be in local time. + * + * @param filename The filename. + * @param stat Pointer to variable to receive file information. + * + * @return PJ_SUCCESS on success or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_file_getstat(const char *filename, pj_file_stat *stat); + + +/** @} */ + +PJ_END_DECL + + +#endif /* __PJ_FILE_ACCESS_H__ */ diff --git a/pjlib/include/pj/file_io.h b/pjlib/include/pj/file_io.h new file mode 100644 index 00000000..7e5fa3ea --- /dev/null +++ b/pjlib/include/pj/file_io.h @@ -0,0 +1,155 @@ +/* $Id$ */ +#ifndef __PJ_FILE_IO_H__ +#define __PJ_FILE_IO_H__ + +/** + * @file file_io.h + * @brief Simple file I/O abstraction. + */ +#include + +PJ_BEGIN_DECL + +/** + * @defgroup PJ_FILE_IO File I/O + * @ingroup PJ_IO + * @{ + * + * This file contains functionalities to perform file I/O. The file + * I/O can be implemented with various back-end, either using native + * file API or ANSI stream. + * + * @section pj_file_size_limit_sec Size Limits + * + * There may be limitation on the size that can be handled by the + * #pj_file_setpos() or #pj_file_getpos() functions. The API itself + * uses 64-bit integer for the file offset/position (where available); + * however some backends (such as ANSI) may only support signed 32-bit + * offset resolution. + * + * Reading and writing operation uses signed 32-bit integer to indicate + * the size. + * + * + */ + +/** + * These enumerations are used when opening file. Values PJ_O_RDONLY, + * PJ_O_WRONLY, and PJ_O_RDWR are mutually exclusive. Value PJ_O_APPEND + * can only be used when the file is opened for writing. + */ +enum pj_file_access +{ + PJ_O_RDONLY = 0x1101, /**< Open file for reading. */ + PJ_O_WRONLY = 0x1102, /**< Open file for writing. */ + PJ_O_RDWR = 0x1103, /**< Open file for reading and writing. + File will be truncated. */ + PJ_O_APPEND = 0x1108, /**< Append to existing file. */ +}; + +/** + * The seek directive when setting the file position with #pj_file_setpos. + */ +enum pj_file_seek_type +{ + PJ_SEEK_SET = 0x1201, /**< Offset from beginning of the file. */ + PJ_SEEK_CUR = 0x1202, /**< Offset from current position. */ + PJ_SEEK_END = 0x1203, /**< Size of the file plus offset. */ +}; + +/** + * Open the file as specified in \c pathname with the specified + * mode, and return the handle in \c fd. All files will be opened + * as binary. + * + * @param pool Pool to allocate memory for the new file descriptor. + * @param pathname The file name to open. + * @param flags Open flags, which is bitmask combination of + * #pj_file_access enum. The flag must be either + * PJ_O_RDONLY, PJ_O_WRONLY, or PJ_O_RDWR. When file + * writing is specified, existing file will be + * truncated unless PJ_O_APPEND is specified. + * @param fd The returned descriptor. + * + * @return PJ_SUCCESS or the appropriate error code on error. + */ +PJ_DECL(pj_status_t) pj_file_open(pj_pool_t *pool, + const char *pathname, + unsigned flags, + pj_oshandle_t *fd); + +/** + * Close an opened file descriptor. + * + * @param fd The file descriptor. + * + * @return PJ_SUCCESS or the appropriate error code on error. + */ +PJ_DECL(pj_status_t) pj_file_close(pj_oshandle_t fd); + +/** + * Write data with the specified size to an opened file. + * + * @param fd The file descriptor. + * @param data Data to be written to the file. + * @param size On input, specifies the size of data to be written. + * On return, it contains the number of data actually + * written to the file. + * + * @return PJ_SUCCESS or the appropriate error code on error. + */ +PJ_DECL(pj_status_t) pj_file_write(pj_oshandle_t fd, + const void *data, + pj_ssize_t *size); + +/** + * Read data from the specified file. When end-of-file condition is set, + * this function will return PJ_SUCCESS but the size will contain zero. + * + * @param fd The file descriptor. + * @param data Pointer to buffer to receive the data. + * @param size On input, specifies the maximum number of data to + * read from the file. On output, it contains the size + * of data actually read from the file. It will contain + * zero when EOF occurs. + * + * @return PJ_SUCCESS or the appropriate error code on error. + * When EOF occurs, the return is PJ_SUCCESS but size + * will report zero. + */ +PJ_DECL(pj_status_t) pj_file_read(pj_oshandle_t fd, + void *data, + pj_ssize_t *size); + +/** + * Set file position to new offset according to directive \c whence. + * + * @param fd The file descriptor. + * @param offset The new file position to set. + * @param whence The directive. + * + * @return PJ_SUCCESS or the appropriate error code on error. + */ +PJ_DECL(pj_status_t) pj_file_setpos(pj_oshandle_t fd, + pj_off_t offset, + enum pj_file_seek_type whence); + +/** + * Get current file position. + * + * @param fd The file descriptor. + * @param pos On return contains the file position as measured + * from the beginning of the file. + * + * @return PJ_SUCCESS or the appropriate error code on error. + */ +PJ_DECL(pj_status_t) pj_file_getpos(pj_oshandle_t fd, + pj_off_t *pos); + +/** @} */ + + +PJ_END_DECL + +#endif /* __PJ_FILE_IO_H__ */ + diff --git a/pjlib/include/pj/ioqueue.h b/pjlib/include/pj/ioqueue.h index ce30c9f9..303df162 100644 --- a/pjlib/include/pj/ioqueue.h +++ b/pjlib/include/pj/ioqueue.h @@ -14,8 +14,8 @@ PJ_BEGIN_DECL /** - * @defgroup PJ_IO Network I/O - * @brief Network I/O + * @defgroup PJ_IO Input/Output + * @brief Input/Output * @ingroup PJ_OS * * This section contains API building blocks to perform network I/O and @@ -52,6 +52,11 @@ PJ_BEGIN_DECL * asynchronous operation and to be notified later when the operation has * completed. * + * The I/O Queue can work on both socket and file descriptors. For + * asynchronous file operations however, one must make sure that the correct + * file I/O back-end is used, because not all file I/O back-end can be + * used with the ioqueue. Please see \ref PJ_FILE_IO for more details. + * * The framework works natively in platforms where asynchronous operation API * exists, such as in Windows NT with IoCompletionPort/IOCP. In other * platforms, the I/O queue abstracts the operating system's event poll API @@ -60,7 +65,7 @@ PJ_BEGIN_DECL * * The I/O queue provides more than just unified abstraction. It also: * - makes sure that the operation uses the most effective way to utilize - * the underlying mechanism, to provide the maximum theoritical + * the underlying mechanism, to achieve the maximum theoritical * throughput possible on a given platform. * - choose the most efficient mechanism for event polling on a given * platform. @@ -487,7 +492,6 @@ PJ_DECL(pj_status_t) pj_ioqueue_recvfrom( pj_ioqueue_key_t *key, pj_sockaddr_t *addr, int *addrlen); - /** * Instruct the I/O Queue to write to the handle. This function will return * immediately (i.e. non-blocking) regardless whether some data has been @@ -529,8 +533,12 @@ PJ_DECL(pj_status_t) pj_ioqueue_send( pj_ioqueue_key_t *key, /** - * This function behaves similarly as #pj_ioqueue_write(), except that - * pj_sock_sendto() (or equivalent) will be called to send the data. + * Instruct the I/O Queue to write to the handle. This function will return + * immediately (i.e. non-blocking) regardless whether some data has been + * transfered. If the function can't complete immediately, the caller will + * be notified about the completion when it calls pj_ioqueue_poll(). If + * operation completes immediately and data has been transfered, the function + * returns PJ_SUCCESS and the callback will NOT be called. * * @param key the key that identifies the handle. * @param op_key An operation specific key to be associated with the diff --git a/pjlib/include/pj/list.h b/pjlib/include/pj/list.h index 95ae99fd..f6662eb6 100644 --- a/pjlib/include/pj/list.h +++ b/pjlib/include/pj/list.h @@ -45,8 +45,11 @@ PJ_BEGIN_DECL * declares additional member @a prev and @a next to the structure. * @hideinitializer */ -#define PJ_DECL_LIST_MEMBER(type) type *prev; /** List @a prev. */ \ - type *next /** List @a next. */ +#define PJ_DECL_LIST_MEMBER(type) \ + /** List @a prev. */ \ + type *prev; \ + /** List @a next. */ \ + type *next /** diff --git a/pjlib/include/pj/pool.h b/pjlib/include/pj/pool.h index 4001079f..4be4d242 100644 --- a/pjlib/include/pj/pool.h +++ b/pjlib/include/pj/pool.h @@ -126,7 +126,7 @@ typedef struct pj_pool_block */ struct pj_pool_t { - PJ_DECL_LIST_MEMBER(struct pj_pool_t); + PJ_DECL_LIST_MEMBER(struct pj_pool_t); /**< Standard list elements. */ /** Pool name */ char obj_name[PJ_MAX_OBJ_NAME]; diff --git a/pjlib/include/pj/types.h b/pjlib/include/pj/types.h index 892a508b..ec3df2c1 100644 --- a/pjlib/include/pj/types.h +++ b/pjlib/include/pj/types.h @@ -63,6 +63,14 @@ typedef int pj_bool_t; /** False value. */ #define PJ_FALSE 0 +/** + * File offset type. + */ +#if defined(PJ_HAS_INT64) && PJ_HAS_INT64!=0 +typedef pj_int64_t pj_off_t; +#else +typedef pj_ssize_t pj_off_t; +#endif /////////////////////////////////////////////////////////////////////////////// /* diff --git a/pjlib/include/pj/xml.h b/pjlib/include/pj/xml.h index 9777a514..fd7978ae 100644 --- a/pjlib/include/pj/xml.h +++ b/pjlib/include/pj/xml.h @@ -30,26 +30,26 @@ typedef struct pj_xml_node pj_xml_node; /** This structure declares XML attribute. */ struct pj_xml_attr { - PJ_DECL_LIST_MEMBER(pj_xml_attr); - pj_str_t name; /**< Attribute name. */ - pj_str_t value; /**< Attribute value. */ + PJ_DECL_LIST_MEMBER(pj_xml_attr); /**< Standard list elements. */ + pj_str_t name; /**< Attribute name. */ + pj_str_t value; /**< Attribute value. */ }; /** This structure describes XML node head inside XML node structure. */ typedef struct pj_xml_node_head { - PJ_DECL_LIST_MEMBER(pj_xml_node); + PJ_DECL_LIST_MEMBER(pj_xml_node); /**< Standard list elements. */ } pj_xml_node_head; /** This structure describes XML node. */ struct pj_xml_node { - PJ_DECL_LIST_MEMBER(pj_xml_node); /** List @a prev and @a next member */ - pj_str_t name; /** Node name. */ - pj_xml_attr attr_head; /** Attribute list. */ - pj_xml_node_head node_head; /** Node list. */ - pj_str_t content; /** Node content. */ + PJ_DECL_LIST_MEMBER(pj_xml_node); /**< List @a prev and @a next member */ + pj_str_t name; /**< Node name. */ + pj_xml_attr attr_head; /**< Attribute list. */ + pj_xml_node_head node_head; /**< Node list. */ + pj_str_t content; /**< Node content. */ }; /** diff --git a/pjlib/include/pjlib.h b/pjlib/include/pjlib.h index c5623d60..76d61d90 100644 --- a/pjlib/include/pjlib.h +++ b/pjlib/include/pjlib.h @@ -15,7 +15,9 @@ #include #include #include -#include +#include +#include +#include #include #include #include -- cgit v1.2.3