PJSUA2開發文檔--第四章 端點ENDPOINT

 

4.端點ENDPOINT

Endpoint類是一個單例類，應用程序必須在此類實例之前創建一個並且最多只能創建一個，然后才能執行任何操作。同樣，一旦這個類被銷毀，應用程序就不能調用該庫的任何API。這個類是PJSUA2的核心類，它提供了以下功能：

• 啟動和關機
• 配置的定制，如核心UA（用戶代理）SIP配置，媒體配置和日志配置

本章將介紹上述功能。

要使用Endpoint類，通常應用程序不需要進行子類化（再寫繼承於該類的子類，簡稱子類化（subclass）），除非：

• 應用程序希望實現/重載端點回調方法來獲取如傳輸狀態更改或NAT檢測完成等事件，或者
• 應用程序使用Endpoint.utilTimerSchedule（）API調度計時器。在這種情況下，應用程序需要實現onTimer（）回調以在定時器到期時獲取通知。

4.1 實例化端點

在其他任何事情之前，必須實例化Endpoint類：

Endpoint *ep = new Endpoint;

一旦端點被實例化，可使用Endpoint.instance（）靜態方法獲取端點實例。

4.2 創建庫

通過調用其libCreate（）方法來創建庫：

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

如果發生錯誤，libCreate（）方法將引發異常，因此我們需要使用try / catch子句來捕獲異常。

4.3 初始化庫並配置設置

EpConfig類提供端點配置，允許自定義以下設置：

• UAConfig，指定核心SIP用戶代理設置。
• MediaConfig，指定各種媒體全局設置
• LogConfig來自定義日志設置。

請注意，可以在AccountConfig中根據每個帳戶進一步指定一些設置。

要自定義設置，請創建EpConfig類的實例，並在端點初始化期間指定它們（稍后將對此進行說明），例如： 

EpConfig ep_cfg;
ep_cfg.logConfig.level = 5; ep_cfg.uaConfig.maxCalls = 4; ep_cfg.mediaConfig.sndClockRate = 16000;

接下來，通過調用libInit（）初始化庫：

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

上面的代碼片段使用默認設置初始化庫。

4.4 創建一個或多個傳輸

在發送或接收SIP消息之前，應用程序需要創建一個或多個傳輸：

try 
{
    TransportConfig tcfg;
    tcfg.port = 5060; TransportId tid = ep->transportCreate(PJSIP_TRANSPORT_UDP, tcfg); } catch(Error& err) { cout << "Transport creation error: " << err.info() << endl; }

transportCreate（）方法返回新創建的傳輸ID，它傳遞 傳輸類型和TransportConfig對象 來定制傳輸設置，如綁定地址和偵聽端口號。沒有這個，默認情況下，傳輸將綁定到INADDR_ANY和任何可用的端口。

除了創建無用戶帳戶（使用Account.create（））以外，沒有真正使用傳輸ID，稍后將對此進行說明），也許可以在應用程序想要的時候向用戶顯示傳輸列表。

4.5 創建安全傳輸（TLS）

要創建TLS傳輸，您可以使用與上述相同的方法。您可以通過修改字段TransportConfig.tlsConfig來進一步自定義TLS傳輸，例如設置證書文件或選擇使用的密碼。

