diff options
Diffstat (limited to 'pjlib/include/pj')
-rw-r--r-- | pjlib/include/pj/addr_resolv.h | 2 | ||||
-rw-r--r-- | pjlib/include/pj/file_access.h | 91 | ||||
-rw-r--r-- | pjlib/include/pj/file_io.h | 155 | ||||
-rw-r--r-- | pjlib/include/pj/ioqueue.h | 20 | ||||
-rw-r--r-- | pjlib/include/pj/list.h | 7 | ||||
-rw-r--r-- | pjlib/include/pj/pool.h | 2 | ||||
-rw-r--r-- | pjlib/include/pj/types.h | 8 | ||||
-rw-r--r-- | pjlib/include/pj/xml.h | 18 |
8 files changed, 284 insertions, 19 deletions
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/types.h>
+
+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/types.h> + +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. */ }; /** |