PJSIP

https://docs.pjsip.org/
Admin
PJSIP is a Session Initiation Protocol (SIP) library providing high-level APIs for building VoIP and...
Tokens:1,257,719
Snippets:12,980
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### C Example for Starting PJSUA

Source: https://docs.pjsip.org/en/latest/api/generated/pjsip/group/group__PJSUA__LIB__BASE.html

Sample code for starting PJSUA.

```c
static pj_status_t app_run(void)
{
   pj_status_t status;

   // Start pjsua
   status = pjsua_start();
   if (status != PJ_SUCCESS) {
       pjsua_destroy();
       pjsua_perror(THIS_FILE, "Error starting pjsua", status);
       return status;
   }

   // Run application loop
   while (1) {
       char choice[10];
       
       printf("Select menu: ");
       fgets(choice, sizeof(choice), stdin);
       ...
   }
}
```

--------------------------------

### Install PJSIP with make install

Source: https://docs.pjsip.org/en/latest/_sources/get-started/posix/build_instructions.rst.txt

Run make install to install header and library files. Customize target directory with --prefix=DIR option to configure.

```shell
$ make install
```

--------------------------------

### Account Creation Example

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/using/account.rst.txt

Example of creating an account with configuration in PJSUA2.

```cpp
AccountConfig acc_cfg;
    acc_cfg.idUri = "sip:test1@pjsip.org";
    acc_cfg.regConfig.registrarUri = "sip:pjsip.org";
    acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "secret1") );

    MyAccount *acc = new MyAccount;
    try {
        acc->create(acc_cfg);
    } catch(Error& err) {
        cout << "Account creation error: " << err.info() << endl;
    }
```

--------------------------------

### Install to prefix

Source: https://docs.pjsip.org/en/latest/_sources/get-started/cmake/build_instructions.rst.txt

Install headers, libraries, and the CMake package config to /usr/local.

```shell
$ cmake --install build --prefix /usr/local
```

--------------------------------

### Configure SIP account with IPv6 preferences (PJSIP 2.14+) using PJSUA2 AccountConfig

Source: https://docs.pjsip.org/en/latest/_sources/specific-guides/network_nat/ipv6.rst.txt

Equivalent PJSUA2 setup using AccountConfig, AuthCredInfo, and Account::create. Sets ipv6Use and mediaConfig.ipv6Use to the same values as the C example. Requires a MyAccount class derived from Account.

```c++
    AccountConfig acc_cfg;
    acc_cfg.idUri = "sip:user@example.com";
    acc_cfg.regConfig.registrarUri = "sip:example.com";
    AuthCredInfo cred("digest", "*", "user", 0, "pwd");
    acc_cfg.sipConfig.authCreds.push_back(cred);

    acc_cfg.sipConfig.ipv6Use   = PJSUA_IPV6_ENABLED_NO_PREFERENCE;
    acc_cfg.mediaConfig.ipv6Use = PJSUA_IPV6_ENABLED_PREFER_IPV4;

    Account *acc = new MyAccount();
    acc->create(acc_cfg);

```

--------------------------------

### Custom install prefix

Source: https://docs.pjsip.org/en/latest/_sources/get-started/cmake/build_instructions.rst.txt

Configure, build, and install to a custom prefix.

```shell
$ cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/pjsip
$ cmake --build build -j
$ cmake --install build
```

--------------------------------

### Build and install vo-amrwbenc

Source: https://docs.pjsip.org/en/latest/_sources/specific-guides/audio/opencore-amr.rst.txt

Build and install the vo-amrwbenc library.

```shell
$ make && make install
```

--------------------------------

### Verify Installation

Source: https://docs.pjsip.org/en/latest/specific-guides/audio/opencore-amr.html

Verify the installation by listing the include directory contents.

```bash
$ ls /home/foo/include
  opencore-amrnb  opencore-amrwb  vo-amrwbenc

```

--------------------------------

### iLBC Mode Setting Example

Source: https://docs.pjsip.org/en/latest/api/generated/pjmedia/group/group__PJMED__PASSTHROUGH__CODEC.html

