doxygen.h

一个开源的sip源代码

/* $Id: doxygen.h 974 2007-02-19 01:13:53Z bennylp $ */
/* 
 * Copyright (C)2003-2007 Benny Prijono <[e-mail]>
 *
 * 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_DOXYGEN_H__
#define __PJ_DOXYGEN_H__

/**
 * @file doxygen.h
 * @brief Doxygen's mainpage.
 */

/*////////////////////////////////////////////////////////////////////////// */
/*
	INTRODUCTION PAGE
 */

/**
 * @mainpage Welcome to PJLIB!
 *
 * @section intro_sec What is PJLIB
 *
 * PJLIB is an Open Source, small footprint framework library written in C for 
 * making scalable applications. Because of its small footprint, it can be used
 * in embedded applications (we hope so!), but yet the library is also aimed for
 * facilitating the creation of high performance protocol stacks.
 *
 * PJLIB is released under GPL terms.
 *
 * @section download_sec Download
 *
 * PJLIB and all documentation can be downloaded from 
 * http://www.pjsip.org.
 *
 *
 * @section how_to_use_sec About This Documentation
 *
 * This document is generated directly from PJLIB source file using
 * \a doxygen (http://www.doxygen.org). Doxygen is a great (and free!) 
 * tools for generating such documentation.
 *
 * @subsection doc_ver_subsec Version
 *
 * This document corresponds to PJLIB version 0.5.10.
 *
 *
 * @subsection find_samples_subsec How to Read This Document
 *
 * This documentation is laid out more to be a reference guide instead
 * of tutorial, therefore first time users may find it difficult to
 * grasp PJLIB by reading this document alone.
 *
 * However, we've tried our best to make this document easy to follow.
 * For first time users, we would suggest that you follow these steps
 * when reading this documentation:
 *
 *  - continue reading this introduction chapter. At the end of this
 *    chapter, you'll find section called \ref pjlib_fundamentals_sec
 *    which should guide you to understand basic things about PJLIB.
 *
 *  - find information about specific features that you want to use
 *    in PJLIB. Use the <b>Module Index</b> to find out about all 
 *    features in PJLIB (if you're browsing the HTML documentation,
 *    click on the \a Module link on top of the page, or if you're
 *    reading the PDF documentation, click on \a Module \a Documentation
 *    on the navigation pane on the left).
 *
 * @subsection doc_organize_sec How To's
 *
 * Please find below links to specific tasks that you probably
 * want to do:
 *
 *  - <b>How to Build PJLIB</b>
 *\n
 * Please refer to \ref pjlib_build_sys_pg page for more information.
 *
 *  - <b>How to Use PJLIB in My Application</b>
 *\n
 * Please refer to \ref configure_app_sec for more information.
 *
 *  - <b>How to Port PJLIB</b>
 *\n
 * Please refer to \ref porting_pjlib_pg page.
 *
 *  - <b>Where to Read Samples Documentation</b>
 *\n
 * Most of the modules provide link to the corresponding sample file.
 * Alternatively, to get the list of all examples, you can click on 
 * <b>Related Pages</b> on the top of HTML document or on 
 * <b>PJLIB Page Documentation</b> on navigation pane of your PDF reader.
 *
 *  - <b>How to Submit Code to PJLIB Project</b>
 *\n
 * Please read \ref pjlib_coding_convention_page before submitting
 * your code. Send your code as patch against current Subversion tree
 * to the appropriate mailing list.
 *
 *
 * @section features_sec Features
 *
 * @subsection open_source_feat It's Open Source!
 *
 * PJLIB is currently released on GPL license, but other arrangements
 * can be made with the author.
 *
 * @subsection extreme_portable_feat Extreme Portability
 *
 * PJLIB is designed to be extremely portable. It can run on any kind
 * of processors (16-bit, 32-bit, or 64-bit, big or little endian, single
 * or multi-processors) and operating systems. Floating point or no
 * floating point. Multi-threading or not.
 * It can even run in environment where no ANSI LIBC is available. 
 *
 * Currently PJLIB is known to run on these platforms:
 *  - Win32/x86 (Win95/98/ME, NT/2000/XP/2003, mingw).
 *  - arm, WinCE and Windows Mobile.
 *  - Linux/x86, (user mode and as <b>kernel module</b>(!)).
 *  - Linux/alpha
 *  - Solaris/ultra.
 *  - MacOS X/powerpc
 *  - RTEMS (x86 and powerpc).
 *
 * And efforts is under way to port PJLIB on:
 *  - Symbian OS
 *
 *
 * @subsection small_size_feat Small in Size
 *
 * One of the primary objectives is to have library that is small in size for
 * typical embedded applications. As a rough guidance, we aim to keep the 
 * library size below 100KB for it to be considered as small.
 * As the result, most of the functionalities in the library can be tailored
 * to meet the requirements; user can enable/disable specific functionalities
 * to get the desired size/performance/functionality balance.
 *
 * For more info, please see @ref pj_config.
 *
 *
 * @subsection big_perform_feat Big in Performance
 *
 * Almost everything in PJLIB is designed to achieve the highest possible
 * performance out of the target platform. 
 *
 *
 * @subsection no_dyn_mem No Dynamic Memory Allocations
 *
 * The central idea of PJLIB is that for applications to run as fast as it can,
 * it should not use \a malloc() at all, but instead should get the memory 
 * from a preallocated storage pool. There are few things that can be 
 * optimized with this approach:
 *
 *  - \a alloc() is a O(1) operation.
 *  - no mutex is used inside alloc(). It is assumed that synchronization 
 *    will be used in higher abstraction by application anyway.
 *  - no \a free() is required. All chunks will be deleted when the pool is 
 *    destroyed.
 *
 * The performance gained on some systems can be as high as 30x speed up
 * against \a malloc() and \a free() on certain configurations, but of
 * course your mileage may vary. 
 *
 * For more information, see \ref PJ_POOL_GROUP
 *
 * 
 * @subsection os_abstract_feat Operating System Abstraction
 *
 * PJLIB has abstractions for features that are normally not portable 
 * across operating systems: 
 *  - @ref PJ_THREAD
 *\n
 *    Portable thread manipulation.
 *  - @ref PJ_TLS
 *\n
 *    Storing data in thread's private data.
 *  - @ref PJ_MUTEX
 *\n
 *    Mutual exclusion protection.
 *  - @ref PJ_SEM
 *\n
 *    Semaphores.
 *  - @ref PJ_ATOMIC
 *\n
 *    Atomic variables and their operations.
 *  - @ref PJ_CRIT_SEC
 *\n
 *    Fast locking of critical sections.
 *  - @ref PJ_LOCK
 *\n
 *    High level abstraction for lock objects.
 *  - @ref PJ_EVENT
 *\n
 *    Event object.
 *  - @ref PJ_TIME
 *\n
 *    Portable time manipulation.
 *  - @ref PJ_TIMESTAMP
 *\n
 *    High resolution time value.
 *  - etc.
 *
 *
 * @subsection ll_network_io_sec Low-Level Network I/O
 *
 * PJLIB has very portable abstraction and fairly complete set of API for
 * doing network I/O communications. At the lowest level, PJLIB provides:
 *
 *  - @ref PJ_SOCK
 *\n
 *    A highly portable socket abstraction, runs on all kind of
 *    network APIs such as standard BSD socket, Windows socket, Linux
 *    \b kernel socket, PalmOS networking API, etc.
 *
 *  - @ref pj_addr_resolve
 *\n
 *    Portable address resolution, which implements #pj_gethostbyname().
 *
 *  - @ref PJ_SOCK_SELECT
 *\n
 *    A portable \a select() like API (#pj_sock_select()) which can be
 *    implemented with various back-end.
 *
 *
 *
 * @subsection timer_mgmt_sec Timer Management
 *
 * A passive framework for managing timer, see @ref PJ_TIMER for more info.
 * There is also function to retrieve high resolution timestamp
 * from the system (see @ref PJ_TIMESTAMP).
 *
 *
 * @subsection data_struct_sec Various Data Structures
 *
 * Various data structures are provided in the library:
 *
 *  - @ref PJ_PSTR
 *  - @ref PJ_ARRAY
 *  - @ref PJ_HASH
 *  - @ref PJ_LIST
 *  - @ref PJ_RBTREE
 *
 *
 * @subsection exception_sec Exception Construct
 *
 * A convenient TRY/CATCH like construct to propagate errors, which by
 * default are used by the @ref PJ_POOL_GROUP "memory pool" and 
 * the lexical scanner in pjlib-util. The exception
 * construct can be used to write programs like below:
 *
 * <pre>
 *    #define SYNTAX_ERROR  1
 *
 *    PJ_TRY {
 *       msg = NULL;
 *       msg = parse_msg(buf, len);
 *    }
 *    PJ_CATCH ( SYNTAX_ERROR ) {
 *       .. handle error ..
 *    }
 *    PJ_END;
 * </pre>
 *
 * Please see @ref PJ_EXCEPT for more information.
 *
 *
 * @subsection logging_sec Logging Facility
 *
 * PJLIB @ref PJ_LOG consists of macros to write logging information to
 * some output device. Some of the features of the logging facility:
 *
 *  - the verbosity can be fine-tuned both at compile time (to control
 *    the library size) or run-time (to control the verbosity of the
 *    information).
 *  - output device is configurable (e.g. stdout, printk, file, etc.)
 *  - log decoration is configurable.
 *
 * See @ref PJ_LOG for more information.
 *
 *
 * @subsection guid_gen_sec Random and GUID Generation
 *
 * PJLIB provides facility to create random string 
 * (#pj_create_random_string()) or globally unique identifier
 * (see @ref PJ_GUID).
 *
 *
 *
 * @section configure_app_sec Configuring Application to use PJLIB
 *
 * @subsection pjlib_compil_sec Building PJLIB
 *
 * Follow the instructions in \ref pjlib_build_sys_pg to build
 * PJLIB.
 *
 * @subsection pjlib_compil_app_sec Building Applications with PJLIB
 *
 * Use the following settings when building applications with PJLIB.
 *
 * @subsubsection compil_inc_dir_sec Include Search Path
 *
 * Add this to your include search path ($PJLIB is PJLIB root directory):
 * <pre>
 *   $PJLIB/include
 * </pre>
 *
 * @subsubsection compil_inc_file_sec Include PJLIB Header
 *
 * To include all PJLIB headers:
 * \verbatim
    #include <pjlib.h>
   \endverbatim
 *
 * Alternatively, you can include individual PJLIB headers like this:
 * \verbatim
     #include <pj/log.h>
     #include <pj/os.h>
  \endverbatim
 *
 *
 * @subsubsection compil_lib_dir_sec Library Path
 *