Changes between Version 2 and Version 3 of pjsip-doc/consider


Ignore:
Timestamp:
Feb 26, 2014 11:33:59 AM (9 years ago)
Author:
ismangil
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • pjsip-doc/consider

    v2 v3  
    2525**Essential:** set your editor to use 8 characters tab size in order to see PJSIP source correctly. 
    2626 
    27 These below are PJSIP coding style. You don't need to follow it unless you are submitting patches to PJSIP: 
    28  
    29 * indentation uses tabs and spaces. Tab size is 8 characters, indentation 4. 
    30 * all public API in header file must be documented in Doxygen format. 
    31 * other than that, we mostly just use `K & R style <http://en.wikipedia.org/wiki/1_true_brace_style#K.26R_style>`_, which is the only correct style anyway. 
     27Detailed below is the PJSIP coding style. You don't need to follow it unless you are submitting patches to PJSIP: 
     28 
     29* Indentation uses tabs and spaces. Tab size is 8 characters, indentation 4. 
     30* All public API in header file must be documented in Doxygen format. 
     31* Apart from that, we mostly just use `K & R style <http://en.wikipedia.org/wiki/1_true_brace_style#K.26R_style>`_, which is the only correct style anyway. 
    3232 
    3333 
    … …  
    4545Windows is supported from Windows 2000 up to the recent Windows 8 and beyond. All features are expected to work. 64bit support was added recently. Development is based on Visual Studio. Considerations for this platform include: 
    4646 
    47 #. because Visual Studio file format keeps changing on every release, we decided to support the lowest denominator, namely Visual Studio 2005. Unfortunately the project upgrade procedure fails on Visual Studio 2010, and we don't have any solution for that. But VS 2008 and VS 20012 work. 
     47#. Because Visual Studio file format keeps changing on every release, we decided to support the lowest denominator, namely Visual Studio 2005. Unfortunately the project upgrade procedure fails on Visual Studio 2010, and we don't have any solution for that. VS 2008 and VS 2012 onwards should work. 
    4848 
    4949MacOS X 
    … …  
    5151All features are expected to work. Considerations include: 
    5252 
    53 #. development with XCode is currently not supported. This is **not** to say that you cannot use XCode, but PJSIP only provides basic Makefiles and if you want to use XCode you'd need to arrange the project yourself. 
     53#. Development with XCode is currently not supported. This is **not** to say that you cannot use XCode, but PJSIP only provides basic Makefiles and if you want to use XCode you'd need to arrange the project yourself. 
    5454#. Mac systems typically provides very good sound device, so we don't expect any problems with audio on Mac.  
    5555 
    … …  
    5858All features are expected to work. Linux considerations: 
    5959 
    60 #. use our native ALSA backend instead of PortAudio because ALSA has less jitter than OSS and our backend is more lightweight than PortAudio 
     60#. Use our native ALSA backend instead of PortAudio because ALSA has less jitter than OSS and our backend is more lightweight than PortAudio 
    6161 
    6262 
    … …  
    6565All features except video are expected to work (video is coming soon!). Considerations for iOS: 
    6666 
    67 #. you need to use TCP transport for SIP for the background feature to work 
     67#. You need to use TCP transport for SIP for the background feature to work 
    6868#. IP change (for example when user is changing access point) is a feature frequently asked by developers and you can find the documentation here: http://trac.pjsip.org/repos/wiki/IPAddressChange 
    69 #. there are some specific issues for iOS 7 and beyond, please see http://trac.pjsip.org/repos/ticket/1697 
    70 #. if SSL is needed, you need to compile OpenSSL for iOS 
     69#. There are some specific issues for iOS 7 and beyond, please see http://trac.pjsip.org/repos/ticket/1697 
     70#. If SSL is needed, you need to compile OpenSSL for iOS 
    7171 
    7272 
    … …  
    7575All features except video are expected to work (video is coming soon!). Considerations for Android: 
    7676 
    77 #. you can only use pjsua2 Java binding for this target 
    78 #. it has been reported that Android audio device is not so good in general, so some audio tuning may be needed. Echo cancellation also needs to be checked 
    79 #. this is also a new platform for us  
     77#. You can only use pjsua2 Java binding for this target. 
     78#. It has been reported that Android audio device is not so good in general, so some audio tuning may be needed. Echo cancellation also needs to be checked. 
     79#. This is also a new platform for us.  
    8080 
    8181 
    8282Symbian 
    8383------- 
    84 Symbian has been supported for a long time but it doesn't get too many attention recently. In general all features (excluding video) are expected to work, but we're not going to do Symbian specific development anymore. Other considerations for Symbian: 
    85  
    86 #. the MDA audio is not very good (it has high latency), so normally you'd want to use Audio Proxy Server (APS) or VoIP Audio Service (VAS) for the audio device, which we support. Using these audio backends will also provide us with high quality echo cancellation as well as low bitrate codecs such as AMR-NB, G.729, and iLBC. But VAS and APS requires purchase of Nokia development certificate to sign the app, and also since APS and VAS only run on specific device type, you need to package the app carefully and manage the deployment to cover various device types. 
    87  
    88  
    89 Blackberry 10 
    90 ------------- 
    91 Blackberry 10 is supported since PJSIP version 2.2. As this is a relatively new platform for us, we are currently listening to developer's feedback regarding the port. But so far it seems to be working well. Some considerations for BB10 platform include: 
     84Symbian has been supported for a long time. In general all features (excluding video) are expected to work, but we're not going to do Symbian specific development anymore. Other considerations for Symbian: 
     85 
     86#. The MDA audio is not very good (it has high latency), so normally you'd want to use Audio Proxy Server (APS) or VoIP Audio Service (VAS) for the audio device, which we support. Using these audio backends will also provide us with high quality echo cancellation as well as low bitrate codecs such as AMR-NB, G.729, and iLBC. But VAS and APS requires purchase of Nokia development certificate to sign the app, and also since APS and VAS only run on specific device type, you need to package the app carefully and manage the deployment to cover various device types. 
     87 
     88 
     89BlackBerry 10 
     90------------- 
     91BlackBerry 10 (BB10) is supported since PJSIP version 2.2. As this is a relatively new platform for us, we are currently listening to developer's feedback regarding the port. But so far it seems to be working well. Some considerations for BB10 platform include: 
    9292 
    9393#. IP change (for example when user is changing access point) is a feature frequently asked by developers and you can find the documentation here: http://trac.pjsip.org/repos/wiki/IPAddressChange 
    … …  
    9696Windows Mobile 
    9797-------------- 
    98 This is the old Windows Mobile platform that is based on WinCE. This platform has been supported for a long time, but doesn't seem to attract any attentions recently. We expect all features except video to work, but there may be some errors every now and then because this target is not actively maintained. No new development will be done for this platform. 
     98This is the old Windows Mobile platform that is based on WinCE. This platform has been supported for a long time. We expect all features except video to work, but there may be some errors every now and then because this target is not actively maintained. No new development will be done for this platform. 
    9999 
    100100Other considerations for Windows Mobile platform are: 
    101101 
    102 #. the quality of audio device on WM varies a lot, and this affects audio latency. Audio latency could go as high as hundreds of millisecond on bad hardware. 
    103 #. echo cancellation could be a problem. We can only use basic echo suppressor due to hardware limitation, and combined with bad quality of audio device, it may cause ineffective echo cancellation. This could be mitigated by setting the audio level to low. 
     102#. The quality of audio device on WM varies a lot, and this affects audio latency. Audio latency could go as high as hundreds of millisecond on bad hardware. 
     103#. Echo cancellation could be a problem. We can only use basic echo suppressor due to hardware limitation, and combined with bad quality of audio device, it may cause ineffective echo cancellation. This could be mitigated by setting the audio level to low. 
    104104 
    105105 
    … …  
    108108Windows Phone 8 (WP8) support is being added to PJSIP version 2.2 and is still under development. Specific considerations for this platform are: 
    109109 
    110 #. WP8 governs specific interaction with WP8 GUI and framework that needs to be followed by application in order to make VoIP call work seamlessly on the device. Some lightweight process will be created by WP8 framework in order for background call to work and PJSIP needs to put it's background processing in this process's context. Currently this feature is under development. 
     110#. WP8 governs specific interaction with WP8 GUI and framework that needs to be followed by application in order to make VoIP call work seamlessly on the device. Some lightweight process will be created by WP8 framework in order for background call to work and PJSIP needs to put its background processing in this process' context. Currently this feature is under development. 
    111111 
    112112 
    … …  
    116116In general embedded Linux support is similar to Linux and we find no problems with it. We found some specific considerations for embedded Linux as follows: 
    117117 
    118 #. the performance of the audio device is probably the one with most issues, as some development boards have not so descent sound device that has high audio jitter (or burst) and latency. This will affect end to end audio latency and also the performance of the echo canceller. Also we found that ALSA generally works better than OSS, so if you can have ALSA up and running that will be better. Use our native ALSA backend audio device instead of PortAudio since it is simpler and lighter. 
     118#. The performance of the audio device is probably the one with most issues, as some development boards does not have a decent sound device. Typically there is high audio jitter (or burst) and latency. This will affect end to end audio latency and also the performance of the echo canceller. Also we found that ALSA generally works better than OSS, so if you can have ALSA up and running that will be better. Use our native ALSA backend audio device instead of PortAudio since it is simpler and lighter. 
    119119 
    120120 
    121121QNX or Other Posix Embedded OS 
    122122------------------------------ 
    123 This is not part of our officially supported OSes, but users have run PJSIP on QNX and Blackberry 10 is based on QNX too. Since QNX provides Posix API, and maybe by using the settings found in the configure-bb10 script, PJSIP should be able to run on it, but you need to develop PJMEDIA sound device wrapper for your audio device. Other than this, we don't have enough experience to comment on the platform.  
     123This is not part of our officially supported OS platforms, but users have run PJSIP on QNX and BlackBerry 10 is based on QNX too. Since QNX provides Posix API, and maybe by using the settings found in the configure-bb10 script, PJSIP should be able to run on it, but you need to develop PJMEDIA sound device wrapper for your audio device. Other than this, we don't have enough experience to comment on the platform.  
    124124 
    125125 
    … …  
    129129 
    130130 
    131 Porting to Other Embedded OSes 
     131Porting to Other Embedded OS 
    132132------------------------------ 
    133 It is possible to port PJSIP to other embedded OSes or even directly to device without OS and people have done so. In general, the closer resemblance the new OS to existing supported OS, the easier the porting job will be. The good thing is, PJSIP has been made to be very very portable, and system dependent features are localized in PJLIB and PJMEDIA audio device, so the effort is more quantifiable. Once you are able to successfully run *pjlib-test*, you are more or less there with your porting effort. Other than that, if you really want to port PJSIP to new platform, you probably already know what you're doing.  
     133It is possible to port PJSIP to other embedded OS or even directly to device without OS and people have done so. In general, the closer resemblance the new OS to existing supported OS, the easier the porting job will be. The good thing is, PJSIP has been made to be very very portable, and system dependent features are localized in PJLIB and PJMEDIA audio device, so the effort is more quantifiable. Once you are able to successfully run *pjlib-test*, you are more or less there with your porting effort. Other than that, if you really want to port PJSIP to new platform, you probably already know what you're doing.  
    134134 
    135135 
    … …  
    142142At the lowest level we have the individual PJSIP **C** libraries, which consist of PJSIP, PJMEDIA, and PJNATH, with PJLIB-UTIL and PJLIB as support libraries. This level provides the most flexibility, but it's also the hardest to use. The only reason you'd want to use this level is if: 
    143143 
    144 #. you only need the individual library (say, PJNATH) 
    145 #. you need to be very very tight in footprint (say when things need to be measured in Kilobytes instead of Megabytes) 
    146 #. you are **not** developing a SIP client 
     144#. You only need the individual library (say, PJNATH) 
     145#. You need to be very very tight in footprint (say when things need to be measured in Kilobytes instead of Megabytes) 
     146#. You are **not** developing a SIP client 
    147147 
    148148Use the corresponding PJSIP, PJMEDIA, PJNATH manuals from http://trac.pjsip.org/repos/ for information on how to use the libraries. If you use PJSIP, the PJSIP Developer's Guide (PDF) from that page provides in-depth information about PJSIP library.   
    … …  
    154154Motivations for using PJSUA-LIB library includes: 
    155155 
    156 #. developing client application (PJSUA-LIB is optimized for developing client app) 
    157 #. better efficiency than higher level API 
     156#. Developing client application (PJSUA-LIB is optimized for developing client app) 
     157#. Better efficiency than higher level API 
    158158 
    159159 
    … …  
    162162pjsua2 is a new, objected oriented, C++ API created on top of PJSUA-LIB. The API is different than PJSUA-LIB, but it should be even easier to use and it should have better documentation too (such as this book). The pjsua2 API removes most cruxes typically associated with PJSIP, such as the pool and pj_str_t, and add new features such as object persistence so you can save your configs to a file, for example. All data structures are rewritten for more clarity.  
    163163 
    164 A C++ application can use pjsua2 natively, while at the same time still has access to the lower level objects if it needs to. This means that the C++ application should not loose any information from using the C++ abstraction, compared to if it is using PJSUA-LIB directly. The C++ application also should not loose the ability to extend the library. It would still be able to register a custom PJSIP module, pjmedia_port, pjmedia_transport, and so on. 
     164A C++ application can use pjsua2 natively, while at the same time still has access to the lower level objects if it needs to. This means that the C++ application should not lose any information from using the C++ abstraction, compared to if it is using PJSUA-LIB directly. The C++ application also should not lose the ability to extend the library. It would still be able to register a custom PJSIP module, pjmedia_port, pjmedia_transport, and so on. 
    165165 
    166166Benefits of using pjsua2 C++ API include: 
    167167 
    168 #. cleaner object oriented API 
    169 #. uniform API for higher level language such as Java and Python 
    170 #. persistence API 
    171 #. the ability to access PJSUA-LIB and lower level libraries when needed (including the ability to extend the libraries, for example creating custom PJSIP module, pjmedia_port, pjmedia_transport, etc.) 
     168#. Cleaner object oriented API 
     169#. Uniform API for higher level language such as Java and Python 
     170#. Persistence API 
     171#. The ability to access PJSUA-LIB and lower level libraries when needed (including the ability to extend the libraries, for example creating custom PJSIP module, pjmedia_port, pjmedia_transport, etc.) 
    172172 
    173173 
    174174Some considerations on pjsua2 C++ API are: 
    175 #. instead of returning error, the API uses exception for error reporting 
     175#. Instead of returning error, the API uses exception for error reporting 
    176176#. pjsua2 uses standard C++ library 
    177 #. the performance penalty due to the API abstraction should be negligible on typical modern device 
     177#. The performance penalty due to the API abstraction should be negligible on typical modern device 
    178178 
    179179