Example of setting up pjmedia_codec_param to use iLBC mode 20ms.

```c
pjmedia_codec_param param;
...
// setting iLBC mode in SDP
param.setting.dec_fmtp.cnt = 1;
param.setting.dec_fmtp.param[0].name = pj_str("mode");
param.setting.dec_fmtp.param[0].val  = pj_str("20");
...

```

--------------------------------

### Quick start build

Source: https://docs.pjsip.org/en/latest/_sources/get-started/cmake/build_instructions.rst.txt

Configure and build the project from the top of the source tree.

```shell
$ cd pjproject
$ cmake -S . -B build
$ cmake --build build -j
```

--------------------------------

### config_site.h include sample

Source: https://docs.pjsip.org/en/latest/_sources/get-started/guidelines-development.rst.txt

Recommended initial content for config_site.h, including the sample configuration header.

```c
#include <pj/config_site_sample.h>
```

--------------------------------

### pjsua_vid_dev_count

Source: https://docs.pjsip.org/en/latest/api/generated/pjsip/group/group__PJSUA__LIB__VIDEO.html

Get the number of video devices installed in the system.

```APIDOC
## pjsua_vid_dev_count

### Description
Get the number of video devices installed in the system.

### Returns
The number of devices.
```

--------------------------------

### iOS Push Notifications Code Examples

Source: https://docs.pjsip.org/en/latest/_sources/specific-guides/other/ios_push_notifications.rst.txt

Code examples from the iOS push notifications guide, covering audio device handling, IP-change handling, and microphone permission.

```c
   /* In the ACTIVATE_AUDIO branch of pjsua_funcs() */
   pjsua_set_no_snd_dev();
   pjsua_set_snd_dev(PJSUA_SND_DEFAULT_CAPTURE_DEV,
                     PJSUA_SND_DEFAULT_PLAYBACK_DEV);

   /* Reconnect each active call's media to the conference bridge. */
   for (unsigned i = 0; i < count; i++) {
       /* ... pjsua_conf_connect for each PJMEDIA_TYPE_AUDIO call ... */
   }
```

```objc
   if (!pjsua_snd_is_active()) {
       [[AVAudioSession sharedInstance]
           setActive:NO
         withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation
               error:nil];
   }
```

```c
   pjsua_ip_change_param param;
   pjsua_ip_change(&param);
```

```objc
   [[AVAudioSession sharedInstance]
     requestRecordPermission:^(BOOL granted) { /* ... */ }];
```

--------------------------------

### Start library with libStart()

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/using/endpoint.rst.txt

Start the library to finalize initialization, e.g., STUN resolution and sound device startup. Throws pj::Error on failure.

```c++
try {
    ep->libStart();
} catch(Error& err) {
    cout << "Startup error: " << err.info() << endl;
}
```

--------------------------------

### Stream Management Functions

Source: https://docs.pjsip.org/en/latest/api/generated/pjmedia/group/group__PJMED__STRM.html

Functions to manage media streams, including getting transport, starting, modifying codec parameters, retrieving info/statistics, and sending/checking DTMF.

```c
pjmedia_transport *pjmedia_stream_get_transport(pjmedia_stream *st)
```

```c
pj_status_t pjmedia_stream_start(pjmedia_stream *stream)
```

```c
pj_status_t pjmedia_stream_modify_codec_param(pjmedia_stream *stream, const pjmedia_codec_param *param)
```

```c
pj_status_t pjmedia_stream_get_info(const pjmedia_stream *stream, pjmedia_stream_info *info)
```

```c
pj_status_t pjmedia_stream_get_stat(pjmedia_stream *stream, pjmedia_stream_stat *stat)
```

```c
pj_status_t pjmedia_stream_dial_dtmf(pjmedia_stream *stream, const pj_str_t *ascii_digit)
```

```c
pj_status_t pjmedia_stream_dial_dtmf2(pjmedia_stream *stream, const pj_str_t *ascii_digit, unsigned duration)
```

