/* $Id$ */ /* * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 Benny Prijono * * 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 */ /** * @file doxygen.h * @brief PJSIP Doxygen's mainpage. */ /*////////////////////////////////////////////////////////////////////////// */ /* INTRODUCTION PAGE */ /** \n @mainpage PJSIP - Open Source SIP Stack \n \n @section intro_sec Introduction PJSIP is an Open Source SIP prototol stack, designed to be very small in footprint, have high performance, and very flexible. @subsection hist_sec History PJSIP has been actively developed since 2003, but its history goes well beyond that. The author has been developing SIP stack since 1999 during RFC 2543 era, and after several experimentation with different approaches in the programming (the first stack actually was in C++!), and also with the evolution of the SIP protocol itself, the current/third generation of PJSIP (the 0.2.9 version is the second generation) can be considered as pretty stable in term of design, and should incorporate all design considerations (and implementation tricks!) that have been learned over the years. Of course only time will tell if this statement can still be held true in the future. \n \n @section pjsipgetting_started Getting Started PJSIP consists of multiple levels of APIs, which each of them layered on top of another. Because of this, new readers may find it a bit difficult to find the place to start. In general, I think perhaps I can recommend two approaches on using PJSIP. \n @subsection getting_started_high Using PJSUA API @ref PJSUA_LIB wraps together all SIP components and media into a high level API, suitable for creating typical SIP user agent applications. It features easy to use API for: - multiple client registration (accounts), - high level SIP and media session (calls), - buddy list, presence and instant messaging, - powerful and very easy to use media manipulation, while maintaining some space for customization (custom SIP transport, custom SIP media, etc.) needed by some types of applications. @ref PJSUA_LIB is also aimed to be able to run on devices such as PDA or mobile phones, by carefully allowing application to set the appropriate threading strategy and memory limits (number of calls, media ports, etc.). However, @ref PJSUA_LIB may not be the most suitable API for some types of applications, since it is directed towards an easy to use API. For more more advanced use, you may better implement the application by using PJSIP + PJMEDIA directly, as described below. \n @subsection getting_started_pjsip_pjmedia Using PJSIP and PJMEDIA Directly For the ultimate flexibility and power, using PJSIP and PJMEDIA directly is the way to go. The drawback will be, of course, steeper learning curve. However, the following links may provide some useful information: - PJSIP Developer's Guide PDF document is the ultimate guide to understand PJSIP design concept. - there are some samples in pjsip-apps/src/samples directory. - @ref PJSUA_LIB source code may also be useful to see how high level API are implemented with PJSIP/PJMEDIA. - and finally, you can always Use the Source! \n \n @section this_doc About This Document This document contains the reference information about PJSIP. For more in-depth guide (and information in general), readers are encouraged to read the PJSIP Developer's Guide PDF document which can be downloaded from http://www.pjsip.org/docs.htm. \n @subsection doc_how_to_read How to Read This Document For main navigation, please go to Modules link on top of this page. This document was generated with Doxygen from PJSIP header files. \n \n @section pjsip_toc Documentation Contents Click on Modules link on top of this page to get the detailed table of contents. The following are top level sections in the Modules, as laid out in the following diagram: \image html pjsip-arch.jpg "Static Library Layout" Enumerating the static libraries from the bottom: - PJLIB, is the platform abstraction and framework library, on which all other libraries depend, - PJLIB-UTIL, provides auxiliary functions such as text scanning, XML, and STUN, - PJMEDIA is the multimedia framework, - PJMEDIA-CODEC is the placeholder for media codecs, - @ref PJSIP_CORE (PJSIP-CORE) is the very core of the PJSIP library, and contains the SIP @ref PJSIP_ENDPT, which is the owner/manager for all SIP objects in the application, messaging elements, parsing, transport management, module management, and stateless operations, and also contains: - The @ref PJSIP_TRANSACT module inside PJSIP-CORE provides stateful operation, and is the base for higher layer features such as dialogs, - The @ref PJSIP_UA module inside PJSIP-CORE manages dialogs, and supports dialog usages, - @ref PJSIP_SIMPLE (PJSIP-SIMPLE) provides the base SIP event framework (which uses the common/base dialog framework) and implements presence on top of it, and is also used by call transfer functions, - @ref PJSIP_HIGH_UA (PJSIP-UA) is the high level abstraction of INVITE sessions (using the common/base dialog framework). This library also provides SIP client registration and call transfer functionality, - and finally, @ref PJSUA_LIB (PJSUA-LIB) is the highest level of abstraction, which wraps together all above functionalities into high level, easy to use API. */ /** @page page_pjsip_samples PJSIP Samples I wish I could write more samples, but for now here are some samples or working applications that are available from the source tree: - @ref page_pjsip_sample_sipstateless_c\n This is about the simplest SIP application with PJSIP, all it does is respond all incoming requests with 501 (Not Implemented) response statelessly. - @ref page_pjsip_sample_simple_ua_c\n This is a very simple SIP User Agent application that only use PJSIP (without PJSIP-UA). It's able to make and receive call, and play media to the sound device. - @ref page_pjsip_sample_simple_pjsuaua_c\n Very simple SIP User Agent with registration, call, and media, using PJSUA-API, all in under 200 lines of code. - @ref page_pjsip_samples_pjsua\n This is the reference implementation for PJSIP and PJMEDIA. PJSUA is a console based application, designed to be simple enough to be readble, but powerful enough to demonstrate all features available in PJSIP and PJMEDIA.\n Screenshot on WinXP: \image html pjsua.jpg "pjsua on WinXP" - @ref page_pjmedia_samples_siprtp_c\n This is a useful program (integrated with PJSIP) to actively measure the network quality/impairment parameters by making one or more SIP calls (or receiving one or more SIP calls) and display the network impairment of each stream direction at the end of the call. The program is able to measure network quality parameters such as jitter, packet lost/reorder/duplicate, round trip time, etc.\n Note that the remote peer MUST support RTCP so that network quality of each direction can be calculated. Using siprtp for both endpoints is recommended.\n Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP" - @ref page_pjsip_perf_c\n This sample contains a complete implementation of a SIP performance measurement tool. Unlike other tool such SIPp, pjsip-perf is geared more towards finding the performance of an endpoint by flooding the endpoint with some requests and time the completion of the requests.\n Screenshots on Linux console: \image html pjsip-perf.jpg "pjsip-perf screenshot on Linux" */ /** * \page page_pjsip_samples_pjsua PJSUA * * This is the reference implementation for PJSIP and PJMEDIA. * PJSUA is a console based application, designed to be simple enough * to be readble, but powerful enough to demonstrate all features * available in PJSIP and PJMEDIA. * * This file is pjsip-apps/src/pjsua/pjsua_app.c * * Screenshot on WinXP: \image html pjsua.jpg "pjsua on WinXP" * * \includelineno pjsua_app.c */ /** * \page page_pjsip_sample_simple_ua_c Samples: Simple UA * * This is a very simple SIP User Agent application that only use PJSIP * (without PJSIP-UA). It's able to make and receive call, and play * media to the sound device. * * \includelineno simpleua.c */ /** * \page page_pjsip_sample_simple_pjsuaua_c Samples: Simple PJSUA * * Very simple SIP User Agent with registration, call, and media, all * in under 200 lines of code. * * \includelineno simple_pjsua.c */ /** * \page page_pjsip_sample_sipstateless_c Samples: Stateless SIP Endpoint * * This is about the simplest SIP application with PJSIP, all it does is * respond all incoming requests with 501 (Not Implemented) response * statelessly. * * \includelineno sipstateless.c */ /** * \page page_pjmedia_samples_siprtp_c Samples: siprtp - SIP with RTCP Quality Monitoring * * This source is an example to demonstrate using SIP and RTP/RTCP framework * to measure the network quality/impairment from the SIP call. This * program can be used to make calls or to receive calls from other * SIP endpoint (or other siprtp program), and to display the media * quality statistics at the end of the call. * * Note that the remote peer must support RTCP. * * The layout of the program has been designed so that custom reporting * can be generated instead of plain human readable text. * * The source code of the file is pjsip-apps/src/samples/siprtp.c * * Screenshots on WinXP: \image html siprtp.jpg * * \includelineno siprtp.c */ /** * \page page_pjsip_perf_c Samples: pjsip-perf - SIP Performance Benchmarking Tool * * This sample contains a complete implementation of a SIP performance * measurement tool. Unlike other tool such SIPp, pjsip-perf is geared * more towards finding the performance of an endpoint by flooding the * endpoint with some requests and time the completion of the requests. * * The source code of the file is pjsip-apps/src/samples/pjsip-perf.c * * Screenshots on Linux console: \image html pjsip-perf.jpg * * \includelineno pjsip-perf.c */