第五章 帳戶（號）
帳戶提供正在使用該應用程序的用戶的身份（或身份）。一個帳戶有一個與之相關的SIP統一資源標識符（URI）。在SIP術語中，該URI用作該人的記錄地址（ Address of Record，AOR），並且用作傳出請求中的From頭。
帳戶可能有也可能沒有與之相關聯的客戶注冊。帳戶也與路由集和一些認證憑證相關聯，這些憑證在使用該帳戶發送SIP請求消息時使用。帳戶還具有狀態，當它們訂閱該帳戶時，該狀態將被報告給遠端（遠程對等體），或者如果為該帳戶啟用了發布，則該狀態發布到呈現（Presence）服務器。
必須在應用程序中創建至少一個帳戶，因為任何外發請求都需要一個帳戶上下文。如果不需要用戶關聯，應用程序可以通過調用Account.create（）來創建一個無用戶帳戶。無用戶帳戶識別本地端點而不是特定用戶，並且它對應於特定的傳輸ID。
還有一個帳戶必須設置為默認帳戶，當pjsua使用更嚴格的匹配規則無法將傳入請求與任何帳戶匹配時，用作帳戶身份。
5.1 子類化Account類（從Account類繼承的子類）
要使用Account類，通常應用程序應該創建自己的子類，以便接收該帳戶的通知。例如：
class MyAccount : public Account
{
public:
MyAccount() {}
~MyAccount() {}
virtual void onRegState(OnRegStateParam &prm)
{
AccountInfo ai = getInfo();
cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=")
<< prm.code << endl;
}
virtual void onIncomingCall(OnIncomingCallParam &iprm)
{
Call *call = new MyCall(*this, iprm.callId);
// Just hangup for now
CallOpParam op;
op.statusCode = PJSIP_SC_DECLINE;
call->hangup(op);
// And delete the call
delete call;
}
};
在其子類中，應用程序可以實現帳戶回調，基本用於處理與該帳戶相關的事件，如：
- SIP注冊的狀態
- 傳入呼叫
- 傳入存在訂閱請求
- 不是從伙伴傳入的即時消息
應用程序需要覆蓋派生類中的相關回調方法來處理這些特定事件。
如果未處理事件，將調用默認操作：
- 來電將不被處理
- 傳入的存在訂閱請求將被接受
- 來自非伙伴的傳入即時消息將被忽略
5.2 創建無用戶帳戶
無用戶帳戶標識特定SIP端點，而不是特定用戶。一些其他SIP軟電話可以稱之為對等模式，這意味着我們通過其地址呼叫另一台計算機，而不是調用特定的用戶ID。例如，我們可能會將自己標識為“ sip：192.168.0.15 ”（無用戶帳戶），而不是“ sip：alice@pjsip.org ”。
在下層PJSUA-LIB API中，無用戶帳戶與SIP傳輸相關聯，並且使用pjsua_acc_add_local()API 創建。這個概念在PJSUA2中已經被棄用了，而且一個無用戶帳號是一個沒有用戶名的ID URI（例如“ sip：192.168.0.15 ”），是一個沒有注冊的“正常”賬戶。因此，創建無用戶帳戶與創建“正常”帳戶完全相同。
5.3 創建帳號
我們需要配置AccountConfig並調用Account.create（）來創建帳戶。至少，pjsua只需要帳戶的ID，這是一個URI來標識帳戶（或者在SIP術語中，它被稱為記錄地址/ AOR）。以下是一個代碼片段：
AccountConfig acc_cfg;
acc_cfg.idUri = "sip:test1@pjsip.org";
MyAccount *acc = new MyAccount;
try {
acc->create(acc_cfg);
} catch(Error& err) {
cout << "Account creation error: " << err.info() << endl;
}
以上創建的帳戶不會執行任何操作，除非在發件人的“發件人”標題中提供身份。該帳戶不會注冊到SIP服務器或任何東西。
通常，將希望該帳戶認證並注冊到SIP服務器，以便可以接收來電。為此，需要在AccountConfig中配置一些更多設置，如下所示：
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;
}
5.4 帳戶配置
在AccountConfig中可以指定更多的設置，如：
- AccountRegConfig，指定注冊設置，如注冊服務器和重試間隔。
- AccountSipConfig，用於指定SIP設置，如憑證信息和代理服務器。
- AccountCallConfig，用於指定呼叫設置，例如是否需要可靠的臨時響應（SIP 100rel）。
- AccountPresConfig來指定狀態設置，例如是否啟用在線發布（PUBLISH）。
- AccountMwiConfig，指定MWI（留言等待指示）設置。
- AccountNatConfig，用於指定NAT設置，例如是否使用STUN或ICE。
- AccountMediaConfig，用於指定媒體設置，如安全RTP（SRTP）相關設置。
- AccountVideoConfig，用於指定視頻設置，如默認捕獲和渲染設備。
有關更多信息，請參閱AccountConfig參考文檔。
5.5 帳戶操作
Account對象的一些操作：
- 管理注冊
- 管理好友/聯系人
- 管理在線狀態
請參閱帳戶的參考文檔了解更多信息。呼叫，存在和好友將在后面的章節中進行說明。
5.6 類參考
類參考
5.6.1 Account帳號
class pj::Account
帳戶
公有函數
1）Account（）
構造函數
2）virtual ~Account（）
析構器
請注意，如果該帳戶被刪除，它也將刪除PJSUA-LIB中的相應帳戶。
3）void create（const AccountConfig＆cfg，bool make_default = false ）
創建帳戶
參數cfg -帳號配置
make_default -將其設為默認帳戶。
4）void modify（const AccountConfig＆cfg ）修改帳戶以使用指定的帳戶配置。根據變更，這可能會導致帳戶的注銷或重新注冊。
參數cfg -要應用於帳戶的新帳戶配置。
5）bool isValid（） const檢查此帳戶是否仍然有效。
返回 true如果有效
6）void setDefault（）
將此設置為默認帳戶以在傳入和傳出請求與任何帳戶不匹配時使用。
返回 PJ_SUCCESS成功。
7）bool isDefault（） const檢查這個帳戶是否是默認帳戶。默認帳戶將用於與任何其他帳戶不匹配的傳入和傳出請求。
返回 如果這是默認帳戶，則為true。
8）INT getId（） const獲取與此帳戶相關聯的PJSUA-LIB帳戶ID或索引。
返回 整數大於或等於零。
9）AccountInfo getInfo（） const獲取帳戶信息。
返回 帳戶信息。
10）void setRegistration（ bool renew ） 更新注冊或執行注銷。如果要手動更新注冊或從服務器注銷，通常只需要調用此函數。
參數renew - 如果是false，將執行注銷。
11）void setOnlineStatus（const PresenceStatus＆pres_st ）設置或修改要發布給遠程/現場訂閱帳戶的在線狀態。如果此帳戶有服務器端存在訂閱，和/或出站PUBLISH（如果此帳戶啟用了存在發布），則會觸發發送傳出的NOTIFY請求。
參數 pres_st - 在線狀態。
12）void setTransport（TransportId tp_id ）將此帳戶鎖定/綁定到特定的傳輸/偵聽器。
通常，應用程序不需要這樣做，因為庫將根據目的地自動選擇傳輸。當帳戶被鎖定/綁定到特定的傳輸時，來自該帳戶的所有傳出請求將使用指定的傳輸（包括SIP注冊，對話（呼叫和事件訂閱）以及諸如MESSAGE之類的對話外請求）。注意，傳輸ID也可以在AccountConfig中指定。
參數 tp_id - 傳輸ID。
13）void presNotify（const PresNotifyParam＆prm ）發送NOTIFY以通知帳戶存在狀態或終止服務器端存在訂閱
如果應用程序想要拒絕傳入的請求，它應該將PresNotifyParam.state的參數設置為PJSIP_EVSUB_STATE_TERMINATED。
參數prm -發送NOTIFY參數。
14）const BuddyVector＆enumBuddies（） const
枚舉帳戶的所有好友。
返回 好友列表。
15）buddy * findBuddy（string URI，FindBuddyMatch * buddy_match = NULL ） const在具有指定URI的好友列表中找到一個好友。
異常：如果沒有找到好友，PJ_ENOTFOUND將被拋出。
返回 指向好友的指針
參數 uri -好友URI。
buddy_match -好友匹配算法
16）void addBuddy（Buddy * buddy ）一個內部功能，將一個好友添加到帳戶好友列表。應用程序不能使用此功能。
17）void removeBuddy（Buddy * buddy ）
從帳戶好友列表中刪除好友的內部功能。應用程序不能使用此功能。
18）virtual void onIncomingCall（OnIncomingCallParam＆prm ）來電時通知應用程序。
參數prm -回調參數
19）virtual void onRegStarted（OnRegStartedParam＆prm ）注冊或注銷登記時通知申請。
注意，這只會通知初始注冊和注銷。一旦注冊會話處於活動狀態，后續刷新將不會導致此回調被調用。
參數prm - 回調參數
20）virtual void onRegState（OnRegStateParam＆prm ）注冊狀態發生變化時通知申請。應用程序可能會查詢帳戶信息以獲取注冊詳細信息。
參數prm -回調參數
21）virtual void onIncomingSubscribe（OnIncomingSubscribeParam＆prm ）收到傳入SUBSCRIBE請求時的通知。
應用程序可以使用此回調來授權傳入的訂閱請求（例如，如果請求被授予，請求用戶許可）。
如果未實現此回調，則將接受所有傳入的存在訂閱請求。
如果實現這個回調，在處理傳入的請求時應用程序有幾個選擇：
它可以通過在IncomingSubscribeParam.code參數中指定非200類最終響應立即拒絕該請求。
它可以通過指定200作為IncomingSubscribeParam.code參數來立即接受該請求。如果應用程序未設置任何值給IncomingSubscribeParam.code參數，則這是默認值。在這種情況下，庫將從該回調返回時自動發送NOTIFY請求。
它可能延遲處理請求，例如要求用戶許是接受還是拒絕請求。在這種情況下，該應用程序必須設置IncomingSubscribeParam.code參數202，然后立即調用presNotify（）與狀態PJSIP_EVSUB_STATE_PENDING，並在之后調用presNotify（）再次接受或拒絕訂閱請求。
200和202以外的任何IncomingSubscribeParam.code將被視為200。
應用程序必須立即從此回調中返回（例如，在等待用戶確認時不得阻止此回調）。
參數prm - 回調參數
22）virtual void onInstantMessage（OnInstantMessageParam＆prm ）調用上下文接收通知應用程序傳入的即時消息或尋呼（即消息請求）
參數prm - 回調參數
23）virtual void onInstantMessageStatus（OnInstantMessageStatusParam＆prm ）
通知應用程序傳送狀態，關於傳出尋呼/即時消息（即，MESSAGE）請求的傳送狀態。
參數prm -回調參數
24）virtual void onTypingIndication（OnTypingIndicationParam＆prm ）通知應用程序打字指示。
參數prm -回調參數
25）virtual void onMwiInfo（OnMwiInfoParam＆prm ）
關於MWI（消息等待指示Message Waiting Indication）狀態變化的通知。
可以在SUBSCRIBE請求的狀態更改（例如，202 /接收到SUBSCRIBE被接收）或接收到NOTIFY reqeust時調用此回調。
參數prm -回調參數
公共靜態功能
26）static Account * lookup（ int acc_id ）
獲取指定帳戶ID 的帳戶類。
返回 該帳戶實例或NULL（如果沒有找到）。
參數acc_id -要查找的帳號
5.6.2 AccountInfo
struct pj::AccountInfo
struct pj::AccountInfo
#include <account.hpp>
帳戶信息。
應用程序可以通過調用Account :: getInfo （）來查詢帳戶信息。
5.6.3 帳戶設置
1）AccountConfig
struct pj::AccountConfig
帳戶配置，從pj :: PersistentObject繼承
2）AccoutRegConfig
struct pj::AccountRegConfig
帳戶注冊配置，在AccountConfig中指定。從pj :: PersistentObject繼承
3）AccountSipConfig
struct pj::AccountSipConfig
帳戶的各種SIP設置。在AccountConfig中指定。從pj :: PersistentObject繼承
4）AccountCallConfig
struct pj::AccountCallConfig
帳戶的通話設置。在AccountConfig中指定。從pj :: PersistentObject繼承
5）AccountPresConfig
struct pj::AccountPresConfig
帳戶存在配置。這將在AccountConfig中指定。從pj :: PersistentObject繼承
6）AccountMwiConfig
struct pj::AccountMwiConfig帳號 MWI（留言等待指示，Message Waiting Indication）設置。
在AccountConfig中指定。從pj :: PersistentObject繼承
7）AccountNatConfig
struct pj::AccountNatConfig帳戶的NAT（網絡地址轉換）設置
在AccountConfig中指定。從pj :: PersistentObject繼承
8）AccountMediaConfig
struct pj::AccountMediaConfig帳戶媒體配置（適用於音頻和視頻）
在AccountConfig中指定。從pj :: PersistentObject繼承
9）AccountVideoConfig
struct pj::AccountVideoConfig帳號視頻配置
在AccountConfig中指定。從pj :: PersistentObject繼承
5.6.4 回調參數
10）struct pj::OnIncomingCallParam
此結構包含onIncomingCall（）帳戶回調的參數。
11）struct pj::OnRegStartedParam
此結構包含onRegStarted（）帳戶回調的參數。
12）struct pj::OnRegStateParam
此結構包含onRegState（）帳戶回調的參數。
13）struct pj::OnIncomingSubscribeParam
此結構包含onIncomingSubscribe（）回調的參數。
14）struct pj::OnInstantMessageParam
onInstantMessage（）帳戶回調的參數。
15）struct pj::OnInstantMessageStatusParam
onInstantMessageStatus（）帳戶回調的參數。
16）struct pj::OnTypingIndicationParam
onTypingIndication（）帳戶回調的參數。
17）struct pj::OnMwiInfoParam
onMwiInfo（）帳戶回調的參數。
18）struct pj::PresNotifyParam
presNotify（）帳戶方法的參數。
5.6.5 其他
class pj::FindBuddyMatch
Buddy匹配算法的包裝類。
默認算法是Buddy URI 中搜索令牌的簡單子字符串查找，區分大小寫。應用程序可以通過覆蓋此類並在Account :: findBuddy（）中指定其實例來實現自己的匹配算法。
公有函數
19）virtual bool match（const string＆token，const Buddy＆buddy ）
默認算法實現。
20）virtual ~FindBuddyMatch（）
析構器
