PJSUA2开发文档--第五章 帐户（号）Accounts

第五章 帐户（号）

帐户提供正在使用该应用程序的用户的身份（或身份）。一个帐户有一个与之相关的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（）

析构器