diff options
Diffstat (limited to 'pjlib')
-rw-r--r-- | pjlib/docs/footer.html | 7 | ||||
-rw-r--r-- | pjlib/docs/header.html | 29 | ||||
-rw-r--r-- | pjlib/include/pj/doxygen.h | 81 | ||||
-rw-r--r-- | pjlib/include/pj/equeue.h | 336 | ||||
-rw-r--r-- | pjlib/include/pj/os.h | 7 | ||||
-rw-r--r-- | pjlib/include/pj/string.h | 2 | ||||
-rw-r--r-- | pjlib/include/pj/types.h | 2 | ||||
-rw-r--r-- | pjlib/include/pj/unicode.h | 54 |
8 files changed, 86 insertions, 432 deletions
diff --git a/pjlib/docs/footer.html b/pjlib/docs/footer.html index 745b54f1..7e7b5529 100644 --- a/pjlib/docs/footer.html +++ b/pjlib/docs/footer.html @@ -1,9 +1,4 @@ -</TD></TR>
-</TABLE>
-
-</td>
-</tr>
-</table>
+ <!--#include virtual="/footer.html" -->
</BODY>
</HTML>
diff --git a/pjlib/docs/header.html b/pjlib/docs/header.html index 8d6db934..a32695a7 100644 --- a/pjlib/docs/header.html +++ b/pjlib/docs/header.html @@ -1,32 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>PJLIB Documentation</title>
-<link href="doxygen.css" rel="stylesheet" type="text/css">
+<link href="/style/style.css" rel="stylesheet" type="text/css">
</head><body>
-
-<TABLE id="MainTable" cellSpacing="0" cellPadding="0" width="100%" border="0">
-<!-- First Row, PJPROJECT logo. -->
-<TR>
- <TD>
- <TABLE id="LogoTable" cellSpacing="0" cellPadding="0" width="100%" border="0">
- <TR>
- <TD><a href="/" target="_top"><IMG src="/images/pjlogo.jpg" border="0"></a></TD>
- <TD> </TD>
- <TD> </TD>
- </TR>
- </TABLE>
- </TD>
-</TR>
-<!-- Second Row, a HR. -->
-<TR>
- <td colspan="3"><hr noshade size="1">
- </td>
-</TR>
-<!-- Third row, main contents. -->
-<TR>
- <TD>
-
-<!-- Main doxygen content -->
-<TABLE border="0">
- <TR><TD width="800" align="left">
+ <!--#include virtual="/header.html" -->
diff --git a/pjlib/include/pj/doxygen.h b/pjlib/include/pj/doxygen.h index 4f14dbad..2d022bb2 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 77374bdb..00000000 --- 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 439b0864..2a57ab87 100644 --- a/pjlib/include/pj/os.h +++ b/pjlib/include/pj/os.h @@ -509,6 +509,13 @@ PJ_DECL(pj_status_t) pj_mutex_destroy(pj_mutex_t *mutex); * 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 a8c39f60..5c2cc251 100644 --- a/pjlib/include/pj/string.h +++ b/pjlib/include/pj/string.h @@ -455,7 +455,7 @@ PJ_IDECL(void) pj_strcat(pj_str_t *dst, const pj_str_t *src); * @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 d471428a..5a275514 100644 --- a/pjlib/include/pj/types.h +++ b/pjlib/include/pj/types.h @@ -313,7 +313,7 @@ PJ_INLINE(pj_int16_t) pj_swap16(pj_int16_t val16) /** * 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 e70f5fb5..e19b1da1 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 @@ PJ_DECL(char*) pj_unicode_to_ansi(const wchar_t *wstr, pj_size_t len, #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_DECL(char*) pj_unicode_to_ansi(const wchar_t *wstr, pj_size_t len, PJ_END_DECL +/* + * @} + */ + #endif /* __PJ_UNICODE_H__ */ |