```c
pj_bool_t pjmedia_stream_check_dtmf(pjmedia_stream *stream)
```

--------------------------------

### Include config_site_sample.h in config_site.h

Source: https://docs.pjsip.org/en/latest/get-started/guidelines-development.html

Recommended starting point for config_site.h: include the sample configuration file to use default settings. Create pjlib/include/pj/config_site.h if it doesn't exist; the GNU make build system creates an empty one automatically.

```C
#include <pj/config_site_sample.h>

```

--------------------------------

### iOS Push Notifications Code Examples

Source: https://docs.pjsip.org/en/latest/specific-guides/other/ios_push_notifications.html

Code snippets from the iOS push notifications guide, covering background handling, PushKit registration, and token handling.

```objectivec
- (void)applicationDidEnterBackground:(UIApplication *)application
{
    SCHEDULE_TIMER(REREGISTER);
    /* Allow the re-registration to complete. */
    [NSThread sleepForTimeInterval:0.3];
}

```

```objectivec
self.voipRegistry = [[PKPushRegistry alloc]
    initWithQueue:dispatch_get_main_queue()];
self.voipRegistry.delegate = self;
self.voipRegistry.desiredPushTypes = [NSSet setWithObject:PKPushTypeVoIP];

```

```objectivec
- (void)pushRegistry:(PKPushRegistry *)registry
    didUpdatePushCredentials:(PKPushCredentials *)credentials
    forType:(NSString *)type
{
    /* Format the token as a hex string. */
    const char *data = [credentials.token bytes];
    self.token = [NSMutableString string];
    for (NSUInteger i = 0; i < [credentials.token length]; i++)
        [self.token appendFormat:@"%02.2hhx", data[i]];

    /* Now start pjsua. */
    [NSThread detachNewThreadSelector:@selector(pjsuaStart)
                           toTarget:self withObject:nil];
}

```

--------------------------------

### Initialize library with libInit()

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/using/endpoint.rst.txt

Initialize the library with libInit(), passing an EpConfig. Throws pj::Error on failure.

```c++
try {
    EpConfig ep_cfg;
    // Specify customization of settings in ep_cfg
    ep->libInit(ep_cfg);
} catch(Error& err) {
    cout << "Initialization error: " << err.info() << endl;
}
```

--------------------------------

### Establish bidirectional video media for conference call

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/using/media_video.rst.txt

Gets encoding and decoding video media from two calls and starts transmitting between them to enable a three-party video conference. After this, all three parties can see each other.

```c++
    VideoMedia vid_enc_med1 = call1.getEncodingVideoMedia(-1);
    VideoMedia vid_dec_med1 = call1.getDecodingVideoMedia(-1);
    
    VideoMedia vid_enc_med2 = call2.getEncodingVideoMedia(-1);
    VideoMedia vid_dec_med2 = call2.getDecodingVideoMedia(-1);
    
    vid_dec_med1.startTransmit(vid_enc_med2);
    vid_dec_med2.startTransmit(vid_enc_med1);
```

--------------------------------

### Configure with CFLAGS for debug build

Source: https://docs.pjsip.org/en/latest/_sources/get-started/posix/build_instructions.rst.txt

Example of passing compiler flags to the configure script to tune PJSIP build. The command shown uses optimization and disables debug assertions. You can get standard customization details from './configure --help'.

```bash
   $ ./configure CFLAGS="-O3 -DNDEBUG -msoft-float -fno-builtin"
```

--------------------------------

### PJ_LOG macro example

Source: https://docs.pjsip.org/en/latest/api/generated/pjlib/group/group__PJ__LOG.html

Use the PJ_LOG macro to write a log message with a specified verbosity level. The first argument is the level (lower is more important, zero is fatal), and the second is a parenthesized printf-style argument list starting with the sender (e.g., __FILE__).

```c
PJ_LOG(2, (__FILE__, "current value is %d", value));
```

--------------------------------

### Minimal Example

Source: https://docs.pjsip.org/en/latest/get-started/cmake/using.html

