Changes between Version 1 and Version 2 of FAQ


Ignore:
Timestamp:
Sep 23, 2007 5:57:09 PM (17 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FAQ

    v1 v2  
    11= PJSIP FAQ = 
    22 
    3 Here you can find answers to some of the most frequently asked questions about PJSIP. If you have a question not answered on this page, you can ask it on the PJSIP mailing list.  
     3Here you can find answers to some of the most frequently asked questions about PJSIP. If you have a question not answered on this page, you can ask it on the [http://lists.pjsip.org/mailman/listinfo/pjsip_lists.pjsip.org PJSIP mailing list].  
    44 
    55---- 
    … …  
    99== General Questions == #general 
    1010 
    11 === Why isn't PJSIP licensed as (LGPL|MPL|BSD|choose your OSS license here)? === #license 
    12  
    13 (Perry please explain) 
    14  
    15 === What kind of testing do you do on PJSIP? === #testing 
    16  
    17  - unit tests 
    18  - test before release 
    19  - by community 
    20  - !Sipit 
     11=== Why is PJSIP licensed as GPL, and not (LGPL|MPL|BSD|choose your OSS license here)? === #non-gnu 
     12 
     13Basically we agree with FSF on this issue. Quoting the [http://www.gnu.org/licenses/gpl-faq.html GPL FAQ]: 
     14 
     15[http://www.gnu.org/licenses/gpl-faq.html#WhyUseGPL Why should I use the GNU GPL rather than other free software licenses?] 
     16 ''Using the GNU GPL will require that all the [http://www.gnu.org/philosophy/pragmatic.html released improved versions] be free software. This means you can avoid the risk of having to compete with a proprietary modified version of your own work.'' 
     17 
     18We don't want people to take PJSIP, mess it up (erm, improve it), and keep the improvements as proprietary code. On the contrary, we want everybody to enjoy PJSIP and all its improvements, and the only way to make sure of this is by releasing PJSIP as GPL. 
     19 
     20 
     21=== What about the "viral" nature of the GPL? === #gpl-viral 
     22 
     23People often think that using GPL-ed software means that other software linked with the GPL software have to be GPL too, hence GPL is considered as viral. '''That is not exactly true''', especially with PJSIP. When linking with PJSIP, only  your application (that is based on PJSIP) has to be GPL-ed, since it is considered as derived work. Other libraries linked with PJSIP don't have to be GPL, because we specifically allow linking PJSIP with third party libraries, as long as they are listed in [http://www.pjsip.org/licensing.htm Third Party Software] that are allowed to be linked with PJSIP. 
     24 
     25 
     26=== Can I develop closed source products with PJSIP? === #proprietary 
     27 
     28It depends. We use the standard GPL v2 or later for PJSIP, and GPL does allow using GPL-ed code for closed source development, '''as long as the resulting product is not redistributed''' (for example, it is only used for internal purpose). Please see [http://www.gnu.org/licenses/gpl-faq.html GPL FAQ] for more information about what you can/can't do with GPL software. 
     29 
     30Alternatively, we can discuss alternative licensing for PJSIP, please contact support@pjsip.org for details. 
     31 
     32=== What SIP products are compatible with PJSIP? === #compatible 
     33 
     34Basically as PJSIP is based on IETF standards (SIP, RTP/RTCP, STUN, ICE, etc.), so it should be compatible with other standard based products. We and the community are constantly using PJSIP with other open source products such as: 
     35 - [http://www.iptel.org SER],  
     36 - [http://www.openser.org OpenSER], and 
     37 - [http://www.asterisk.org Asterisk].  
     38 
     39We have also heard people successfully done interoperability tests with commercial SIP servers or products, but we don't specificly maintain list of these products. Basically the principle stays the same, as long as they follow the standards, we are confident that PJSIP should be able to communicate with them. 
    2140 
    2241=== Where can I find the latest release of PJSIP? === #latest 
    2342 
    24 SVN. 
    25  
     43The latest PJSIP is always the SVN trunk version. You can find information on how to retrieve PJSIP from SVN in the [http://www.pjsip.org/download.htm PJSIP Download] and [http://www.pjsip.org/using.htm Getting Started] page. 
     44 
     45---- 
    2646 
    2747== Build and Installation Issues == 
    2848 
    29 === I'm having problem building PJSIP === #build-problems 
    30  
    31 See Getting started page 
    32  
    33 === Unable to open "DSound.h" === #dsound 
    34  
    35 Doh! See Getting Started page. 
    36  
     49=== I'm having problem building PJSIP, please help! === #build-problems 
     50 
     51You should check the [http://www.pjsip.org/using.htm Getting Started] page. 
     52 
     53=== I'm getting "Unable to open DSound.h error", please help! === #dsound 
     54 
     55You should really check the [http://www.pjsip.org/using.htm Getting Started] page first. 
     56 
     57---- 
    3758 
    3859== Integration Issues == 
    … …  
    4061=== Can I use the SIP stack with my own media stack? === 
    4162 
    42 Yes 
    43  
    44 === Can I use the media stack only with my own SIP stack? === 
    45  
    46 Yes 
    47  
    48 === How to port PJSIP to system XYZ? === #porting 
    49  
    50 See porting page. 
    51  
     63Sure. The SIP stack (pjsip) and media stack (pjmedia) is independent from one another, and they are only integrated at the higher level user agent library (pjsua-lib). Please see the library architecture diagram on [http://www.pjsip.org/docs.htm PJSIP Documentation] page for reference. 
     64 
     65So yes, you can use the SIP stack (pjsip) without having to use pjmedia, as long as you don't use pjsua-lib. 
     66 
     67 
     68=== Can I use the media stack with my own SIP stack? === 
     69 
     70Yes. Please see above. 
     71 
     72=== What platforms are PJSIP known to run on? === #platforms 
     73 
     74PJSIP runs on many platforms, embedded or non-embedded. Please see the platforms list that it currently supports in [http://www.pjsip.org/sip_media_features.htm#platforms Platform features] page. Apart from the platforms that we maintain ourselves, the community have also been constantly finding new platforms that PJSIP can run on. For now we don't maintain list of platforms that the community have ported PJSIP to, but you can search for them in the mailing list archive. 
     75 
     76 
     77=== How can I port PJSIP to platform XYZ? === #porting 
     78 
     79PJSIP has been designed for ultra-portability, and we have ported PJSIP to exotic platform such as Symbian (long time ago, PJSIP has also been ported to Linux kernel). People even have ported PJSIP to even more exotic platforms such as Nintendo DS and Texas Instrument (TI) DSP. So there is a good chance that PJSIP will be ''port''-able to your platform. 
     80 
     81You can start from the [http://www.pjsip.org/porting.htm Porting] page. For additional information, there is also information on porting [http://www.pjsip.org/sip_symbian.htm PJSIP to Symbian], to emphasize that even on difficult platform like this, PJSIP is still ''port''-able. 
     82 
     83---- 
    5284 
    5385== Audio Questions == #media 
    … …  
    5587=== I'm having problems with no/poor audio (quality), please help! === #audio-problem 
    5688 
    57 Please see BlahBlah for troubleshooting audio problems. 
    58  
    59 === I'm having problems with echo! === #echo 
    60  
    61 AEC doesn't work all the time. 
    62  
    63 === When I try to send DTMF, it fails === #dtmf 
    64  
    65 That's because remote doesn't support RFC 2833. 
    66  
    67 === Outgoing RTP packets are not timed properly === #tx-timing 
    68  
    69 It's because of sound device's clock. 
     89We have created a Wiki page dedicated for troubleshooting all sorts of audio problems, please follow the instructions in http://www.pjsip.org/trac/wiki/sound-problems. If this does not solve your problem, please consult the [http://lists.pjsip.org/mailman/listinfo/pjsip_lists.pjsip.org PJSIP mailing list] 
     90 
     91=== I'm having problems with echo, please help === #echo 
     92 
     93Please see above. 
     94 
     95=== Why does PJSIP refuse to send DTMF to remote? === #rfc-2833 
     96 
     97PJSIP will only send RFC 2833 DTMF to remote if remote has indicated its capability to accept RFC 2833 events in its SDP. This is done by putting this line in the SDP: 
     98 
     99{{{ 
     100a=rtpmap:101 telephone-event/8000 
     101}}} 
     102 
     103Without receiving this capability indication, PJSIP will refuse to send RFC 2833 event, and a call to {{{pjsua_call_dial_dtmf()}}} or {{{pjmedia_session_dial_dtmf()}}} or {{{pjmedia_stream_dial_dtmf()}}} will return error code '''[http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__ERRNO.htm#g043502be6c0961209feade822cdd79b7 PJMEDIA_RTP_EREMNORFC2833]'''. In this case, you can send the [#inband-dtmf DTMF tone inband] instead (see below). 
     104 
     105 
     106=== How can I send inband DTMF tones? === #inband-dtmf 
     107 
     108It's quite easy with [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-LIB] API: 
     109 1. Once you get the call established, create an instance of [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__MF__DTMF__TONE__GENERATOR.htm Tone Generator]. 
     110 1. Register this tone generator to pjsua's conference bridge, by calling [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB__MEDIA.htm#g833528c1019f4ab5c8fb216b4b5f788b pjsua_conf_add_port()]. 
     111 1. ''Connect'' the tone generator to the call, with [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB__MEDIA.htm#g3451304d677e013130dfb9e6b37e3ee6 pjsua_conf_connect()]. 
     112 1. Now instruct the tone generator to ''play'' some DTMF digits ([http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__MF__DTMF__TONE__GENERATOR.htm#gf7920b73983e1e09dfe883cbdd2861ae pjmedia_tonegen_play_digits()]). The digits then will be streamed to the call, and remote endpoint should receive the DTMF tone inband. 
     113 
     114 
     115=== Outgoing RTP transmissions are not timed equally/properly. Why? === #tx-timing 
     116 
     117In PJMEDIA default setup, media flow is normally triggered by the ''clock'' from the audio device. We made this kind of design to ensure that the audio device always gets fed whenever it needs to be fed, and also since this design would work best for DSP devices, where audio flow would be triggered by some kind of (soft) IRQs thus it should provide the best timing source for audio flow (and without needing to have multi-threading capability). 
     118 
     119Unfortunately, not all audio devices provide good timing. Especially in PC world, and also with some uC-Linux based development boards that only support OSS, it is very common to have sound cards that can't provide reliable timing. On these platforms, you will notice that audio frames come in burst rather than one by one and spaced equally. So with 20ms ''ptime'' for example, rather than having one frame every 20ms, these devices would give PJMEDIA three or four frames every 60ms or 80ms. Since RTP packets are transmitted as soon as audio frame is available from the sound card, this would cause PJMEDIA to transmit RTP packets at (what looks like) irregular interval. 
     120 
     121In my opinion, this should be fine, as the remote endpoint should be able to accommodate this with its ''jitter buffer''. 
     122 
     123If you don't like this, and you'd rather want PJMEDIA to transmit RTP packets at good interval, you can install a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__MASTER__PORT.htm master clock port] between sound device and conference bridge, so that the master port will drive the media clock instead. A master clock port uses an internal thread to drive the media flow, so it should provide better timing on most platforms. 
     124 
     125The steps to install master port between sound device and conference bridge are as follows: 
     126 1. Create a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SPLITCOMB.htm splitter/combiner (splitcomb) port]. 
     127 1. Create a reverse phase port on the splitcomb ([http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__SPLITCOMB.htm#gc59338fd9d471a14c06b0f51c2290b68 pjmedia_splitcomb_create_rev_channel()]). 
     128 1. Create the [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__SND__PORT.htm sound device port] as usual. 
     129 1. Connect the sound device port to the splitcomb (use [http://www.pjsip.org/pjmedia/docs/html/group__PJMED__SND__PORT.htm#g046156b765a34e6c640b0534e6b21f9c pjmedia_snd_port_connect()]). 
     130 1. Create a [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__MASTER__PORT.htm master clock port], and specify the splitcomb's reverse channel as the ''upstream'' port, and the [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__CONF.htm conference bridge] as the ''downstream'' port. 
     131 1. Start the master port. 
     132 
     133For example, if you normally ''connect'' the sound device to the conference bridge (the default setup in pjsua-lib) with the code below: 
     134 
     135{{{ 
     136void connect_conf_bridge_to_snd_dev(pj_pool_t *pool, pjmedia_port *conf) 
     137{ 
     138    pjmedia_snd_port *snd; 
     139 
     140    pjmedia_snd_port_create(..., &snd); 
     141    pjmedia_snd_port_connect(snd, conf); 
     142} 
     143}}} 
     144 
     145Then the change required to install master clock between sound device and conference bridge would be something like this: 
     146 
     147{{{ 
     148void connect_conf_bridge_to_snd_dev2(pj_pool_t *pool, pjmedia_port *conf) 
     149{ 
     150    pjmedia_port *splitcomb, *rev; 
     151    pjmedia_snd_port *snd; 
     152    pjmedia_master_port *m; 
     153 
     154    pjmedia_splitcomb_create(pool, CLOCK_RATE, 1, SAMPLES_PER_FRAME, 
     155                             BITS, 0, &splitcomb); 
     156    pjmedia_splitcomb_create_rev_channel(pool, splitcomb, 0, 0, &rev); 
     157     
     158    pjmedia_snd_port_create(..., &snd); 
     159    pjmedia_snd_port_connect(snd, splitcomb); 
     160 
     161    pjmedia_master_port_create(pool, rev, conf, 0, &m); 
     162    pjmedia_master_port_start(m); 
     163} 
     164}}} 
     165 
     166 
     167=== Does PJSIP support G.723 or G.729 codec? === #g729-g723 
     168 
     169Yes and no.  
     170 
     171No, because there is no ready to use G.723/G.729 codec implementation in PJMEDIA. We specifically don't include G.723/G.729 support in our code because G.723/G.729 are both patented and royalty based codecs, so we are quite nervous with the possibility that some lawyers may contact us should we include them in PJMEDIA. So our decision is to include only free and open source codec in PJMEDIA. 
     172 
     173But yes, because you can always add your own codec in PJMEDIA. Please see [#adding-codec Adding a new codec] question below for more info. 
    70174 
    71175=== How to add new codec to PJMEDIA? === #adding-codec 
    72176 
    73 See other codec files. 
     177First of all, read the [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__CODEC.htm Codec Framework] documentation. Then, the easiest is to take other codec source file in {{{pjmedia-codec}}} directory (such as [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia-codec/gsm.c gsm.c]), and replace GSM specific function calls with the functions that are provided by your codec library. 
     178 
     179Once you're finished, you should end up with just two public APIs exported by your codec: the initialization function, and the deinitialization function. 
     180 
     181Then register your codec to PJMEDIA in your application by calling the codec initialization function. After this, your codec should be picked up automagically by the rest of PJMEDIA framework. 
     182 
    74183 
    75184=== How can I manipulate audio samples directly? === #audio-man 
    76185 
    77 Implement a media port.. 
    78  
    79 === I always get "Bad RTP pt error" === #bad-rtp-pt 
    80  
    81 The other endpoint is broken 
    82  
    83 === How can I implement Secure RTP (SRTP)? === #srtp 
    84  
    85 Just implement it 
     186In PJMEDIA, audio frames are sent back and forth between what is called [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__PORT__CONCEPT.htm media port (pjmedia_port)]. So to be able to peek or manipulate audio frames, you need to implement your own media port. 
     187 
     188Implementing media port should be easy. Basically you just need to implement these: 
     189 1. Create your media port structure. 
     190 1. Fill in the media port information to describe your media port (like, the name, clock rate, bits per sample, etc.). Use [http://www.pjsip.org/pjmedia/docs/html/group__PJMEDIA__PORT__INTERFACE.htm#gb3259d2924c7a2243733391f6f8f0a9a pjmedia_port_info_init()] to initialize the port into. 
     191 1. Implement {{{get_frame()}}} callback (of the ''pjmedia_port'') if your media port is a source (that is, your media port feed audio frames to other media ports). 
     192 1. Implement {{{put_frame()}}} callback (of the ''pjmedia_port'') if your media port is a sink (that is, other media ports may feed audio frames to your media port). 
     193 1. Implement {{{on_destroy()}}}, if you need to reclaim resources when the media port is destroyed. 
     194 
     195There are many media port sample implementations in PJMEDIA. 
     196 
     197For source only media ports, samples include: 
     198 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjsip-apps/src/samples/playsine.c playsine.c] from the {{{pjsip-apps/samples}}} directory. 
     199 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/mem_player.c mem_player.c] from pjmedia (media port to playback audio from a buffer). 
     200 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/wav_player.c wav_player.c] from pjmedia (media port to playback audio from WAVE file). 
     201 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/tonegen.c tonegen.c] from pjmedia (media port to generate sine waves/DTMF/multi-frequency tones). 
     202 
     203For sink only media ports, samples include: 
     204 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/mem_capture.c mem_capture.c] from pjmedia (media port to save audio to a buffer). 
     205 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/wav_writer.c wav_writer.c] from pjmedia (media port to save audio to a WAVE file). 
     206 
     207For media ports that manipulates audio and provide both sink and source callbacks: 
     208 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/resample_port.c resample_port.c] from pjmedia (to convert sampling rate) 
     209 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/echo_port.c echo_port.c] from pjmedia (the AEC) 
     210 
     211 
     212=== I always get "Bad RTP pt" error. Why? === #bad-rtp-pt 
     213 
     214From our experience, this can be caused by one of these: 
     215 1. Remote endpoint has agreed to use one codec in the SDP negotiation, but it sends RTP with different codec. This had happened with some old version of a popular but not open source softphone (don't want to name it to protect the innocent). When this happens, the "Bad RTP pt" error message will be printed continuously in the log or screen (basically for every RTP packet!). The remedy in this case was to upgrade that softphone to a new version. 
     216 1. Remote endpoint is sending a comfort noise packet. When this happens, the error message is not printed as often as the other case (maybe once in every few seconds). 
     217 
     218When you encounter this problem, and if upgrading the softphone doesn't solve the problem, you can report this to PJSIP mailing list. When reporting, please include the error log and the complete INVITE message and the 200/OK response (containing the SDP), so that we can analyze which endpoint is behaving badly. 
     219 
     220 
     221=== Does PJSIP support SRTP or ZRTP? If no, how can I implement them? === #srtp-zrtp 
     222 
     223Currently PJMEDIA doesn't support SRTP nor ZRTP, although this has been on our TODO list for sometime now. Fortunately, implementing them is not too difficult, since media transport in PJMEDIA is separated from the stream. 
     224 
     225Have a look at: 
     226 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/transport_udp.c transport_udp.c], the normal UDP media transport, and 
     227 - [http://www.pjsip.org/trac/browser/pjproject/trunk/pjmedia/src/pjmedia/transport_ice.c transport_ice.c], ICE media transport. 
     228 
     229There, it's quite easy to see where RTP/RTCP packets are received (that is in {{{on_rx_rtp()}}}/{{{on_rx_rtcp()}}} respectively) or sent (in {{{transport_send_rtp()}}}/{{{transport_send_rtcp()}}}). So these are the locations where you should call the decryption and encryption function of SRTP/ZRTP. 
     230 
     231Alternatively, there is a cleaner way to plug in SRTP/ZRTP functionality without changing existing code. As mentioned earlier, media transport is separated from stream. They are only ''attached'' to each other in application code (or in pjsua-lib). So then one can build an ''adapter'', which is plugged between the media transport and the stream to do the SRTP/ZRTP stuffs. To the stream, this adapter will look like a media transport, and to existing media transport, this adapter will look like a stream. The benefit of this approach is we can use the same adapter for both kind of media transports, that is the UDP and ICE media transport. 
     232 
     233---- 
    86234 
    87235== Video Questions == 
    … …  
    89237=== Does PJSIP support video? === #video 
    90238 
    91 No 
     239Unfortunately no at the moment. Supporting video has been in our TODO list for long time (more than a year!), but so far we haven't had enough time and commitment to do it. 
    92240 
    93241=== When can I expect PJSIP to support video? === 
    94242 
    95 It will be done when it's done. 
    96  
     243We're not sure. 
     244 
     245=== How can I add video support in PJSIP? === 
     246 
     247Since video stream is independent from audio stream, the simplest "integration" would be to not integrate video with pjmedia at all. In other words, the application would have to manage everything related to video (capture, render, codec, and RTP)  by itself, separate from audio stream which is managed by pjmedia. Maybe you can use the media transports supplied by pjmedia, and the RTP module to pack/unpack RTP packets, to help you up a little bit, but apart from these, basically you'll have to do everything on your own. 
     248 
     249Also some processing needs to be done on the SDP to support video. So basically, for outgoing SDP, application has to add video information in the SDP after the SDP is created, and it has to parse video related information in the incoming SDP by itself. 
     250 
     251And perhaps if synchronization between audio and video is needed, the application then will need to peek the RTP packet coming to the audio stream. This can be done perhaps by modifying the media transport, or by installing media transport ''adapter'' as described in [#srtp-zrtp SRTP/ZRTP] question above. 
     252 
     253---- 
    97254 
    98255== SIP Questions == #sip-questions 
    … …  
    100257=== Does PJSIP support RFC XYZ? === #rfc 
    101258 
    102 See the Features page. 
    103  
    104 === I'm having problem with some SIP scenario === #general-sip 
    105  
    106 Let me see the log file! 
    107  
    108 === Unable to authenticate === #authentication 
    109  
    110 Set your realm correctly, or use "*". 
    111  
    112 === How can I reduce the SIP message size === #sip-msg-size 
    113  
    114 There are few settings to configure... 
    115  
    116 === How can I do IMS authentication? === #ims-auth 
    117  
    118 We don't support this yet. 
     259The best way is to look at the [http://www.pjsip.org/sip_media_features.htm PJSIP Features] page and see if that particular feature is supported by PJSIP. 
     260 
     261=== I'm having problem when calling XYZ, please help me! === #general-sip 
     262 
     263Please report your problem to [http://lists.pjsip.org/mailman/listinfo/pjsip_lists.pjsip.org PJSIP mailing list]. In order for us to help you, please provide the following information: 
     264 1. Please describe in detail what are you trying to accomplish and how do you configure your equipments (for example, do you use proxy? What kind of proxy?). 
     265 1. It would be best to try to reproduce the problem with [http://www.pjsip.org/pjsua.htm pjsua], so that we can also try to reproduce your problem. 
     266 1. In any case, please provide the complete log file. If you use ''pjsua'', you can configure it to write log file with {{{--log-file}}} option. If you use your own application that is based on ''pjsua-lib'', you can write the log by setting {{{pjsua_logging_config.log_filename}}} field. 
     267 
     268 
     269=== I cannot login/REGISTER to my server. It complains about authentication error. === #authentication 
     270 
     271Most likely this is caused by wrong credential in your configuration. The remedy depends on what error was reported by PJSIP. 
     272 
     273For [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__CORE__ERRNO.htm#ga13bf24296c19bece7c0c9af051f89db PJSIP_ENOCREDENTIAL] error: 
     274 - This error is caused by the realm specified in the credential doesn't match the realm challenged by the server in the 401/407 response. If you use PJSIP version 0.7-trunk or PJSIP version 0.7.1 or later, you can put wildcard ("*") as the realm to make PJSIP respond to any realms challenged by the server. If you use older PJSIP, you have to match the realm in the credential with the realm in the challenge. The realm normally would be equal to the domain name, but it doesn't have to. Asterisk, for example, always set the realm to "asterisk". 
     275 
     276For [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__CORE__ERRNO.htm#ga935d4205ae50ad6f18a4df98b90d2f6 PJSIP_EFAILEDCREDENTIAL] error: 
     277 - If you encounter this error, most likely it was caused by a wrong credential. Check if the username and password combination is correct. 
     278 
     279=== With ICE enabled, INVITE packet can exceed MTU/1500 bytes. How can I reduce the message size? === #sip-msg-size 
     280 
     281Please see ticket #342 for info. Basically there are few settings to configure to make PJSIP sends smaller packet: 
     282 1. Configure PJSIP to send compact form of SIP headers, by setting {{{PJSIP_ENCODE_SHORT_HNAME}}} macro to 1 in your {{{config_site.h}}}. This will reduce SIP message size by approximately 50 bytes. 
     283 1. Suppress the inclusion of ''Allow'' header in outgoing requests, by setting {{{PJSIP_INCLUDE_ALLOW_HDR_IN_DLG}}} macro to 0 in {{{config_site.h}}}. This will reduce SIP message size by approximately 86 bytes. 
     284 1. Suppress the inclusion of SDP {{{rtpmap}}} attribute for static payload types, by setting {{{PJMEDIA_ADD_RTPMAP_FOR_STATIC_PT}}} macro to 0 in {{{config_site.h}}}. Note that this setting should not cause bad effects for communication, since SDP {{{rtpmap}}} attributes for static payload types are optional. This will reduce SIP message size by approximately 65 bytes. 
     285 1. Disable RTCP (advertisement) in SDP, by setting {{{PJMEDIA_ADVERTISE_RTCP}}} macro to 0 in {{{config_site.h}}}. When RTCP is disabled, no RTCP packets will be sent or received, and this will cause some RTCP TX statistics (including RTT report) to be unavailable. Other RTCP statistics such as RX statistics, as well as number of TX packets, will still be available since these values are generated locally. Disabling RTCP will reduce SIP message size by approximately 235 bytes for ICE with three candidates. 
     286 1. Last resort, disable some unused network interfaces in your system to reduce the number of ICE candidates advertised in SDP. On Windows for example, it's quite common to have some Loopback network interface, and disabling it doesn't seem to cause (too much) harm. 
     287 
    119288 
    120289=== How can I instantiate multiple PJSIP stacks in my application? === #multi-stack 
    121290 
    122 You don't need to! 
     291You don't need to! This may be necessary with other SIP stacks, but PJSIP inherently supports multiple identities (or accounts) throughout the libraries, so one instance of the stack can be used to perform multiple, separate registration and invite sessions. 
     292 
     293---- 
    123294 
    124295== Performance == 
    125296 
    126 === How can I reduce the CPU usage? === #cpu 
    127  
    128 Optimize it. 
    129  
    130 === I want to build server with PJSUA-LIB === #pjsua-performance 
    131  
    132 Don't. 
     297=== How can I reduce the CPU usage/maximize the performance of my application? === #cpu 
     298 
     299There are few configuration settings to tweak to reduce the CPU usage of the application or to produce the best performance out of pjsip: 
     300 1. '''Echo canceller'''. The software AEC probably is the most CPU intensive module in PJSIP. To reduce the CPU usage, you can shorten the EC tail length to lower value (the {{{pjsua_media_config.ec_tail_len}}} setting), or you can even disable it altogether by setting {{{pjsua_media_config.ec_tail_len}}} to zero. 
     301 1. '''Codec'''. Use low complexity codec such as ''pcmu'' or ''pcma''. When you use ''pcmu'' or ''pcma'', make sure pjmedia chooses the table based implementation, by setting {{{PJMEDIA_HAS_ALAW_ULAW_TABLE}}} macro to 1 (the default is normally enabled, but it may worth double-checking). 
     302 1. '''Avoid resampling'''. Resampling is a CPU intensive process, thus you should avoid it if you can, by choosing uniform clock rate for all media components (sound device, conference bridge, codecs, WAV files, etc.). 
     303 1. '''Logging'''. The default logging level is 5, which provides verbose information just in case some debugging is needed. When absolute performance is needed, you can decrease the logging verbosity level to 3 so that only vital information is displayed. This can be done by, either at compile time by setting {{{PJ_LOG_MAX_LEVEL}}} macro (in {{{config_site.h}}} as usual), or at run-time by calling {{{pj_log_set_level()}}}. 
     304 1. '''Threads'''. Use the optimum number of worker threads in your application. The optimum number would be equal to the number of processors (or processor cores) in the system. 
     305 1. '''Run-time checks'''. All the libraries are equipped with run-time checks to prevent bad parameters from crashing the software. You can disable this feature by setting {{{PJ_ENABLE_EXTRA_CHECK}}} to zero. 
     306 1. '''Stack checks'''. PJLIB is equipped with stack overflow detection. You can disable this feature by setting {{{PJ_OS_HAS_CHECK_STACK}}} to zero. 
     307 1. '''Safe module'''. PJSIP is equipped with mutex protection to protect PJSIP modules from being unregistered while they are still being accessed by PJSIP. If you don't plan to add/remove modules dynamically during run-time, you can disable this protection by setting {{{PJSIP_SAFE_MODULE}}} to zero. 
     308 1. '''Unescape in place'''. By default, PJSIP will make a copy of escaped message sequence before unescaping it. You can configure PJSIP to unescape in place by setting {{{PJSIP_UNESCAPE_IN_PLACE}}} to one. 
     309 1. '''Hash tolower optimization'''. By setting {{{PJ_HASH_USE_OWN_TOLOWER}}} to one, the hash function will convert the key to lower case and calculate the hash value in one loop. 
     310 1. '''Release mode'''. Don't forget to set the appropriate compiler optimization flag, and disable assertion with '''-DNDEBUG'''. 
     311 
     312 
     313=== How can I configure pjsip to serve thousands of calls? === #high-perf 
     314 
     315There are few settings to tweak: 
     316 1. First apply the CPU reduction techniques above to maximize the performance. 
     317 1. By default, PJSIP is configured to handle only 16384 simultaneous SIP transactions and dialogs. You should enlarge this to your requirement, by setting both {{{PJSIP_MAX_TSX_COUNT}}} and {{{PJSIP_MAX_DIALOG_COUNT}}} to the appropriate values (for example, 640*1024-1). 
     318 1. If you plan to support large number of TCP/TLS connections, then increase {{{PJ_IOQUEUE_MAX_HANDLES}}} to some large number (the default is only 64). 
     319 
     320---- 
    133321 
    134322== Footprint == 
    135323 
    136 === How can I reduce the footprint of my application? === #footprint 
    137  
    138 See config_site_sample.h 
    139  
     324=== How can I reduce the footprint and heap usage of my application? === #footprint 
     325 
     326With the default settings, PJSIP is not really optimized for size (nor speed), since the main objective is to have sufficient information for troubleshooting. Taking Windows as reference platform, the executable size of Release build with Visual C++ 6 is as follows: 
     327 
     328{{{ 
     329  pjsua_vc6.exe: file size=749,672 bytes 
     330 
     331      241664 .data 
     332      102400 .rdata 
     333       24576 .reloc 
     334      536576 .text 
     335 
     336  (all numbers in decimal, bytes) 
     337}}} 
     338 
     339'''Note:''' with default settings, pjsua will include PJNATH/ICE implementation as well as many media goodies, which you may not need in your embedded application. Hence the executable size is a bit large for ''pjsua''. 
     340 
     341The heap usage with 2 connected calls using Speex wideband codec and AEC enabled (press '''dd''' in pjsua menu): 
     342 
     343{{{ 
     344>>> dd 
     345.. 
     346  Total    908508 of   1046304 (86 %) used! 
     347.. 
     348}}} 
     349 
     350To reduce the executable size, you can apply the following settings: 
     351 1. '''Reduce logging verbosity'''. The default logging level is 5, which provides verbose information just in case some debugging is needed. You can decrease the logging verbosity level to 3 so that only vital information is displayed, by setting {{{PJ_LOG_MAX_LEVEL}}} macro (in {{{config_site.h}}} as usual). This will reduce executable size by approximately '''28 KB'''. 
     352 1. '''Turn off logging'''. Alternatively you can disable logging altogether, by setting {{{PJ_LOG_MAX_LEVEL}}} to 0. This will reduce executable size by another '''28 KB'''. 
     353 1. '''Disable Speex AEC''', by setting {{{PJMEDIA_HAS_SPEEX_AEC=0}}}, to reduce executable size by '''32 KB'''. 
     354 1. '''Disable resampling''', by setting {{{PJMEDIA_HAS_LIBRESAMPLE=0}}}, to reduce executable size by '''45 KB'''. 
     355 1. '''Disable unused codecs'''. To leave with only G.711 codecs (''pcma'' and ''pcmu''), disable speex with {{{PJMEDIA_HAS_SPEEX_CODEC=0}}}, disable iLBC with {{{PJMEDIA_HAS_ILBC_CODEC=0}}}, disable GSM codec with {{{PJMEDIA_HAS_GSM_CODEC=0}}}, and disable L16 codecs with {{{PJMEDIA_HAS_L16_CODEC=0}}}. This will reduce executable size by approximately '''114 KB'''. 
     356 1. '''Disable alaw/ulaw table'''. By default, a table based alaw/ulaw implementation is used. You can disable this by setting {{{PJMEDIA_HAS_ALAW_ULAW_TABLE=0}}}, which makes PJMEDIA to calculate the alaw/ulaw value rather than using the table. This will reduce executable size by approximately '''28 KB'''. 
     357 1. '''Disable error string'''. All libraries keep the description of the error codes in some static variables. You can omit this error description by setting {{{PJ_HAS_ERROR_STRING=0}}}. When the error description is omitted, {{{pj_strerror()}}} will just print the error code rather than the error description. You can then look for the error description in libraries source codes, or by searching on PJSIP website. Omitting the error description will reduce executable size by approximately '''20 KB'''. 
     358 1. '''Disable run-time checks'''. All the libraries are equipped with run-time checks to prevent bad parameters from crashing the software. You can disable this feature by setting {{{PJ_ENABLE_EXTRA_CHECK}}} to zero. This will reduce executable size by approximately '''20 KB'''. 
     359 1. '''Disable stack checks'''. PJLIB is equipped with stack overflow detection. You can disable this feature by setting {{{PJ_OS_HAS_CHECK_STACK}}} to zero, to reduce executable size by approximately '''4 KB'''. 
     360 1. '''Disable CRC32 table''', by setting {{{PJ_CRC32_HAS_TABLES=0}}}, to reduce executable size by about '''1 KB''', only if you use ICE. 
     361 1. '''Use your own sound device abstraction''', rather than !PortAudio. If you are porting PJSIP to an embedded platform, you may need to create your own sound device abstraction. So supposing we don't use !PortAudio and use the NULL sound device implementation ({{{PJMEDIA_SOUND_IMPLEMENTATION=PJMEDIA_SOUND_NULL_SOUND}}}, we will reduce executable size by approximately '''49 KB'''. 
     362 
     363With all above optimizations set, we now have pjsua size (still with ICE/PJNATH and all media goodies '''included''' in the executable): 
     364 
     365{{{ 
     366  pjsua_vc6.exe: file size= 381,032 bytes 
     367 
     368   184320 .data 
     369     8192 .rdata 
     370    16384 .reloc 
     371   319488 .text 
     372}}} 
     373 
     374Using the same settings, if we take the executable size of '''simpleua.exe''' (this is a sample program to do simple call with audio, without conference bridge nor ICE/STUN): 
     375 
     376{{{ 
     377  simpleua.exe: file size= 155,648 bytes 
     378 
     379    28672 .data 
     380     4096 .rdata 
     381   139264 .text 
     382}}} 
     383 
     384At this point, the heap memory usage of pjsua with 2 calls has been reduced by about 100 KB: 
     385 
     386{{{ 
     387>>> dd 
     388.. 
     389 Total    793624 of    909024 (87 %) used! 
     390.. 
     391}}} 
     392 
     393We still want more heap usage reductions, of course! 
     394 
     395Now, assuming that the product will only need to support, say, 8 calls, we can apply these settings to '''reduce heap memory usage''': 
     396 1. '''Transaction/dialog/call count'''. Set the maximum number of concurrent transactions/dialogs/calls with 
     397{{{ 
     398#   define PJSIP_MAX_TSX_COUNT          31 
     399#   define PJSIP_MAX_DIALOG_COUNT       31 
     400#   define PJSUA_MAX_CALLS              31 
     401}}} 
     402 1. '''Optimize pool sizes'''. These settings not only will reduce heap memory usage, but will also prevent the libraries from allocating too many large memory blocks. With the default settings, most memory pools are configured to allocate memory in 4KB blocks, and some system like Symbian will have difficulties in providing these blocks to PJSIP. Use the following setting to reduce the memory block size used by memory pools, at the expense of more calls to system's memory allocators ({{{new}}} or {{{malloc}}}) to allocate memory: 
     403{{{ 
     404#   define PJSIP_POOL_LEN_ENDPT         1000 
     405#   define PJSIP_POOL_INC_ENDPT         1000 
     406#   define PJSIP_POOL_RDATA_LEN         2000 
     407#   define PJSIP_POOL_RDATA_INC         2000 
     408#   define PJSIP_POOL_LEN_TDATA         2000 
     409#   define PJSIP_POOL_INC_TDATA         512 
     410#   define PJSIP_POOL_LEN_UA            2000 
     411#   define PJSIP_POOL_INC_UA            1000 
     412#   define PJSIP_POOL_TSX_LAYER_LEN     256 
     413#   define PJSIP_POOL_TSX_LAYER_INC     256 
     414#   define PJSIP_POOL_TSX_LEN           512 
     415#   define PJSIP_POOL_TSX_INC           128 
     416#   define PJMEDIA_SESSION_SIZE         1000 
     417#   define PJMEDIA_SESSION_INC          1000 
     418}}} 
     419 
     420With these settings applied, heap memory usage will be reduced very significantly. Looking at heap memory usage of pjsua with two G.711 calls: 
     421 
     422{{{ 
     423pjsua_vc6 --clock-rate 8000 --ec-tail 0 --max-calls 2 --no-tcp 
     424 
     425>>> dd 
     426.. 
     427  Total    120532 of    150344 (80 %) used! 
     428.. 
     429}}} 
     430 
     431So only about 150 KB for two calls, I think that should be affordable. 
     432 
     433---- 
    140434 
    141435== Windows Specific Questions == 
    142436 
    143 === Where can I have PJSIP as ActiveX control? === #activex 
    144  
    145 See Sasa Coh's page. 
     437=== How can I use PJSIP in .NET applications? === #activex 
     438 
     439For this, you will need to have ActiveX wrapper for PJSIP. Unfortunately, at this point we don't provide ActiveX projects for PJSIP, but you can use one of the following projects: 
     440 
     441 - [http://sipekphone2.googlepages.com/ Sipek Phone project], by created Sasa Coh, is a project to build a SIP softphone using .NET, and it has an PJSIP ActiveX wrapper as part of the project. 
     442 
     443 
     444---- 
    146445 
    147446== Windows Mobile Specific Questions == 
    148447 
    149 === I'm having problem with audio === #wm-audio 
    150  
    151 Please see [#audio-problem] above. 
     448=== How can I build PJSIP for WinCE/Windows Mobile? === #wm-build 
     449 
     450Have a look at this [http://www.pjsip.org/using.htm#evc Getting Started | Windows Mobile] page. 
     451 
     452 
     453---- 
    152454 
    153455== Linux/uC-Linux Specific Questions == 
    154456 
     457=== How can I build PJSIP for Linux/uC-Linux? === #linux-build 
     458 
     459Have a look at this [http://www.pjsip.org/using.htm#gnu Getting Started | GNU] page. 
     460 
     461---- 
     462 
    155463== MacOS X Specific Questions == 
    156464 
     465=== How can I build PJSIP for MacOS X? === #osx-build 
     466 
     467Have a look at this [http://www.pjsip.org/using.htm#gnu Getting Started | GNU] page. 
     468 
     469---- 
     470 
    157471== Symbian Specific Questions == 
     472 
     473=== How can I build PJSIP for Symbian? === #symbian-build 
     474 
     475We have provided a thorough instructions at the [http://www.pjsip.org/sip_symbian.htm PJSIP for Symbian] page. 
     476 
     477---- 
     478 
     479== Python == 
     480 
     481=== How can I use PJSIP in Python? === #python 
     482 
     483Start at this small [Python_SIP_Tutorial PJSIP Python Tutorial] page. 
     484 
     485 
     486