Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; either version 2 of the License, or |
| 9 | * (at your option) any later version. |
| 10 | * |
| 11 | * This program is distributed in the hope that it will be useful, |
| 12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 | * GNU General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License |
| 17 | * along with this program; if not, write to the Free Software |
| 18 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 19 | */ |
| 20 | |
| 21 | /** |
| 22 | * @file doxygen.h |
| 23 | * @brief PJSIP Doxygen's mainpage. |
| 24 | */ |
| 25 | |
| 26 | /*////////////////////////////////////////////////////////////////////////// */ |
| 27 | /* |
| 28 | INTRODUCTION PAGE |
| 29 | */ |
| 30 | |
| 31 | /** |
| 32 | \n |
| 33 | |
| 34 | @mainpage PJSIP - Open Source SIP Stack |
| 35 | |
| 36 | \n |
| 37 | \n |
| 38 | @section intro_sec Introduction |
| 39 | |
| 40 | PJSIP is an Open Source SIP prototol stack, designed to be very small in |
| 41 | footprint, have high performance, and very flexible. |
| 42 | |
| 43 | @subsection hist_sec History |
| 44 | |
| 45 | PJSIP has been actively developed since 2003, but its history goes well |
| 46 | beyond that. The author has been developing SIP stack since 1999 during |
| 47 | RFC 2543 era, and after several experimentation with different approaches |
| 48 | in the programming (the first stack actually was in C++!), and also with |
| 49 | the evolution of the SIP protocol itself, the current/third generation |
| 50 | of PJSIP (the 0.2.9 version is the second generation) can be considered |
| 51 | as pretty stable in term of design, and should |
| 52 | incorporate all design considerations (and implementation tricks!) that |
| 53 | have been learned over the years. Of course only time will tell if this |
| 54 | statement can still be held true in the future. |
| 55 | |
| 56 | |
| 57 | |
| 58 | |
| 59 | \n |
| 60 | \n |
| 61 | @section pjsipgetting_started Getting Started |
| 62 | |
| 63 | PJSIP consists of multiple levels of APIs, which each of them layered on |
| 64 | top of another. Because of this, new readers may find it a bit difficult |
| 65 | to find the place to start. |
| 66 | |
| 67 | In general, I think perhaps I can recommend two approaches on using PJSIP. |
| 68 | |
| 69 | |
| 70 | \n |
| 71 | @subsection getting_started_high Using PJSUA API |
| 72 | |
| 73 | @ref PJSUA_LIB wraps together all SIP components and media into a high level |
| 74 | API, suitable for creating typical SIP user agent applications. It |
| 75 | features easy to use API for: |
| 76 | - multiple client registration (accounts), |
| 77 | - high level SIP and media session (calls), |
| 78 | - buddy list, presence and instant messaging, |
| 79 | - powerful and very easy to use media manipulation, |
| 80 | |
| 81 | while maintaining some space for customization (custom SIP |
| 82 | transport, custom SIP media, etc.) needed by some types of applications. |
| 83 | @ref PJSUA_LIB is also aimed to be able to run on devices such as PDA |
| 84 | or mobile phones, by carefully allowing application to set the appropriate |
| 85 | threading strategy and memory limits (number of calls, media ports, etc.). |
| 86 | |
| 87 | However, @ref PJSUA_LIB may not be the most suitable API for some types |
| 88 | of applications, since it is directed towards an easy to use API. For |
| 89 | more more advanced use, you may better implement the application by using |
| 90 | PJSIP + PJMEDIA directly, as described below. |
| 91 | |
| 92 | |
| 93 | \n |
| 94 | @subsection getting_started_pjsip_pjmedia Using PJSIP and PJMEDIA Directly |
| 95 | |
| 96 | For the ultimate flexibility and power, using PJSIP and PJMEDIA directly |
| 97 | is the way to go. The drawback will be, of course, steeper learning curve. |
| 98 | |
| 99 | However, the following links may provide some useful information: |
| 100 | - <A HREF="/docs.htm">PJSIP Developer's Guide</A> PDF |
| 101 | document is the ultimate guide to understand PJSIP design concept. |
| 102 | - there are some samples in <A HREF="/cgi-bin/viewcvs.cgi/pjproject/trunk/pjsip-apps/src/samples/"> |
| 103 | <b>pjsip-apps/src/samples</b></A> directory. |
| 104 | - @ref PJSUA_LIB source code may also be useful to see how high level |
| 105 | API are implemented with PJSIP/PJMEDIA. |
| 106 | - and finally, you can always <b>Use the Source</b>! |
| 107 | |
| 108 | |
| 109 | |
| 110 | \n |
| 111 | \n |
| 112 | @section this_doc About This Document |
| 113 | |
| 114 | This document contains the reference information about PJSIP. For |
| 115 | more in-depth guide (and information in general), readers are |
| 116 | encouraged to read the <A HREF="/docs.htm"> |
| 117 | <b>PJSIP Developer's Guide</b></A> PDF document |
| 118 | which can be downloaded from http://www.pjsip.org/docs.htm. |
| 119 | |
| 120 | \n |
| 121 | @subsection doc_how_to_read How to Read This Document |
| 122 | |
| 123 | For main navigation, please go to <A HREF="modules.htm"><b>Modules</b></A> |
| 124 | link on top of this page. |
| 125 | |
| 126 | This document was generated with <A HREF="http://www.doxygen.org">Doxygen</A> |
| 127 | from PJSIP header files. |
| 128 | |
| 129 | |
| 130 | \n |
| 131 | \n |
| 132 | @section pjsip_toc Documentation Contents |
| 133 | |
| 134 | Click on <A HREF="modules.htm"><b>Modules</b></A> link on top of this page |
| 135 | to get the detailed table of contents. |
| 136 | |
| 137 | The following are top level sections in the <A HREF="modules.htm"> |
| 138 | <b>Modules</b></A>, as laid out in the following diagram: |
| 139 | |
| 140 | \image html pjsip-arch.jpg "Static Library Layout" |
| 141 | |
| 142 | Enumerating the static libraries from the bottom: |
| 143 | |
| 144 | - <A HREF="/pjlib/docs/main.htm">PJLIB</A>, is the platform abstraction |
| 145 | and framework library, on which all other libraries depend, |
| 146 | |
| 147 | - PJLIB-UTIL, provides auxiliary functions such as text scanning, |
| 148 | XML, and STUN, |
| 149 | |
| 150 | - PJMEDIA is the multimedia framework, |
| 151 | |
| 152 | - PJMEDIA-CODEC is the placeholder for media codecs, |
| 153 | |
| 154 | - @ref PJSIP_CORE (<b>PJSIP-CORE</b>) is the very core of the PJSIP library, |
| 155 | and contains the SIP @ref PJSIP_ENDPT, which is the owner/manager for all |
| 156 | SIP objects in the application, messaging elements, parsing, transport |
| 157 | management, module management, and stateless operations, and also |
| 158 | contains: |
| 159 | |
| 160 | - The @ref PJSIP_TRANSACT module inside <b>PJSIP-CORE</b> provides |
| 161 | stateful operation, and is the base for higher layer features such as |
| 162 | dialogs, |
| 163 | |
| 164 | - The @ref PJSIP_UA module inside <b>PJSIP-CORE</b> manages dialogs, and supports dialog |
| 165 | usages, |
| 166 | |
| 167 | - @ref PJSIP_SIMPLE (<b>PJSIP-SIMPLE</b>) provides the base SIP event framework |
| 168 | (which uses the common/base dialog framework) and implements presence |
| 169 | on top of it, and is also used by call transfer functions, |
| 170 | |
| 171 | - @ref PJSIP_HIGH_UA (<b>PJSIP-UA</b>) is the high level abstraction of INVITE sessions |
| 172 | (using the common/base dialog framework). This library also provides |
| 173 | SIP client registration and call transfer functionality, |
| 174 | |
| 175 | - and finally, @ref PJSUA_LIB (<b>PJSUA-LIB</b>) is the highest level of abstraction, |
| 176 | which wraps together all above functionalities into high level, easy to |
| 177 | use API. |
| 178 | */ |
| 179 | |
| 180 | |
| 181 | /** |
| 182 | @page page_pjsip_samples PJSIP Samples |
| 183 | |
| 184 | I wish I could write more samples, but for now here are some samples or |
| 185 | working applications that are available from the source tree: |
| 186 | |
| 187 | - @ref page_pjsip_sample_sipstateless_c\n |
| 188 | This is about the simplest SIP application with PJSIP, all it does is |
| 189 | respond all incoming requests with 501 (Not Implemented) response |
| 190 | statelessly. |
| 191 | |
| 192 | - @ref page_pjsip_sample_simple_ua_c\n |
| 193 | This is a very simple SIP User Agent application that only use PJSIP |
| 194 | (without PJSIP-UA). It's able to make and receive call, and play |
| 195 | media to the sound device. |
| 196 | |
| 197 | - @ref page_pjsip_sample_simple_pjsuaua_c\n |
| 198 | Very simple SIP User Agent with registration, call, and media, using |
| 199 | PJSUA-API, all in under 200 lines of code. |
| 200 | |
| 201 | - @ref page_pjsip_samples_pjsua\n |
| 202 | This is the reference implementation for PJSIP and PJMEDIA. |
| 203 | PJSUA is a console based application, designed to be simple enough |
| 204 | to be readble, but powerful enough to demonstrate all features |
| 205 | available in PJSIP and PJMEDIA.\n |
| 206 | Screenshot on WinXP: \image html pjsua.jpg "pjsua on WinXP" |
| 207 | |
| 208 | - @ref page_pjmedia_samples_siprtp_c\n |
| 209 | This is a useful program (integrated with PJSIP) to actively measure |
| 210 | the network quality/impairment parameters by making one or more SIP |
| 211 | calls (or receiving one or more SIP calls) and display the network |
| 212 | impairment of each stream direction at the end of the call. |
| 213 | The program is able to measure network quality parameters such as |
| 214 | jitter, packet lost/reorder/duplicate, round trip time, etc.\n |
| 215 | Note that the remote peer MUST support RTCP so that network quality |
| 216 | of each direction can be calculated. Using siprtp for both endpoints |
| 217 | is recommended.\n |
| 218 | Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP" |
| 219 | |
| 220 | - @ref page_pjsip_perf_c\n |
| 221 | This sample contains a complete implementation of a SIP performance |
| 222 | measurement tool. Unlike other tool such SIPp, pjsip-perf is geared |
| 223 | more towards finding the performance of an endpoint by flooding the |
| 224 | endpoint with some requests and time the completion of the requests.\n |
| 225 | Screenshots on Linux console: \image html pjsip-perf.jpg "pjsip-perf screenshot on Linux" |
| 226 | */ |
| 227 | |
| 228 | /** |
| 229 | * \page page_pjsip_samples_pjsua PJSUA |
| 230 | * |
| 231 | * This is the reference implementation for PJSIP and PJMEDIA. |
| 232 | * PJSUA is a console based application, designed to be simple enough |
| 233 | * to be readble, but powerful enough to demonstrate all features |
| 234 | * available in PJSIP and PJMEDIA. |
| 235 | * |
| 236 | * This file is pjsip-apps/src/pjsua/pjsua_app.c |
| 237 | * |
| 238 | * Screenshot on WinXP: \image html pjsua.jpg "pjsua on WinXP" |
| 239 | * |
| 240 | * \includelineno pjsua_app.c |
| 241 | */ |
| 242 | |
| 243 | /** |
| 244 | * \page page_pjsip_sample_simple_ua_c Samples: Simple UA |
| 245 | * |
| 246 | * This is a very simple SIP User Agent application that only use PJSIP |
| 247 | * (without PJSIP-UA). It's able to make and receive call, and play |
| 248 | * media to the sound device. |
| 249 | * |
| 250 | * \includelineno simpleua.c |
| 251 | */ |
| 252 | |
| 253 | /** |
| 254 | * \page page_pjsip_sample_simple_pjsuaua_c Samples: Simple PJSUA |
| 255 | * |
| 256 | * Very simple SIP User Agent with registration, call, and media, all |
| 257 | * in under 200 lines of code. |
| 258 | * |
| 259 | * \includelineno simple_pjsua.c |
| 260 | */ |
| 261 | |
| 262 | /** |
| 263 | * \page page_pjsip_sample_sipstateless_c Samples: Stateless SIP Endpoint |
| 264 | * |
| 265 | * This is about the simplest SIP application with PJSIP, all it does is |
| 266 | * respond all incoming requests with 501 (Not Implemented) response |
| 267 | * statelessly. |
| 268 | * |
| 269 | * \includelineno sipstateless.c |
| 270 | */ |
| 271 | |
| 272 | /** |
| 273 | * \page page_pjmedia_samples_siprtp_c Samples: siprtp - SIP with RTCP Quality Monitoring |
| 274 | * |
| 275 | * This source is an example to demonstrate using SIP and RTP/RTCP framework |
| 276 | * to measure the network quality/impairment from the SIP call. This |
| 277 | * program can be used to make calls or to receive calls from other |
| 278 | * SIP endpoint (or other siprtp program), and to display the media |
| 279 | * quality statistics at the end of the call. |
| 280 | * |
| 281 | * Note that the remote peer must support RTCP. |
| 282 | * |
| 283 | * The layout of the program has been designed so that custom reporting |
| 284 | * can be generated instead of plain human readable text. |
| 285 | * |
| 286 | * The source code of the file is pjsip-apps/src/samples/siprtp.c |
| 287 | * |
| 288 | * Screenshots on WinXP: \image html siprtp.jpg |
| 289 | * |
| 290 | * \includelineno siprtp.c |
| 291 | */ |
| 292 | |
| 293 | /** |
| 294 | * \page page_pjsip_perf_c Samples: pjsip-perf - SIP Performance Benchmarking Tool |
| 295 | * |
| 296 | * This sample contains a complete implementation of a SIP performance |
| 297 | * measurement tool. Unlike other tool such SIPp, pjsip-perf is geared |
| 298 | * more towards finding the performance of an endpoint by flooding the |
| 299 | * endpoint with some requests and time the completion of the requests. |
| 300 | * |
| 301 | * The source code of the file is pjsip-apps/src/samples/pjsip-perf.c |
| 302 | * |
| 303 | * Screenshots on Linux console: \image html pjsip-perf.jpg |
| 304 | * |
| 305 | * \includelineno pjsip-perf.c |
| 306 | */ |
| 307 | |