Added file I/O and file access API

git-svn-id: http://svn.pjsip.org/repos/pjproject/main@18 74dad513-b988-da41-8d7b-12977e46ad98

9 files changed, 287 insertions, 20 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.                   */
 };
 
 /**
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 <pj/ctype.h>
 #include <pj/errno.h>
 #include <pj/except.h>
-#include <pj/fifobuf.h>
+#include <pj/fifobuf.h>

+#include <pj/file_access.h>
+#include <pj/file_io.h>
 #include <pj/guid.h>
 #include <pj/hash.h>
 #include <pj/ioqueue.h>