try {
    TransportConfig tcfg;
    tcfg.port = 5061; // Optional, set CA/certificate/private key files. // tcfg.tlsConfig.CaListFile = "ca.crt"; // tcfg.tlsConfig.certFile = "cert.crt"; // tcfg.tlsConfig.privKeyFile = "priv.key"; // Optional, set ciphers. You can select a certain cipher/rearrange the order of ciphers here. // tcfg.ciphers = ep->utilSslGetAvailableCiphers(); TransportId tid = ep->transportCreate(PJSIP_TRANSPORT_TLS, tcfg); } catch(Error& err) { cout << "Transport creation error: " << err.info() << endl; }

4.5 啟動庫

現在我們啟動庫了。我們需要啟動庫完成初始化階段，例如完成初始的STUN地址解析，初始化/啟動聲音設備等。要啟動庫，請調用libStart（）方法：

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

4.6 關閉庫

應用程序退出后，庫需要關閉，以便將資源釋放回操作系統。雖然可以通過刪除端點實例（內部調用libDestroy（））來完成，最好是手動調用它，因為在Java或Python中，垃圾回收有問題，如前所述：

ep->libDestroy();
delete ep;

4.7 類引用

4.7.1 Endpoint

class pj::Endpoint

Endpoint （端點）表示pjsua庫的一個實例

在應用程序中只能有一個pjsua庫的實例，因此這個類是一個單例

公共功能(函數)

1）Endpoint() 　　　//默認構造函數 

2）virtual ~Endpoint()//虛析構函數

3）Version libVersion() const//得到庫的版本

4）void libCreate()　　//實例化pjsua應用程序。調用任何其他函數之前，應用程序必須調用此函數，以確保底層庫被正確初始化。一旦此函數返回成功，應用程序必須在退出前調用libDestroy（）。

5）pjsua_state libGetState() const //獲取庫狀態。返回庫狀態 

6）void libInit(const EpConfig &prmEpConfig) //使用指定的設置初始化pjsua。所有設置都是可選的，並且在未指定配置時將使用默認值。請注意，在調用此函數之前必須調用create（）。 

　　參數  prmEpConfig -端點配置

7）void libStart() // 在所有的初始化完成后，調用該函數，以便可以做其他檢查設置。應用程序可以在init（）之后的任何時間調用此函數。

8）void libRegisterThread(const string &name)//將由外部或自身API創建的線程注冊到庫。請注意，每次調用此函數時，它將分配一些內存來存儲線程描述，這只會在庫被銷毀時被釋放。 

　　參數name 要分配給線程的可選名稱

9）bool libIsThreadRegistered()//檢查該線程是否已經被注冊到庫中。需要注意的是此功能只適用於使用libRegisterThread（）注冊的庫的主線程與工作線程和外部/自身線程。

10）void libStopWorkerThreads()//停止所有工作線程

11）int libHandleEvents(unsigned msec_timeout)//對pjsua進行事件輪詢，如果需要，可以阻塞調用者線程指定的最大間隔（以毫秒為單位）。如果它在pjsua_config結構里配置了工作線程（thread_cnt域），應用程序通常不需要調用這個函數，因為輪詢將由這些工作線程來完成。如果EpConfig :: UaConfig :: mainThreadOnly啟用，並從主線程調用此函數（默認情況下，主線程是調用libCreate（）的線程），此功能也將掃描並在列表中運行任何掛起的作業。

 　　返回　　投票期間處理的事件數。負值表示錯誤，應用程序可以以（status = -return_value）方式檢索錯誤。

　　參數  msec_timeout - 最長時間等待，以毫秒為單位。 

12）void libDestroy(unsigned prmFlags = 0) //銷毀pjsua. 建議使用應用程序在調用此功能之前執行正常shutdown（例如從SIP服務器注銷帳戶，終止預訂訂閱和掛斷主動調用）.但是如果發現有活動會話，此函數將執行所有這些操作以終止活動會話。此功能將等待（block）幾秒鍾等待遠程的回復。如果沒有跟蹤它的狀態，Application.可以多次安全地調用此函數。 

　　參數  prmFlags，  pjsua_destroy_flag 枚舉值的組合

string utilStrError(pj_status_t prmErr) 檢索指定狀態代碼的錯誤字符串。

參數 prmErr -錯誤代碼。 

13）void utilLogWrite(int prmLevel, const string &prmSender, const string &prmMsg)寫一個日志消息

參數 prmLevel -日志詳細程度（1-5）

prmSender -日志發送方。

prmMsg -日志消息。

14）void utilLogWrite(LogEntry &e) 寫一個日志條目。

參數 e - 日志條目

15）pj_status_t utilVerifySipUri(const string &prmUri) 這是一個通用用函數，用於驗證是否給出了有效的SIP URL。如果URL是有效的SIP / SIPS方案，則將返回PJ_SUCCESS

返回 PJ_SUCCESS成功，或相應的錯誤代碼

參考 utilVerifyUri()

16）pj_status_t utilVerifyUri(const string &prmUri) 這是一個通用用函數，用於驗證是否給出了有效的URL。與utilVerifySipUri（）不同，如果給出tel：URI，此函數將返回PJ_SUCCESS

返回 PJ_SUCCESS成功，或相應的錯誤代碼

PJ_SUCCESS on success, or the appropriate error code.

參考 pjsua_verify_sip_url()

參數 prmUri - URL字符串

17）Token utilTimerSchedule(unsigned prmMsecDelay, Token prmUserData) 

設定具有指定間隔和用戶數據的定時器。當間隔時間到時，將調用onTimer（）回調。注意，回調可能由不同的線程執行，具體取決於是否啟用了工作線程

返回 令牌識別定時器，可以用utilTimerCancel（）取消定時器

參數 prmMsecDelay -時間間隔，單位為毫秒

      prmUserData - 任意用戶數據，被回饋給應用程序在回調。

18）void utilTimerCancel(Token prmToken) 使用指定的定時器令牌取消先前指定的定時器

參數 prmToken -從以前的utilTimerSchedule（）調用返回的計時器令牌。 

19）void utilAddPendingJob(PendingJob *job)  

注冊要由主線程執行的待處理作業的實用程序。如果EpConfig :: UaConfig :: mainThreadOnly為false，該作業將立即執行。

參數 job 工作類 

20）IntVector utilSslGetAvailableCiphers() 獲取SSL / TLS后端支持的密碼列表。

21）void natDetectType(void) 這是一個在這個端點前面檢測NAT類型的通用函數，一旦成功調用，此函數將異步完成，並在onNatDetectionComplete（）中報告結果.在檢測到NAT並調用回調后，應用程序可以通過調用natGetType（）獲取檢測到的NAT類型。應用程序還可以在稍后再次調用natDetectType（）來執行NAT檢測。注意，必須啟用STUN才能成功運行此功能。

22）pj_stun_nat_type natGetType() 獲取natDetectType（）函數檢測到的NAT類型。

natDetectType（）已成功完成並且已調用onNatDetectionComplete（）回調函數后，此函數將僅返回有用的NAT類型。

異常：如果在檢測過程中調用此函數，將引發PJ_EPENDING異常。

23）void natUpdateStunServers(const StringVector &prmServers, bool prmWait)更新STUN服務器列表。libInit（）必須在調用這個函數之前調用。 

參數prmServers - STUN服務器數組嘗試。端點將嘗試解析並聯系每個STUN服務器條目，直到找到可用的條目。每個條目可能是域名，主機名，IP地址，並且可能包含可選的端口號。例如：

 “pjsip.org”（域名）

“sip.pjsip.org”（主機名）

“pjsip.org:33478”（域名和非標准端口號）

“10.0.0.1:3478”（IP地址和端口號）

prmWait - 指定函數是否應該阻塞，直到得到結果。在這種情況下，函數將在分辨率完成時阻塞，並且在該函數返回之前調用onNatCheckStunServersComplete（） 

24）void natCheckStunServers(const StringVector &prmServers, bool prmWait, TokenprmUserData)  輔助函數，用於解析和聯系每個STUN服務器條目（依次）以查找哪個可用。須先調用libInit（） 

　　參考   natCancelCheckStunServers（）

　　參數 prmServers - STUN服務器數組嘗試。端點將嘗試解析並聯系每個STUN服務器條目，直到找到可用的條目。每個條目可能是域名，主機名，IP地址，並且可能包含可選的端口號。例如： 

“pjsip.org”（域名）

“sip.pjsip.org”（主機名）

“pjsip.org:33478”（域名和非標准端口號）

“10.0.0.1:3478”（IP地址和端口號）

 prmWait - 指定函數是否應該阻塞，直到得到結果。在這種情況下，函數將在分辨率完成時阻塞，並且在該函數返回之前調用回調函數。prmUserData - 任意用戶數據要在回調中傳回應用程序。 

25）void natCancelCheckStunServers(Token token, bool notify_cb = false)取消與指定令牌匹配的待決STUN分辨率。

異常：如果沒有匹配的PJ_ENOTFOUND或其他錯誤。

參數token -令牌匹配。 這個令牌給了natCheckStunServers（）

notify_cb -布爾值，用於控制是否為已取消的方案調用回調。 當調用回調時，結果中的狀態將被設置為PJ_ECANCELLED。

26）TransportId transportCreate （ pjsip_transport_type_e type ， const TransportConfig ＆ cfg ） 根據指定的設置創建並啟動新的SIP傳輸。

返回傳輸ID。

參數type -傳輸類型。cfg -傳輸配置。

27）IntVector transportEnum （ ） 

枚舉系統中當前創建的所有傳輸。

此函數將返回所有傳輸ID，然后應用程序可以調用transportGetInfo（）函數來檢索有關傳輸的詳細信息。

返回 傳輸ID數組。

28）TransportInfo transportGetInfo （ TransportId id ） 

獲取有關傳輸的信息。

返回 交通信息

參數 id - 運輸ID。

29）void transportSetEnable （ TransportId id ，bool enabled ） 

禁用傳輸或重新啟用它。

默認情況下，傳輸始終在創建后啟用。 禁用傳輸不一定關閉套接字，它只會丟棄傳入的消息，並阻止傳輸被用於發送傳出的消息。

參數id -傳輸ID。

enabled -啟用或禁用傳輸。

30）void transportClose （ TransportId id ） 關閉傳輸。

系統將等待所有事務關閉，同時防止新用戶使用傳輸，並在其使用次數達到零時關閉傳輸。

參數id -傳輸ID。

31）void transportShutdown （ TransportHandle tp ） 

啟動此傳輸句柄的正常關閉程序。

在正常關閉初始化后，傳輸獲取不到新的引用。 然而，當前使用傳輸的現有對象仍然可以使用該傳輸來發送和接收數據包。 所有的對象釋放對該引用后傳輸將立即銷毀。

注意：從回調onTransportState（）獲取句柄后，應用程序通常會使用此API。

參數tp -傳輸句柄。

32）void hangupAllCalls （ void ） 

終止所有呼叫

這將啟動所有當前活動呼叫的呼叫掛斷。

33）void mediaAdd （ AudioMedia ＆ media ） 

將媒體添加到媒體列表。

參數media -要添加的媒體

34）void mediaRemove （ AudioMedia ＆ media ） 

從媒體列表中刪除媒體。

參數media -要移除的媒體

35）bool mediaExists （ const AudioMedia ＆ media ） const

檢查媒體是否已添加到媒體列表。

返回 如果添加了媒體，則為真，否則為false。

參數media -要檢查的媒體

36）unsigned  mediaMaxPorts （ ） mediaMaxPorts獲取媒體端口的最大數量

返回 會議橋中媒體端口的最大數量。

37）unsigned  mediaActivePorts （ ） mediaActivePorts

獲取橋活性介質端口的當前數目

返回會議橋中媒體端口的最大數量

38）const AudioMediaVector ＆ mediaEnumPorts （ ） mediaEnumPorts

枚舉所有媒體端口。

返回 媒體端口列表。

39）AudDevManager ＆ audDevManager （ ） 

獲取音頻設備管理器的實例。

返回 音頻設備管理器。

40）VidDevManager ＆ vidDevManager （ ） 

獲取視頻設備管理器的實例。

返回 視頻設備管理器。

41）const CodecInfoVector ＆ codecEnum （ ） 

枚舉所有支持的編解碼器在系統中。

返回 編解碼器信息數組。

42）void codecSetPriority （ const string＆ codec_id ，pj_uint8_t priority ） 

更改編解碼優先級

參數codec_id -編解碼器ID，它是唯一標識編解碼器的字符串（如“speex / 8000”）。

priority -編解碼器優先級0-255，其中0表示禁用編解碼器。

43）CodecParam codecGetParam （ const string＆ codec_id ） const¶

獲取編解碼器參數

返回 編解碼器參數。 如果沒有找到編解碼器，則會拋出錯誤 。

參數codec_id - 編解碼器ID。

44）void codecSetParam （ const string＆ codec_id ， const CodecParam param ） 

設置編解碼器參數

參數 codec_id - 編解碼器ID。

param -編解碼器參數設置。 設置為NULL將編解碼器參數重置為庫默認設置。

45）const CodecInfoVector ＆ videoCodecEnum （ ） 

枚舉所有支持的視頻編解碼器在系統中。

返回  視頻編解碼器信息數組。

46）void videoCodecSetPriority （ const string＆ codec_id ，pj_uint8_t priority ） 

更改視頻編解碼優先級

參數codec_id - 編解碼器ID，其是唯一標識編解碼器的字符串（例如“H263 / 90000”）。 有關詳細信息，請參閱pjsua手冊或pjmedia編解碼器參考。

priority - 編解碼器優先級0-255，其中0表示禁用編解碼器。

47）VidCodecParam getVideoCodecParam （ const string＆ codec_id ） const¶

獲取視頻編解碼器參數。

返回

編解碼器參數。 如果沒有找到編解碼器，則會拋出錯誤 。

參數

• codec_id -

編解碼器ID。

48）void setVideoCodecParam （ const string＆ codec_id ， const VidCodecParam ＆ param ） 

設置視頻編解碼器參數。

參數

• codec_id -

編解碼器ID。

• param -

編解碼器參數設置。

49）void resetVideoCodecParam （ const string＆ codec_id ） 

將視頻編解碼器參數重置為庫默認設置。

參數

• codec_id -

編解碼器ID。

50）virtual void onNatDetectionComplete （ const OnNatDetectionCompleteParam ＆ prm ） 

端點完成使用natDetectType（）啟動的NAT類型檢測時的回調。

參數

• prm -

包含檢測結果的回調參數。

51）virtual  void onNatCheckStunServersComplete （ const OnNatCheckStunServersCompleteParam ＆ prm ） 

當Endpoint完成執行調用libInit（）或調用natCheckStunServers（）或natUpdateStunServers（）時啟動的STUN服務器檢查時的回調。

參數prm -回調參數

52）virtual  void onTransportState （ const OnTransportStateParam ＆ prm ） 

傳輸狀態發生變化時調用此回調。

參數prm -回調參數

53）virtual  void onTimer （ const OnTimerParam ＆ prm ） 

計時器觸發時回調。

計時器由utilTimerSchedule（）調度 。

參數prm -回調參數

54）virtual  void onSelectAccount （ OnSelectAccountParam ＆ prm ） 

應用程序可以使用此回調來覆蓋用於處理傳入消息的帳戶。

最初，使用的帳戶將由圖書館自動計算。 如果應用程序沒有實現此回調，則該初始帳戶將被使用，或者從此回調返回時應用程序設置無效的帳戶。

請注意，目前需要帳號分配的傳入消息是INVITE，MESSAGE，SUBSCRIBE和未經請求的NOTIFY。 這個回調可以在SIP事件本身的回叫之前被調用，即：來電，尋呼機，訂閱或者非請求事件。

參數 prm - 回調參數

 公共靜態功能

55）static Endpoint ＆ instance （ ） 

檢索端點的單例實例。

 

4.7.2 端點配置

Endpoint
struct pj::EpConfig
#include <endpoint.hpp>

 

endpoint配置

公共功能

　　void readObject（const ContainerNode＆node）

　　　　從容器讀取此對象。

　　　　參數

　　　　•node - 要從中寫入值的容器。

 

　　void writeObject（ContainerNode＆node）

　　　　將此對象寫入容器。

　　　　參數

　　　　　　•node - 要將值寫入的容器。

公有成員

　　UaConfig uaConfig

　　　　UA配置

　　LogConfig logConfig

　　　　記錄配置。

　　MediaConfig medConfig

　　　　媒體配置

媒體

struct pj::MediaConfig

此結構描述媒體配置，在調用Lib :: init（）時指定。

從pj :: PersistentObject繼承

記錄

struct pj::LogConfig

記錄配置，可以（可選）在調用Lib :: init（）時指定。

從pj :: PersistentObject繼承

class pj::LogWriter

用於編寫日志消息的界面

應用程序可以繼承此類並在LogConfig結構中提供它，以實現自定義日志寫入工具。

公共函數

virtual ~LogWriter（）

析構器

virtual void write（const LogEntry＆entry ） = 

寫一個日志條目。

struct pj::LogEntry

包含由LogWriter寫入的日志條目的數據。

用戶代理

struct pj::UaConfig

SIP用戶代理相關設置。

從pj :: PersistentObject繼承

回調參數

struct pj::OnNatDetectionCompleteParam

Endpoint :: onNatDetectionComplete（）回調的參數。

struct pj::OnNatCheckStunServersCompleteParam

對Endpoint :: onNatCheckStunServersComplete（）回調的參數。

struct pj::OnTimerParam

端點::的OnTimer（）回調的參數

struct pj::OnTransportStateParam

端點:: onTransportState（）回調的參數

struct pj::OnSelectAccountParam

端點:: onSelectAccount（）回調的參數

其他

struct pj::PendingJob