Minimal example showing how to consume PJSIP from a CMake project: CMakeLists.txt, a small C source file, and the build commands.

```cmake
cmake_minimum_required(VERSION 3.28)
project(myapp C)

find_package(Pj REQUIRED)

add_executable(myapp myapp.c)
target_link_libraries(myapp PRIVATE Pj::pjsua-lib)

```

```c
#include <pjsua-lib/pjsua.h>
#include <pj/log.h>

int main(void)
{
    pjsua_create();
    PJ_LOG(3, ("myapp.c", "Hello PJSIP! Bye PJSIP."));
    pjsua_destroy();
    return 0;
}

```

```shell
$ cmake -S . -B build -DCMAKE_PREFIX_PATH=/usr/local
$ cmake --build build -j

```

--------------------------------

### Java: PJSUA2 Hello World with registration

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/hello_world.rst.txt

Java equivalent of the C++ sample. Loads the pjsua2 native library, creates and initializes the endpoint, creates a UDP transport on port 5060, configures an account with registration to sip.pjsip.org, and sleeps for 10 seconds. Uses a custom Account subclass to print registration state changes.

```java
import org.pjsip.pjsua2.*;

// Subclass to extend the Account and get notifications etc.
class MyAccount extends Account {
  @Override
  public void onRegState(OnRegStateParam prm) {
      System.out.println("*** On registration state: " + prm.getCode() + prm.getReason());
  }
}

public class test {
  static {
      System.loadLibrary("pjsua2");
      System.out.println("Library loaded");
  }
  
  public static void main(String argv[]) {
      try {
          // Create endpoint
          Endpoint ep = new Endpoint();
          ep.libCreate();
          // Initialize endpoint
          EpConfig epConfig = new EpConfig();
          ep.libInit( epConfig );
          // Create SIP transport. Error handling sample is shown
          TransportConfig sipTpConfig = new TransportConfig();
          sipTpConfig.setPort(5060);
          ep.transportCreate(pjsip_transport_type_e.PJSIP_TRANSPORT_UDP, sipTpConfig);
          // Start the library
          ep.libStart();
```

--------------------------------

### pjsip_tcp_transport_lis_start

Source: https://docs.pjsip.org/en/latest/api/generated/pjsip/group/group__PJSIP__TRANSPORT__TCP.html

Start the TCP listener, if the listener is not started yet. This is useful to start the listener manually, if listener was not started when PJSIP_TCP_TRANSPORT_DONT_CREATE_LISTENER is set to 0.

```c
pj_status_t pjsip_tcp_transport_lis_start(pjsip_tpfactory *factory, const pj_sockaddr *local, const pjsip_host_port *a_name)
```

--------------------------------

### Python3: PJSUA2 Hello World with registration

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/hello_world.rst.txt

Python3 equivalent of the C++ sample. Creates and initializes the endpoint, creates a UDP transport on port 5060, configures an account with registration to sip.pjsip.org, and sleeps for 10 seconds. Uses a custom Account subclass to print registration state changes.

```python
import pjsua2 as pj

# Subclass to extend the Account and get notifications etc.
class Account(pj.Account):
  def onRegState(self, prm):
      print("***OnRegState: " + prm.reason)

# pjsua2 test function
def pjsua2_test():
  # Create and initialize the library
  ep_cfg = pj.EpConfig()
  ep = pj.Endpoint()
  ep.libCreate()
  ep.libInit(ep_cfg)
  
  # Create SIP transport. Error handling sample is shown
  sipTpConfig = pj.TransportConfig();
  sipTpConfig.port = 5060;
  ep.transportCreate(pj.PJSIP_TRANSPORT_UDP, sipTpConfig);
  # Start the library
  ep.libStart();
  
  acfg = pj.AccountConfig();
  acfg.idUri = "sip:test@sip.pjsip.org";
  acfg.regConfig.registrarUri = "sip:sip.pjsip.org";
  cred = pj.AuthCredInfo("digest", "*", "test", 0, "pwtest");
  acfg.sipConfig.authCreds.append( cred );
  # Create the account
  acc = Account();
  acc.create(acfg);
  # Here we don't have anything else to do..
  time.sleep(10);

  # Destroy the library
  ep.libDestroy()

#
# main()
#
if __name__ == "__main__":
  pjsua2_test()
```

