Fixed pjlib doxygen documentation
git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@514 74dad513-b988-da41-8d7b-12977e46ad98
diff --git a/pjlib/include/pj/doxygen.h b/pjlib/include/pj/doxygen.h
index 4f14dba..2d022bb 100644
--- a/pjlib/include/pj/doxygen.h
+++ b/pjlib/include/pj/doxygen.h
@@ -234,22 +234,6 @@
* implemented with various back-end.
*
*
- * @subsection hl_network_io_sec High-Level Network I/O
- *
- * At higher abstraction, PJLIB provides @ref PJ_IOQUEUE,
- * which promotes creating high performance network
- * applications by managing asynchronous I/O. This is a passive framework
- * that utilizes the most effective way to manage asynchronous I/O
- * on a given platform, such as:
- * - IoCompletionPort on WinNT,
- * - on Linux it can use either /dev/epoll or aio.
- * - or to fall back to use @a select()
- *
- * At even a higher abstraction, PJLIB provides @ref PJ_EQUEUE, which
- * combines asynchronous I/O with timer management and thread management
- * to fasilitate creating trully high performance, event driven
- * application.
- *
*
* @subsection timer_mgmt_sec Timer Management
*
@@ -484,16 +468,16 @@
* the \a workspace file in the corresponding \b \c build directory. You have
* several choices on which \a dsw file to open:
\verbatim
- $PJPROJECT/build/pjproject.dsw
- $PJPROJECT/pjlib/build/pjlib.dsw
- $PJPROJECT/pjsip/build/pjsip.dsw
+ $PJPROJECT/pjlib/build/pjlib.dsw
+ $PJPROJECT/pjsip/build/pjsip.dsw
..etc
\endverbatim
*
- * The easiest way is to open <tt>pjproject.dsw</tt> file in \b \c $PJPROJECT/build
- * directory. However this will only build the required projects, not
- * the complete projects. For example, the PJLIB test and samples projects
- * are not included in this workspace. To build the complete projects, you must
+ * The easiest way is to open <tt>pjsip_apps.dsw</tt> file in \b \c $PJPROJECT/pjsip-apps/build
+ * directory, and build pjsua project or the samples project.
+ * However this will not build the complete projects.
+ * For example, the PJLIB test is not included in this workspace.
+ * To build the complete projects, you must
* open and build each \a dsw file in \c build directory in each
* subprojects. For example, to open the complete PJLIB workspace, open
* <tt>pjlib.dsw</tt> in <tt>$PJPROJECT/pjlib/build</tt> directory.
@@ -567,52 +551,27 @@
* Generally, steps required to build the PJLIB are:
*
\verbatim
- $ cd /home/user/pjproject # <-- go to $PJPROJECT
- $ vi build.mak # <-- set build target etc
+ $ cd /home/user/pjproject
+ $ ./configure
$ touch pjlib/include/pj/config_site.h
- $ cd pjlib/build # <-- go to projet's build dir
- $ make # <-- build the project
+ $ make dep
+ $ make
\endverbatim
*
- * For other project, \a cd to <tt>build</tt> directory in the project
- * and execute \a make from there.
+ * The above process will build all static libraries and all applications.
+ *
+ * \note the <tt>configure</tt> script is not a proper autoconf script,
+ * but rather a simple shell script to detect current host. This script
+ * currently does not support cross-compilation.
*
* \note For Linux kernel target, there are additional steps required, which
* will be explained in section \ref linux_kern_target_subsec.
*
- * @subsubsection build_mak_sec Editing build.mak
+ * @subsubsection build_mak_sec Cross Compilation
*
- * The \c build.mak file in \c $PJPROJECT root directory is used to
- * specify the build configuration. This file is expected to export
- * the following \a make variables:
- *
- * - <tt><b>MACHINE_NAME</b></tt>
- *\n
- * Target machine/processor, one of: <b>{ i386 | alpha | sparc }</b>.
- *
- * - <tt><b>OS_NAME</b></tt>
- *\n
- * Target operating system, one of: <b>{ win32 | linux |
- * linux-kernel | sunos }</b>.
- *
- * - <tt><b>CC_NAME</b></tt>
- *\n
- * Compiler name: <b>{ gcc | vc }</b>\n
- * (Note that support for Visual C (vc) compiler with the \c make system is
- * experimental, and it will only work when run inside a DOS shell
- * (i.e. <tt>"HOST_NAME=win32"</tt>)).
- *
- * - <tt><b>HOST_NAME</b></tt>
- *\n
- * Build host: <b>{ unix | mingw | win32 }</b>\n
- * (Note: win32 host means a DOS command prompt. Support for this type
- * of development host is experimental).
- *
- * These variables will cause the correct configuration file in
- * \c $PJPROJECT/build directory to be executed by \a make. For
- * example, specifying \c OS_NAME=linux will cause file \c os-linux.mak
- * in \c build directory to be executed. These files contain specific
- * configuration for the option that is selected.
+ * For cross compilation, you will need to edit the \c build.mak file in
+ * \c $PJPROJECT root directory manually. Please see <b>README-configure</b> file
+ * in the root directory for more information.
*
* For Linux kernel target, you are also required to declare the following
* variables in this file:
diff --git a/pjlib/include/pj/equeue.h b/pjlib/include/pj/equeue.h
deleted file mode 100644
index 77374bd..0000000
--- a/pjlib/include/pj/equeue.h
+++ /dev/null
@@ -1,336 +0,0 @@
-/* $Id$ */
-/*
- * Copyright (C)2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJ_EQUEUE_H__
-#define __PJ_EQUEUE_H__
-
-/**
- * @file equeue.h
- * @brief Event Queue
- */
-#include <pj/types.h>
-
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJ_EQUEUE Event Queue
- * @brief Event Queue
- * @ingroup PJ_OS
- * @{
- */
-
-
-/**
- * Opaque data type for Event Queue.
- */
-typedef struct pj_equeue_t pj_equeue_t;
-
-/**
- * Opaque data type for Event Queue key.
- */
-typedef struct pj_equeue_key_t pj_equeue_key_t;
-
-
-/**
- * This structure describes the callbacks to be called when I/O operation
- * completes.
- */
-typedef struct pj_io_callback
-{
- /**
- * This callback is called when #pj_equeue_read, #pj_equeue_recv or
- * #pj_equeue_recvfrom completes.
- *
- * @param key The key.
- * @param bytes_read The size of data that has just been read.
- */
- void (*on_read_complete)(pj_equeue_key_t *key, pj_ssize_t bytes_read);
-
- /**
- * This callback is called when #pj_equeue_write, #pj_equeue_send, or
- * #pj_equeue_sendto completes.
- *
- * @param key The key.
- * @param bytes_read The size of data that has just been written.
- */
- void (*on_write_complete)(pj_equeue_key_t *key, pj_ssize_t bytes_sent);
-
- /**
- * This callback is called when #pj_equeue_accept completes.
- *
- * @param key The key.
- * @param status Zero if the operation completes successfully.
- */
- void (*on_accept_complete)(pj_equeue_key_t *key, int status);
-
- /**
- * This callback is called when #pj_equeue_connect completes.
- *
- * @param key The key.
- * @param status Zero if the operation completes successfully.
- */
- void (*on_connect_complete)(pj_equeue_key_t *key, int status);
-
-} pj_io_callback;
-
-/**
- * Event Queue options.
- */
-typedef struct pj_equeue_options
-{
- /** Maximum number of threads that are allowed to access Event Queue
- * simulteneously.
- */
- unsigned nb_threads;
-
- /** If non-zero, then no mutex protection will be used. */
- pj_bool_t no_lock;
-
- /** Interval of the busy loop inside the event queue.
- * The time resolution here determines the accuracy of the
- * timer in the Event Queue.
- */
- pj_time_val poll_interval;
-
-} pj_equeue_options;
-
-
-/**
- * Error value returned by I/O operations to indicate that the operation
- * can't complete immediately and will complete later.
- */
-#define PJ_EQUEUE_PENDING (-2)
-
-/**
- * Types of Event Queue operation.
- */
-typedef enum pj_equeue_op
-{
- PJ_EQUEUE_OP_NONE = 0, /**< No operation. */
- PJ_EQUEUE_OP_READ = 1, /**< read() operation. */
- PJ_EQUEUE_OP_RECV_FROM = 2, /**< recvfrom() operation. */
- PJ_EQUEUE_OP_WRITE = 4, /**< write() operation. */
- PJ_EQUEUE_OP_SEND_TO = 8, /**< sendto() operation. */
-#if defined(PJ_HAS_TCP) && PJ_HAS_TCP != 0
- PJ_EQUEUE_OP_ACCEPT = 16, /**< accept() operation. */
- PJ_EQUEUE_OP_CONNECT = 32, /**< connect() operation. */
-#endif /* PJ_HAS_TCP */
-} pj_equeue_op;
-
-
-
-/**
- * Initialize Event Queue options with default values.
- *
- * @param options Event Queue options.
- */
-PJ_DECL(void) pj_equeue_options_init(pj_equeue_options *options);
-
-/**
- * Create a new Event Queue framework.
- *
- * @param pool The pool to allocate the event queue structure.
- * @param options Event queue options, or if NULL is given, then
- * default options will be used.
- * @param equeue Pointer to receive event queue structure.
- *
- * @return zero on success.
- */
-PJ_DECL(pj_status_t) pj_equeue_create( pj_pool_t *pool,
- const pj_equeue_options *options,
- pj_equeue_t **equeue);
-
-/**
- * Get the first instance of Event Queue, or NULL if no Event Queue
- * instance has been created in the application.
- *
- * @return The first instance of Event Queue created, or NULL.
- */
-PJ_DECL(pj_equeue_t*) pj_equeue_instance(void);
-
-/**
- * Destroy the Event Queue.
- *
- * @param equeue The Event Queue instance to be destroyed.
- */
-PJ_DECL(pj_status_t) pj_equeue_destroy( pj_equeue_t *equeue );
-
-/**
- * Customize the lock object that is used by the Event Queue.
- *
- * @param equeue The Event Queue instance.
- * @param lock The lock object.
- * @param auto_del If non-zero, the lock will be destroyed by
- * Event Queue.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pj_equeue_set_lock( pj_equeue_t *equeue,
- pj_lock_t *lock,
- pj_bool_t auto_del);
-
-/**
- * Associate an Event Queue key to particular handle. The key is also
- * associated with the callback and user data, which will be used by
- * the Event Queue framework when signalling event back to application.
- *
- * @param pool To allocate the resource for the specified handle, which
- * must be valid until the handle/key is unregistered
- * from Event Queue.
- * @param equeue The Event Queue.
- * @param hnd The OS handle to be registered, which can be a socket
- * descriptor (pj_sock_t), file descriptor, etc.
- * @param cb Callback to be called when I/O operation completes.
- * @param user_data User data to be associated with the key.
- * @param key Pointer to receive the key.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pj_equeue_register( pj_pool_t *pool,
- pj_equeue_t *equeue,
- pj_oshandle_t hnd,
- pj_io_callback *cb,
- void *user_data,
- pj_equeue_key_t **key);
-
-/**
- * Retrieve user data associated with a key.
- *
- * @param key The Event Queue key.
- *
- * @return User data associated with the key.
- */
-PJ_DECL(void*) pj_equeue_get_user_data( pj_equeue_key_t *key );
-
-
-/**
- * Unregister Event Queue key from the Event Queue.
- *
- * @param equeue The Event Queue.
- * @param key The key.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pj_equeue_unregister( pj_equeue_t *equeue,
- pj_equeue_key_t *key);
-
-/**
- * Instruct the Event Queue to read from the specified handle. This function
- * returns immediately (i.e. non-blocking) regardless whether some data has
- * been transfered. If the operation can't complete immediately, caller will
- * be notified about the completion when it calls pj_equeue_poll().
- *
- * @param key The key that uniquely identifies the handle.
- * @param buffer The buffer to hold the read data. The caller MUST make sure
- * that this buffer remain valid until the framework completes
- * reading the handle.
- * @param size The maximum size to be read.
- *
- * @return
- * - zero or positive number to indicate the number of bytes has been
- * read, and in this case the operation was not queued.
- * - (-1) on error, which in this case operation was not queued.
- * - PJ_EQUEUE_PENDING if the operation has been queued.
- */
-PJ_DECL(pj_ssize_t) pj_equeue_read( pj_equeue_key_t *key,
- void *buffer,
- pj_size_t size);
-
-/**
- * Start recv() operation on the specified handle.
- *
- * @see ::pj_ioqueue_read
- */
-PJ_DECL(pj_ssize_t) pj_equeue_recv( pj_equeue_key_t *key,
- void *buf,
- pj_size_t size,
- unsigned flags);
-
-/**
- * Start recvfrom() operation on the specified handle.
- *
- * @see ::pj_equeue_read
- */
-PJ_DECL(pj_ssize_t) pj_equeue_recvfrom( pj_equeue_key_t *key,
- void *buf,
- pj_size_t size,
- unsigned flags,
- pj_sockaddr_t *addr,
- int *addrlen );
-
-/**
- * Write.
- */
-PJ_DECL(pj_ssize_t) pj_equeue_write( pj_equeue_key_t *key,
- const void *buf,
- pj_size_t size);
-
-/**
- * Send.
- */
-PJ_DECL(pj_ssize_t) pj_equeue_send( pj_equeue_key_t *key,
- const void *buf,
- pj_size_t size,
- unsigned flags);
-
-/**
- * Sendto.
- */
-PJ_DECL(pj_ssize_t) pj_equeue_sendto( pj_equeue_key_t *key,
- const void *buf,
- pj_size_t size,
- unsigned flags,
- const pj_sockaddr_t *addr,
- int addrlen);
-
-/**
- * Schedule timer.
- */
-PJ_DECL(pj_status_t) pj_equeue_schedule_timer( pj_equeue_t *equeue,
- const pj_time_val *timeout,
- pj_timer_entry *entry);
-
-/**
- * Cancel timer.
- */
-PJ_DECL(pj_status_t) pj_equeue_cancel_timer( pj_equeue_t *equeue,
- pj_timer_entry *entry);
-
-/**
- * Poll for events.
- */
-PJ_DECL(pj_status_t) pj_equeue_poll( pj_equeue_t *equeue,
- const pj_time_val *timeout );
-
-/**
- * Run.
- */
-PJ_DECL(pj_status_t) pj_equeue_run( pj_equeue_t *equeue );
-
-/**
- * Stop all running threads.
- */
-PJ_DECL(pj_status_t) pj_equeue_stop( pj_equeue_t *equeue );
-
-
-/** @} */
-
-PJ_END_DECL
-
-#endif /* __PJ_EQUEUE_H__ */
diff --git a/pjlib/include/pj/os.h b/pjlib/include/pj/os.h
index 439b086..2a57ab8 100644
--- a/pjlib/include/pj/os.h
+++ b/pjlib/include/pj/os.h
@@ -509,6 +509,13 @@
* readers can acquire the mutex, but only a single writer can acquire the
* mutex.
*/
+
+/**
+ * Opaque declaration for reader/writer mutex.
+ * Reader/writer mutex is a classic synchronization object where multiple
+ * readers can acquire the mutex, but only a single writer can acquire the
+ * mutex.
+ */
typedef struct pj_rwmutex_t pj_rwmutex_t;
/**
diff --git a/pjlib/include/pj/string.h b/pjlib/include/pj/string.h
index a8c39f6..5c2cc25 100644
--- a/pjlib/include/pj/string.h
+++ b/pjlib/include/pj/string.h
@@ -455,7 +455,7 @@
* @param dst The destination string.
* @param src The source string.
*/
-PJ_IDECL(void) pj_strcat2(pj_str_t *dst, const char *str);
+PJ_IDECL(void) pj_strcat2(pj_str_t *dst, const char *src);
/**
diff --git a/pjlib/include/pj/types.h b/pjlib/include/pj/types.h
index d471428..5a27551 100644
--- a/pjlib/include/pj/types.h
+++ b/pjlib/include/pj/types.h
@@ -313,7 +313,7 @@
/**
* Swap the byte order of an 32bit data.
*
- * @param val16 The 32bit data.
+ * @param val32 The 32bit data.
*
* @return An 32bit data with swapped byte order.
*/
diff --git a/pjlib/include/pj/unicode.h b/pjlib/include/pj/unicode.h
index e70f5fb..e19b1da 100644
--- a/pjlib/include/pj/unicode.h
+++ b/pjlib/include/pj/unicode.h
@@ -22,6 +22,12 @@
#include <pj/types.h>
+/**
+ * @defgroup PJ_UNICODE Unicode Support
+ * @ingroup PJ_MISC
+ * @{
+ */
+
PJ_BEGIN_DECL
@@ -60,20 +66,64 @@
#if defined(PJ_NATIVE_STRING_IS_UNICODE) && PJ_NATIVE_STRING_IS_UNICODE!=0
+/**
+ * This macro is used to declare temporary Unicode buffer for ANSI to
+ * Unicode conversion, and should be put in declaration section of a block.
+ * When PJ_NATIVE_STRING_IS_UNICODE macro is not defined, this
+ * macro will expand to nothing.
+ */
# define PJ_DECL_UNICODE_TEMP_BUF(buf,size) wchar_t buf[size];
+
+/**
+ * This macro will convert ANSI string to native, when the platform's
+ * native string is Unicode (PJ_NATIVE_STRING_IS_UNICODE is non-zero).
+ */
# define PJ_STRING_TO_NATIVE(s,buf,max) pj_ansi_to_unicode( \
s, strlen(s), \
buf, max)
+
+/**
+ * This macro is used to declare temporary ANSI buffer for Unicode to
+ * ANSI conversion, and should be put in declaration section of a block.
+ * When PJ_NATIVE_STRING_IS_UNICODE macro is not defined, this
+ * macro will expand to nothing.
+ */
# define PJ_DECL_ANSI_TEMP_BUF(buf,size) char buf[size];
+
+
+/**
+ * This macro will convert Unicode string to ANSI, when the platform's
+ * native string is Unicode (PJ_NATIVE_STRING_IS_UNICODE is non-zero).
+ */
# define PJ_NATIVE_TO_STRING(cs,buf,max) pj_unicode_to_ansi( \
cs, wcslen(cs), \
buf, max)
#else
+/**
+ * This macro is used to declare temporary Unicode buffer for ANSI to
+ * Unicode conversion, and should be put in declaration section of a block.
+ * When PJ_NATIVE_STRING_IS_UNICODE macro is not defined, this
+ * macro will expand to nothing.
+ */
# define PJ_DECL_UNICODE_TEMP_BUF(var,size)
+/**
+ * This macro will convert ANSI string to native, when the platform's
+ * native string is Unicode (PJ_NATIVE_STRING_IS_UNICODE is non-zero).
+ */
# define PJ_STRING_TO_NATIVE(s,buf,max) ((char*)s)
+/**
+ * This macro is used to declare temporary ANSI buffer for Unicode to
+ * ANSI conversion, and should be put in declaration section of a block.
+ * When PJ_NATIVE_STRING_IS_UNICODE macro is not defined, this
+ * macro will expand to nothing.
+ */
# define PJ_DECL_ANSI_TEMP_BUF(buf,size)
+/**
+ * This macro will convert Unicode string to ANSI, when the platform's
+ * native string is Unicode (PJ_NATIVE_STRING_IS_UNICODE is non-zero).
+ */
# define PJ_NATIVE_TO_STRING(cs,buf,max) ((char*)(const char*)cs)
#endif
@@ -82,5 +132,9 @@
PJ_END_DECL
+/*
+ * @}
+ */
+
#endif /* __PJ_UNICODE_H__ */