doxygen.h

一个开源SIP协议栈

 * Add this to your library search path:
 * <pre>
 *   $PJLIB/lib
 * </pre>
 *
 * Then add the appropriate PJLIB library to your link specification. For
 * example, you would add \c libpj-i386-linux-gcc.a when you're building
 * applications in Linux.
 *
 *
 * @subsection pjlib_fundamentals_sec Principles in Using PJLIB
 *
 * Few things that you \b MUST do when using PJLIB, to make sure that
 * you create trully portable applications.
 *
 * @subsubsection call_pjlib_init_sec Call pj_init()
 *
 * Before you do anything else, call \c pj_init(). This would make sure that
 * PJLIB system is properly set up.
 *
 * @subsubsection no_ansi_subsec Do NOT Use ANSI C
 *
 * Contrary to popular teaching, ANSI C (and LIBC) is not the most portable
 * library in the world, nor it's the most ubiquitous. For example, LIBC
 * is not available in Linux kernel. Also normally LIBC will be excluded
 * from compilation of RTOSes to reduce size.
 *
 * So for maximum portability, do NOT use ANSI C. Do not even try to include
 * any other header files outside <include/pj>. Stick with the functionalities
 * provided by PJLIB. 
 *
 *
 * @subsubsection string_rep_subsubsec Use pj_str_t instead of C Strings
 *
 * PJLIB uses pj_str_t instead of normal C strings. You SHOULD follow this
 * convention too. Remember, ANSI string-h is not always available. And
 * PJLIB string is faster!
 *
 * @subsubsection mem_alloc_subsubsec Use Pool for Memory Allocations
 *
 * You MUST NOT use \a malloc() or any other memory allocation functions.
 * Use PJLIB @ref PJ_POOL_GROUP instead! It's faster and most portable.
 *
 * @subsection logging_subsubsec Use Logging for Text Display
 *
 * DO NOT use <stdio.h> for text output. Use PJLIB @ref PJ_LOG instead.
 *
 *
 * @section porting_pjlib_sec0 Porting PJLIB
 *
 * Please see \ref porting_pjlib_pg page on more information to port
 * PJLIB to new target.
 *
 * @section enjoy_sec Enjoy Using PJLIB!
 *
 * We hope that you find PJLIB usefull for your application. If you
 * have any questions, suggestions, critics, bug fixes, or anything
 * else, we would be happy to hear it.
 *
 * Enjoy using PJLIB!
 *
 * Benny Prijono < bennylp at pjsip dot org >
 */



/*////////////////////////////////////////////////////////////////////////// */
/*
         CODING CONVENTION
 */

/**
 * @page pjlib_coding_convention_page Coding Convention
 *
 * Before you submit your code/patches to be included with PJLIB, you must
 * make sure that your code is compliant with PJLIB coding convention.
 * <b>This is very important!</b> Otherwise we would not accept your code.
 *
 * @section coding_conv_editor_sec Editor Settings
 *
 * The single most important thing in the whole coding convention is editor 
 * settings. It's more important than the correctness of your code (bugs will
 * only crash the system, but incorrect tab size is mental!).
 *
 * Kindly set your editor as follows:
 *  - tab size to \b 8.
 *  - indentation to \b 4.
 *
 * With \c vi, you can do it with:
 * <pre>
 *  :se ts=8
 *  :se sts=4
 * </pre>
 *
 * You should replace tab with eight spaces.
 *
 * @section coding_conv_detail_sec Coding Style
 *
 * Coding style MUST strictly follow K&R style. The rest of coding style
 * must follow current style. You SHOULD be able to observe the style
 * currently used by PJLIB from PJLIB sources, and apply the style to your 
 * code. If you're not able to do simple thing like to observe PJLIB
 * coding style from the sources, then logic dictates that your ability to
 * observe more difficult area in PJLIB such as memory allocation strategy, 
 * concurrency, etc is questionable.
 *
 * @section coding_conv_comment_sec Commenting Your Code
 *
 * Public API (e.g. in header files) MUST have doxygen compliant comments.
 *
 */


/*////////////////////////////////////////////////////////////////////////// */
/*
	BUILDING AND INSTALLING PJLIB
 */