--------------------------------

### Video build configuration

Source: https://docs.pjsip.org/en/latest/_sources/get-started/cmake/build_instructions.rst.txt

Enable video support with SDL2, libyuv, and VPX codec.

```shell
$ cmake -S . -B build \
    -DPJMEDIA_WITH_VIDEO=ON \
    -DPJMEDIA_WITH_LIBYUV=ON \
    -DPJMEDIA_WITH_VPX=ON \
    -DPJMEDIA_WITH_SDL2=ON
```

--------------------------------

### pjsip_tls_transport_lis_start

Source: https://docs.pjsip.org/en/latest/api/generated/pjsip/group/group__PJSIP__TRANSPORT__TLS.html

Starts the TLS listener if it is not already started. Useful for manually starting the listener when PJSIP_TLS_TRANSPORT_DONT_CREATE_LISTENER is set to 0.

```APIDOC
## pjsip_tls_transport_lis_start

### Description
Starts the TLS listener if it is not already started. This is useful to start the listener manually, if listener was not started when PJSIP_TLS_TRANSPORT_DONT_CREATE_LISTENER is set to 0.

### Function Signature
pj_status_t pjsip_tls_transport_lis_start(pjsip_tpfactory *factory, const pj_sockaddr *local, const pjsip_host_port *a_name)

### Parameters
- **factory** (pjsip_tpfactory*) - The SIP TLS transport factory.
- **local** (const pj_sockaddr*) - The address where the listener should be bound to. Both IP interface address and port fields are optional. If IP interface address is not specified, socket will be bound to PJ_INADDR_ANY. If port is not specified, socket will be bound to any port selected by the operating system.
- **a_name** (const pjsip_host_port*) - The published address for the listener. It can be set using IP address or hostname. If this argument is NULL, then the bound address will be used as the published address.

### Returns
PJ_SUCCESS when the listener has been successfully started.
```

--------------------------------

### Python example

Source: https://docs.pjsip.org/en/latest/specific-guides/sip/async_auth.html

Python example showing how to defer an authentication challenge and respond asynchronously with new credentials, with explicit cleanup of the deferred object.

```python
import pjsua2 as pj

class MyAccount(pj.Account):
    def onAuthChallenge(self, prm):
        deferred = prm.challenge.defer()

        # ... fetch credentials asynchronously (from a pjlib-registered
        # thread, or marshal the result back to one) ...

        creds = pj.AuthCredInfoVector()
        creds.append(pj.AuthCredInfo("digest", "*",
                                     "alice", 0, "secret123"))
        deferred.respond(creds)
        # Must explicitly consume the deferred object — do not rely on
        # Python GC to abandon it (finalizer runs on an unregistered
        # thread). See the GC warning above.

```

--------------------------------

### Build and install opencore-amr

Source: https://docs.pjsip.org/en/latest/_sources/specific-guides/audio/opencore-amr.rst.txt

Build and install the opencore-amr library.

```shell
make && make install
```

--------------------------------

### Enable TLS and select backend manually in config_site.h

Source: https://docs.pjsip.org/en/latest/_sources/specific-guides/security/ssl.rst.txt

For build systems that don't auto-detect (such as a raw MSVC project), set these macros in `config_site.h`. `PJ_HAS_SSL_SOCK` must be `1` to turn on TLS, and `PJ_SSL_SOCK_IMP` selects the backend—replace the comment's example with the actual macro.

```c
#define PJ_HAS_SSL_SOCK     1
#define PJ_SSL_SOCK_IMP     PJ_SSL_SOCK_IMP_OPENSSL   /* or another */
```

--------------------------------

### Install SWIG (Debian)

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/building.rst.txt

Installs SWIG on Debian-based distributions.

```shell
sudo apt-get install swig
```

--------------------------------

### Heading Convention Example (Sphinx Heading)

