本日本語訳はPJSUA API - High Level Softphone APIをよりよく理解をする支援を行う目的で作成されたものであり、非公式なドキュメントです。

原文: PJSUA API - High Level Softphone API

各部の説明

PJSUA APIのベース部分はPJSUAの生成、初期化、起動をコントロールし、様々な補助関数を提供します。

PJSUAライブラリを使用する

PJSUAの生成

何よりもまず最初に、アプリケーションは pjsua_create() を呼ぶ事でPJSUAを生成しなければなりません。これにより、とりわけPJLIBが初期化されます。これは全てのPJLIB関数を呼ばれる前、PJLIB-UTIL、SIPエンドポイントの生成の前に行われる事が重要です。

この関数( pjsua_create() )が呼ばれた後、アプリケーションはメモリープールを生成（ pjsua_pool_create() ）する事ができます。またPJSUAの初期化の為に、コマンドラインまたはファイルから設定を読み込む事ができます。

PJSUAの初期化

PJSUAが生成された後、アプリケーションは pjsua_init() を呼ぶ事で初期化を実行する事ができます。この関数は、もし必要であれば幾つかのオプショナルな設定を引数として受け取ります。

PJSUA-LIBの初期化(C言語)

C言語でのPJSUA初期化サンプルコード

# include <pjsua-lib/pjsua.h>
# define THIS_FILE __FILE__

static pj_status_t app_init(void)
{
  pjsua_config ua_cfg;
  pjsua_logging_config log_cfg;
  pjsua_media_config media_cfg;
  pj_status_t status;

  // Must create pjsua before anything else!
  status = pjsua_create();

  if (status != PJ_SUCCESS) {
    pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
    return status;
  }

  // Initialize configs with default settings.
  pjsua_config_default(&ua_cfg);
  pjsua_logging_config_default(&log_cfg);
  pjsua_media_config_default(&media_cfg);

  // At the very least, application would want to override
  // the call callbacks in pjsua_config:
  ua_cfg.cb.on_incoming_call = ...
  ua_cfg.cb.on_call_state = ..
    ...
  // Customize other settings (or initialize them from application specific
  // configuration file):
  ...
  // Initialize pjsua
  status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg);

  if (status != PJ_SUCCESS) {
    pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
    return status;
  }
  .
  ...
}

その他の初期化

pjsua_init() によってPJSUAが初期化された後は、アプリケーションは通常必要に応じて以下の処理を行います。

pjsua_transport_create() によるSIPトランスポートの生成。アプリケーションはサポートする全てのトランスポート（例: UDP, TCP, またはTLS）に対してpjsua_transport_create() を呼びます。より多くの情報を得る為にはPJSUA-API Signaling Transportを参照してください。
一つまたは複数のアカウントを生成する為にpjsua_acc_add() または pjsua_acc_add_local() を呼んでください。SIPアカウントはSIPサーバーに登録する為に使用されます。より多くの情報が必要な場合はPJSUA-API Accounts Managementを参照してください。
1つもしくは複数のbaddy（訳わからず）を追加する為にpjsua_buddy_add() を使用します。より多くの情報が必要な場合はPJSUA-API Buddy, Presence, and Instant Messagingを参照してください。
必須ではありませんが、サウンドデバイスの設定、コーデックの設定、その他のメディアの設定を行います。より詳しい情報は PJSUA-API Media Manipulationにあります。

PJSUAの起動

全ての初期化が行われた後、アプリケーションは pjsua_start() を呼んでPJSUAを起動しなければなりません。この関数はまず全ての設定が適切に設定されている事を確認します。そして設定されていない項目が有ればデフォルト値を設定します。もしも必須の設定値が与えられておらず、リカバーが不可能な場合はエラーステータスを報告します。

殆どの設定は実行中に変更する事が出来ます。例えばアカウントやbaddyの追加・変更・削除や、メディア関連の設定変更などを実行中に行う事ができます。

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);
    ...
  }
}