/**
 * @page pjlib_build_sys_pg Building, and Installing PJLIB
 *
 * @section build_sys_install_sec Build and Installation
 *
 * \note
 * <b>The most up-to-date information on building and installing PJLIB
 *  should be found in the website, under "Getting Started" document.
 *  More over, the new PJLIB build system is now based on autoconf,
 *  so some of the information here might not be relevant anymore 
 *  (although most still are, since the autoconf script still use
 *  the old Makefile system as the backend).</b>
 *
 * @subsection build_sys_install_win32_sec Visual Studio
 *
 * The PJLIB Visual Studio workspace supports the building of PJLIB
 * for Win32 target. Although currently only the Visual Studio 6 Workspace is
 * actively maintained, developers with later version of Visual Studio
 * can easily imports VS6 workspace into their IDE.
 *
 * To start building PJLIB projects with Visual Studio 6 or later, open
 * the \a workspace file in the corresponding \b \c build directory. You have
 * several choices on which \a dsw file to open:
 \verbatim
  $PJPROJECT/pjlib/build/pjlib.dsw
  $PJPROJECT/pjsip/build/pjsip.dsw
 ..etc
 \endverbatim
 *
 * 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.
 *
 *
 * @subsubsection config_site_create_vc_sec Create config_site.h
 *
 * The file <tt><b>$PJPROJECT/pjlib/include/pj/config_site.h</b></tt>
 * is supposed to contain configuration that is specific to your site/target.
 * This file is not part of PJLIB, so you must create it yourself. Normally
 * you just need to create a blank file.
 *
 * The reason why it's not included in PJLIB is so that you would not accidently
 * overwrite your site configuration.
 *
 * If you fail to do this, Visual C will complain with error like: 
 *
 * <b>"fatal error C1083: Cannot open include file: 'pj/config_site.h': No such file 
 * or directory"</b>.
 *
 * @subsubsection build_vc_subsubsec Build the Projects
 *
 * Just hit the build button!
 *
 *
 * @subsection build_sys_install_unix_sec Make System
 *
 * For other targets, PJLIB provides a rather comprehensive build system
 * that uses GNU \a make (and only GNU \a make will work). 
 * Currently, the build system supports building * PJLIB for these targets:
 *  - i386/Win32/mingw
 *  - i386/Linux
 *  - i386/Linux (kernel)
 *  - alpha/linux
 *  - sparc/SunOS
 *  - etc..
 *
 *
 * @subsubsection build_req_sec Requirements
 *
 * In order to use the \c make based build system, you MUST have:
 *
 *  - <b>GNU make</b>
 *\n
 *    The Makefiles heavily utilize GNU make commands which most likely
 *    are not available in other \c make system.
 *  - <b>bash</b> shell is recommended.
 *\n
 *    Specificly, there is a command <tt>"echo -n"</tt> which may not work
 *    in other shells. This command is used when generating dependencies
 *    (<tt>make dep</tt>) and it's located in 
 *    <tt>$PJPROJECT/build/rules.mak</tt>.
 *  - <b>ar</b>, <b>ranlib</b> from GNU binutils
 *\n
 *    In your system has different <tt>ar</tt> or <tt>ranlib</tt> (e.g. they
 *    may have been installed as <tt>gar</tt> and <tt>granlib</tt>), then
 *    either you create the relevant symbolic links, <b>or</b> modify
 *    <tt>$PJPROJECT/build/cc-gcc.mak</tt> and rename <tt>ar</tt> and
 *    <tt>ranlib</tt> to the appropriate names.
 *  - <b>gcc</b> to generate dependency.
 *\n
 *    Currently the build system uses <tt>"gcc -MM"</tt> to generate build
 *    dependencies. If <tt>gcc</tt> is not desired to generate dependency,
 *    then either you don't run <tt>make dep</tt>, <b>or</b> edit
 *    <tt>$PJPROJECT/build/rules.mak</tt> to calculate dependency using
 *    your prefered method. (And let me know when you do so so that I can
 *    update the file. :) )
 *
 * @subsubsection build_overview_sec Building the Project
 *
 * Generally, steps required to build the PJLIB are:
 *
 \verbatim
   $ cd /home/user/pjproject
   $ ./configure
   $ touch pjlib/include/pj/config_site.h
   $ make dep
   $ make
 \endverbatim
 *
 * 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 Cross Compilation
 * 
 * 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:
 *	- \c KERNEL_DIR: full path of kernel source tree.
 *	- \c KERNEL_ARCH: kernel ARCH options (e.g. "ARCH=um"), or leave blank
 * 	     for default.
 *	- \c PJPROJECT_DIR: full path of PJPROJECT source tree.
 *
 * Apart from these, there are also additional steps required to build
 * Linux kernel target, which will be explained in \ref linux_kern_target_subsec.
 *
 * @subsubsection build_dir_sec Files in "build" Directory
 *
 * The <tt>*.mak</tt> files in \c $PJPROJECT/build directory are used to specify
 * the configuration for the specified compiler, target machine target 
 * operating system, and host options. These files will be executed
 * (included) by \a make during building process, depending on the values
 * specified in <b>$PJPROJECT/build.mak</b> file.
 *
 * Normally you don't need to edit these files, except when you're porting
 * PJLIB to new target.
 *
 * Below are the description of some files in this directory:
 *
 *  - <tt>rules.mak</tt>: contains generic rules always included during make.
 *  - <tt>cc-gcc.mak</tt>: rules when gcc is used for compiler.
 *  - <tt>cc-vc.mak</tt>: rules when MSVC compiler is used.
 *  - <tt>host-mingw.mak</tt>: rules for building in mingw host.
 *  - <tt>host-unix.mak</tt>: rules for building in Unix/Posix host.
 *  - <tt>host-win32.mak</tt>: rules for building in Win32 command console
 *    (only valid when VC is used).
 *  - <tt>m-i386.mak</tt>: rules when target machine is an i386 processor.
 *  - <tt>m-m68k.mak</tt>: rules when target machine is an m68k processor.
 *  - <tt>os-linux.mak</tt>: rules when target OS is Linux.
 *  - <tt>os-linux-kernel.mak</tt>: rules when PJLIB is to be build as
 *    part of Linux kernel.
 *  - <tt>os-win32.mak</tt>: rules when target OS is Win32.
 *
 *
 * @subsubsection config_site_create_sec Create config_site.h
 *
 * The file <tt><b>$PJPROJECT/pjlib/include/pj/config_site.h</b></tt>
 * is supposed to contain configuration that is specific to your site/target.
 * This file is not part of PJLIB, so you must create it yourself.
 *
 * The reason why it's not included in PJLIB is so that you would not accidently
 * overwrite your site configuration.
 *
 *
 * @subsubsection invoking_make_sec Invoking make
 *
 * Normally, \a make is invoked in \c build directory under each project.
 * For example, to build PJLIB, you would invoke \a make in
 * \c $PJPROJECT/pjlib/build directory like below:
 *
 \verbatim
   $ cd pjlib/build
   $ make
 \endverbatim
 *
 * Alternatively you may invoke <tt>make</tt> in <tt>$PJPROJECT</tt> 
 * directory, to build all projects under that directory (e.g. 
 * PJLIB, PJSIP, etc.).
 *
 *
 * @subsubsection linux_kern_target_subsec Linux Kernel Target
 *
 * \note
 * <b>BUILDING APPLICATIONS IN LINUX KERNEL MODE IS A VERY DANGEROUS BUSINESS.
 * YOU MAY CRASH THE WHOLE OF YOUR SYSTEM, CORRUPT YOUR HARDISK, ETC. PJLIB
 * KERNEL MODULES ARE STILL IN EXPERIMENTAL PHASE. DO NOT RUN IT IN PRODUCTION
 * SYSTEMS OR OTHER SYSTEMS WHERE RISK OF LOSS OF DATA IS NOT ACCEPTABLE.
 * YOU HAVE BEEN WARNED.</b>
 *
 * \note
 * <b>User Mode Linux (UML)</b> provides excellent way to experiment with Linux
 * kernel without risking the stability of the host system. See
 * http://user-mode-linux.sourceforge.net for details.
 *
 * \note
 * I only use <b>UML</b> to experiment with PJLIB kernel modules.
 * <b>I wouldn't be so foolish to use my host Linux machine to experiment
 * with this.</b> 
 *
 * \note
 * You have been warned.