Source: https://docs.pjsip.org/en/latest/specific-guides/other/writing-guide.html

Example of a Sphinx heading convention used for documentation. The actual heading text is not visible in the example, but it is used as a title for a section.

```rst
```

```
```

--------------------------------

### List configure options

Source: https://docs.pjsip.org/en/latest/_sources/get-started/cmake/build_instructions.rst.txt

List all cached variables with help text.

```shell
$ cmake -LAH -N build | less
```

--------------------------------

### Install OpenH264 on Debian/Ubuntu

Source: https://docs.pjsip.org/en/latest/api/pjmedia/pjmedia-codec.html

Installation command for OpenH264 on Debian/Ubuntu systems.

```bash
$ sudo apt-get install libopenh264-dev

```

--------------------------------

### PJSIP Video Configuration Examples

Source: https://docs.pjsip.org/en/latest/get-started/ios/build_instructions.html

Code examples for configuring PJSIP video support, including enabling VideoToolbox, configuring OpenH264, and setting video orientation.

```c
#define PJMEDIA_HAS_VID_TOOLBOX_CODEC 1

```

```bash
$ ./configure-iphone --with-openh264=/Users/me/opt

```

```c
#define PJ_CONFIG_IPHONE                     1
#define PJMEDIA_HAS_VIDEO                    1

/* Enable at least one video codec — see Requirements above.
   VideoToolbox requires PJSIP 2.7+; on older versions enable
   OpenH264 (PJMEDIA_HAS_OPENH264_CODEC) instead. */
#define PJMEDIA_HAS_VID_TOOLBOX_CODEC        1

#include <pj/config_site_sample.h>

```

```c
pjsua_vid_dev_set_setting(dev_id, PJMEDIA_VID_DEV_CAP_ORIENTATION, &new_orientation, PJ_TRUE)

```

--------------------------------

### C++: PJSUA2 Hello World with registration

Source: https://docs.pjsip.org/en/latest/_sources/pjsua2/hello_world.rst.txt

Initializes the PJSUA2 endpoint, creates a UDP transport on port 5060, configures an account with registration to sip.pjsip.org, and sleeps for 10 seconds. Includes a MyAccount subclass that prints registration state changes. Requires building with the standard build and running from pjsip-apps/bin/samples/.. directory.

```c++
#include <pjsua2.hpp>
#include <iostream>

using namespace pj;

// Subclass to extend the Account and get notifications etc.
class MyAccount : public Account {
public:
    virtual void onRegState(OnRegStateParam &prm) {
        AccountInfo ai = getInfo();
        std::cout << (ai.regIsActive? "*** Register:" : "*** Unregister:")
                  << " code=" << prm.code << std::endl;
    }
};

int main()
{
    Endpoint ep;
    
    ep.libCreate();
    
    // Initialize endpoint
    EpConfig ep_cfg;
    ep.libInit( ep_cfg );
    
    // Create SIP transport. Error handling sample is shown
    TransportConfig tcfg;
    tcfg.port = 5060;
    try {
        ep.transportCreate(PJSIP_TRANSPORT_UDP, tcfg);
    } catch (Error &err) {
        std::cout << err.info() << std::endl;
        return 1;
    }
    
    // Start the library (worker threads etc)
    ep.libStart();
    std::cout << "*** PJSUA2 STARTED ***" << std::endl;
    
    // Configure an AccountConfig
    AccountConfig acfg;
    acfg.idUri = "sip:test@sip.pjsip.org";
    acfg.regConfig.registrarUri = "sip:sip.pjsip.org";
    AuthCredInfo cred("digest", "*", "test", 0, "secret");
    acfg.sipConfig.authCreds.push_back( cred );
    
    // Create the account
    MyAccount *acc = new MyAccount;
    acc->create(acfg);
    
    // Here we don't have anything else to do..
    pj_thread_sleep(10000);
    
    // Delete the account. This will unregister from server
    delete acc;
    
    // This will implicitly shutdown the library
    return 0;
}
```
Tokens:
Raw