# 1V1 呼叫邀请场景 (/zh-CN/realtime-media/rtm/best-practice/one-to-one-call/cpp)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在线体验本场景} href="https://rtm-demo.shengwang.cn/social/one-to-one-call?utm_source=docs&utm_medium=scenario_doc" external />
查看 Demo 源码} href="https://github.com/AgoraIO-Community/RTM-Demo/tree/master/src/scenes/one-to-one-call" external />
## 场景介绍 [#场景介绍-4]
一对一呼叫中,主叫希望找到指定用户并发起通话;被叫需要先看到来电,再决定接听或拒绝。双方尚未进入同一个音视频频道时,先由 RTM 传递邀请信令,再由 RTC 建立音视频连接。
一次完整的呼叫按以下顺序执行:
1. 双方登录 RTM,安装呼叫邀请模块,等待或发起呼叫。
2. 主叫向指定用户发送邀请,被叫展示来电。
3. 被叫接听,主叫确认;各端确认邀请已接受后,开始连接 RTC。
4. RTC 媒体建立后,界面进入通话状态。
5. 用户静音、恢复或挂断;结束后释放媒体资源,下一次呼叫创建新邀请。
被叫拒绝、主叫在等待期间取消,都是正常业务分支,双方不进入 RTC。无人应答、网络异常或媒体未建立时,则按相应截止时间结束等待并提示原因。
Web Demo 使用双页面演示语音通话,邀请设计也可用于视频呼叫。页面上的“呼叫 ID”是用户的 RTM 用户 ID;每次邀请另有唯一的 `callId`,用于关联本次信令与媒体。
| 能力 | 负责 | 不负责 |
| --- | --- | --- |
| RTM | 呼叫、接听、拒绝、取消等点对点信令,消息发布结果和本端连接状态 | 音视频传输、媒体通话状态 |
| RTC | 加入频道、音视频传输、感知目标用户加入与离开 | 呼叫邀请信令 |
### 接入分层 [#接入分层-4]
呼叫功能由三层组成。Demo 中的呼叫邀请模块目前为 Web 版本,**在 C++ 上,你需要参照它的信令协议和状态设计实现中间一层**(关键代码见 [3. 实现指南](#3-实现指南)),再完成 App 层的工作:
| 层 | 是什么 | 负责 |
| ----------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| RTM SDK | 声网提供的实时消息 SDK | 点对点消息投递与送达结果、对方是否在线、本端连接状态与自动重连 |
| 呼叫邀请模块(`invitation/`) | 基于 RTM 点对点消息实现的呼叫逻辑。Demo 提供 Web 版本,C++ 上参照其协议实现 | 定义呼叫信令协议,维护两端的呼叫状态,处理各阶段超时与邀请重试,记录失败原因 |
| App | 你的业务代码 | 安装与销毁模块、按状态渲染界面、按失败原因提示用户、接通后加入 RTC、媒体等待截止、占线策略 |
> 呼叫邀请模块不是 RTM SDK 的接口,而是一份 Web 参考实现。在 C++ 上,需要参照其信令协议和状态设计自行实现。
### 术语 [#术语-4]
| 术语 | 含义 |
| -------------------- | ------------------------------------------------------------------------ |
| 主叫 / 被叫 | 发起呼叫的一方 / 接收呼叫的一方,即 Caller / Callee |
| 邀请 | 一次呼叫在 RTM 侧的过程,从发起到出现结果为止。每次呼叫有唯一的 `callId` |
| 接听消息(accepted) | 被叫点击接听后发给主叫的消息 |
| 确认消息(ACK) | 主叫收到接听消息后回给被叫的消息,被叫据此确认接通 |
| 终态 | 邀请的最终结果:已接受、已拒绝、已取消或失败。进入终态后状态不再变化 |
### 核心规则 [#核心规则-4]
1. **将呼叫邀请模块安装在 App 已登录的唯一 RTM client 上**。登出前先销毁模块,重新登录后重新安装。
2. **App 自己的点对点消息监听必须忽略 `CALL_KIT_` 系列 `customType`**。
3. **以模块的状态驱动界面**。
4. **接受即邀请结束,之后只看 RTC**。加入频道时设置媒体等待截止;挂断只离开 RTC 频道。
5. **按失败原因提示用户**。不在 App 层叠加自动重试。
## 1. 为什么 1V1 呼叫需要 RTM [#1-为什么-1v1-呼叫需要-rtm-4]
呼叫发生在音视频通道建立之前,RTC 无法承担这一阶段的工作:
- 发起呼叫时,被叫还不在任何 RTC 频道中,无法通过 RTC 通知对方"有来电";
- 振铃、接听、拒绝、取消、无人应答都是业务动作,RTC 没有对应接口;
- 主叫需要区分"对方不在线""网络异常""对方没应答"并给出不同提示,RTC 无法提供这些信息;
- 两端需要先确认"这次呼叫已被接受",再各自加入频道,否则会出现一方已入会、另一方仍在振铃的情况。
因此呼叫需要一条独立于音视频的实时信令通道。如果用 WebSocket 或业务服务端转发自建这条通道,需要同时解决长连接维持与断线重连、按用户路由点对点消息、判断对方是否在线、确认消息是否送达,以及海量连接下的容量与可用性保障。RTM 直接提供这些能力:
| RTM 提供的能力 | 在呼叫中的效果 |
| ---------------------------------- | ------------------------------------------------------------------------ |
| `USER` 点对点消息 | 呼叫、接听、拒绝、取消、确认五种信令都通过它在两个用户之间直接传递 |
| 点对点消息发送成功即表示对方已收到 | 主叫无需等待额外回执,就能确认邀请已送达对方设备(`RECEIVED_BY_CALLEE`) |
| 发送错误码 `-11033`(对方不在线) | 主叫能明确提示"对方不在线"(`PEER_OFFLINE`) |
| `linkState` 连接状态 | 发送失败时判断是本端网络问题(`LOCAL_NETWORK_ERROR`)还是对方问题 |
| 长连接与自动重连 | 网络短暂波动时连接自动恢复 |
## 2. 设计原则 [#2-设计原则-4]
本节内容与平台无关。
### 2.1 复用 App 已登录的 RTM client [#21-复用-app-已登录的-rtm-client-4]
呼叫邀请模块安装在 App 已有的 RTM client 上,不创建新 client,也不负责登录和登出:
- 传给模块的 `userId` 必须与 RTM 登录时使用的 UID 一致;
- 在 `login()` 成功后安装模块;
- **登出前先销毁模块,重新登录后重新安装**。模块的 dispose() 会解绑模块自身的事件监听,因此销毁后需要创建新的模块实例,才能继续接收来电。
### 2.2 隔离邀请信令与 App 自有消息 [#22-隔离邀请信令与-app-自有消息-4]
邀请信令使用 `USER` Channel 点对点发送,并通过以下 `customType` 标识:
| `customType` | 方向 | 含义 |
| --------------------------------------- | ----------- | -------- |
| `CALL_KIT_INVITE` | 主叫 → 被叫 | 发起呼叫 |
| `CALL_KIT_ACCEPT`(`type: "accepted"`) | 被叫 → 主叫 | 被叫接听 |
| `CALL_KIT_ACCEPT`(`type: "ack"`) | 主叫 → 被叫 | 主叫确认 |
| `CALL_KIT_REFUSE` | 被叫 → 主叫 | 被叫拒绝 |
| `CALL_KIT_CANCEL` | 主叫 → 被叫 | 主叫取消 |
SDK 会把收到的每条消息同时分发给模块和 App 自己注册的 `message` 监听。模块只处理上述 `customType`,**App 的监听则需要主动跳过它们**(代码见 [3.3 接收与分发信令](#33-接收与分发信令))。App 自己的点对点业务消息请使用独立的 `customType`。
每条邀请信令都可以携带 `extra` 字段,即 App 自定义字符串,模块原样透传。
### 2.3 以状态驱动界面 [#23-以状态驱动界面-4]
模块在两端各维护一份邀请状态,并在状态变化时回调。App 只需把状态映射到界面:
| 端 | 状态 | 界面 | 可用操作 |
| ---- | -------------------------------------------- | -------------------------------- | ---------- |
| 主叫 | `SENT_TO_CALLEE` | 正在呼叫… | 取消 |
| 主叫 | `RECEIVED_BY_CALLEE` | 正在呼叫… | 取消 |
| 主叫 | `ACCEPTED_BY_CALLEE` | 接通中,开始加入 RTC | 挂断 |
| 主叫 | `REFUSED_BY_CALLEE` / `CANCELED` / `FAILURE` | 显示结果后关闭呼叫界面(见 [2.6 按失败原因提示用户](#26-按失败原因提示用户)) | — |
| 被叫 | `INVITATION_RECEIVED` | 来电界面 | 接听、拒绝 |
| 被叫 | `ACCEPT_SENT_TO_CALLER` | 接通中 | — |
| 被叫 | `ACCEPTED` | 开始加入 RTC | 挂断 |
| 被叫 | `REFUSED` / `CANCELED_BY_CALLER` / `FAILURE` | 显示结果后关闭来电界面(见 [2.6 按失败原因提示用户](#26-按失败原因提示用户)) | — |
`RECEIVED_BY_CALLEE` 表示邀请已送达对方设备,不代表对方已看到来电,因此界面仍显示"正在呼叫"。点击拒绝或取消后,界面立即显示结果,无需等待对方收到。
完整的状态定义与流转见 [附录:邀请状态与流转](#附录邀请状态与流转)。
### 2.4 接受即邀请结束,通话交给 RTC [#24-接受即邀请结束通话交给-rtc-4]
主叫进入 `ACCEPTED_BY_CALLEE`、被叫进入 `ACCEPTED` 后,邀请就结束了。之后的通话完全由 RTC 负责:两端各自加入同一个 RTC 频道;**挂断只需离开 RTC 频道**,对方感知到你离开后结束通话,不需要发送 RTM 消息。
**接受不等于接通**。以下两种情况都会出现"一方在等待、另一方不会进来":
| 场景 | 主叫 | 被叫 | 结果 |
| ----------------------------- | ------------------ | ---------------------------------- | ------------ |
| 被叫网络差,没收到确认消息 | 已接受,已加入 RTC | 等待确认超时,邀请失败,不加入 RTC | 双方无法通话 |
| 被叫收到确认,但加入 RTC 失败 | 已接受,已加入 RTC | 已接受,RTC 加入失败 | 双方无法通话 |
因此 **App 必须设置媒体等待截止**:开始建立 RTC 时计时,未在截止时间内建立媒体就结束本次通话并提示用户。Demo 默认使用 15 秒(代码见 [3.6 接通后进入 RTC 与挂断](#36-接通后进入-rtc-与挂断))。
### 2.5 超时与重试:用默认值,按需调整 [#25-超时与重试用默认值按需调整-4]
模块为邀请的每个等待阶段都设置了截止时间,并会在 INVITE 发送失败时自动重试。以下默认值即 Demo 的建议配置:
| 配置项 | 默认值 | 含义 |
| -------------------------- | ------ | ---------------------------------------------------- |
| `sendTimeoutMs` | 30000 | 主叫发送邀请的总时长上限,包含重试 |
| `maxRetries` | 2 | 邀请发送失败后的重试次数(首次 + 2 次重试,共 3 次) |
| `retryIntervalMs` | 2000 | 两次重试之间的间隔 |
| `callerInvitationExpireMs` | 30000 | 邀请送达后,主叫等待对方接听或拒绝的时长 |
| `calleeInvitationExpireMs` | 30000 | 被叫从收到来电到完成接通(含等待确认消息)的时长 |
主叫和被叫各自计时,起点不同,因此两端不保证同时到期。
### 2.6 按失败原因提示用户 [#26-按失败原因提示用户-4]
邀请结束时,回调中的 `state` 表示结果,失败时 `reason` 表示原因。建议按下表给出提示。
**主叫**
| 结果 | `reason` | 建议处理 |
| ------------------- | ----------------------------------------------------------------------------- | ---------------------------- |
| `REFUSED_BY_CALLEE` | — | 对方已拒绝 |
| `CANCELED` | — | 已取消 |
| `FAILURE` | `PEER_OFFLINE` | 对方不在线 |
| `FAILURE` | `LOCAL_NETWORK_ERROR` / `PUBLISH_TIMEOUT` / `PUBLISH_FAILED` / `SEND_TIMEOUT` | 网络异常,可提供"重新呼叫" |
| `FAILURE` | `PEER_NO_RESPONSE` | 对方无应答,可提供"再次呼叫" |
| `FAILURE` | `STOPPED` | 无需提示 |
**被叫**
| 结果 | `reason` | 建议处理 |
| -------------------- | --------------------- | -------------------------- |
| `CANCELED_BY_CALLER` | — | 对方已取消,可记为未接来电 |
| `FAILURE` | `INVITATION_EXPIRE` | 来电超时,可记为未接来电 |
| `FAILURE` | `ACCEPT_ACK_TIMEOUT` | 接通失败 |
| `FAILURE` | `LOCAL_NETWORK_ERROR` | 网络异常 |
| `FAILURE` | `STOPPED` | 无需提示 |
排查问题时,回调中的 `trigger`(触发条件)、`sdkError`(SDK 原始错误)和 `linkStateAtFailure`(失败时的网络状态)可以帮助定位原因。
### 2.7 多来电与占线 [#27-多来电与占线-4]
模块允许同时存在多个来电,每个来电独立计时、独立处理,**不会自动拒绝其他来电**。占线策略由 App 决定。
Demo 同一时间只保留一路通话。通话中收到新来电时,来电继续计时,用户可以拒绝;通话结束后,仍在有效期内的来电可以接听。
## 3. 实现指南 [#3-实现指南-4]
基础接入见 [实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start/cpp),凭证准备见 [部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation) 和 [客户端鉴权](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication/cpp)。
以下代码基于 RTM C++ SDK 2.x 和 RTC C++ SDK 4.x,接口名和参数以实际接入的 SDK 版本为准。
Demo 中的呼叫邀请模块目前只有 Web 版本。本节展示如何用 C++ SDK 按同一套信令协议实现模块的关键环节:信令收发、超时与重试、失败原因判断和接通后的 RTC 处理。完整的状态定义与流转以附录为准。
C++ SDK 的异步业务方法返回类型为 `void`,通过 `requestId` 输出参数提供请求编号;调用结果通过 `IRtmEventHandler` 中对应的 `onXxxResult` 回调返回,回调在 SDK 线程中触发。为保证状态读写串行,示例约定:
- 所有 SDK 回调先通过 App 的 `postToAppThread()` 切换到业务线程,再处理状态,下文代码不再重复这一步;
- 计时使用 App 的 `scheduleAfter(delayMs, task)`,返回的句柄可通过 `cancelScheduled()` 取消;
- 回调中的字符串指针只在回调期间有效,切换线程前先复制为 `std::string`。
以上三个函数由 App 基于自己的事件循环实现。RTM 示例中的成员函数属于 `InvitationModule`;该类继承 `std::enable_shared_from_this`,并由 `std::shared_ptr` 创建和持有,才能使用下文的 `shared_from_this()`。`Invitation::retryTimer` 与 `deadlineTimer` 使用同一种 App 定时任务句柄类型,并初始化为空句柄。所有延迟任务及转发到业务线程的 SDK 结果都通过弱引用访问模块;`dispose()` 在业务线程调用,停止转发、取消任务并清理发送回调,随后才能释放最后一个模块引用。主叫和被叫的邀请使用同一个 `Invitation` 结构,用 `isCaller` 区分角色;状态名与附录一致。
### 3.1 信令定义与发送 [#31-信令定义与发送-3]
每条信令都使用 `USER` Channel 点对点发送,`customType` 标识信令类型,消息体为 JSON 文本 `{ callId, extra, type? }`,其中 `type` 只用于 `CALL_KIT_ACCEPT`:
```cpp
static const char* CALL_KIT_INVITE = "CALL_KIT_INVITE";
static const char* CALL_KIT_ACCEPT = "CALL_KIT_ACCEPT"; // type: "accepted" 或 "ack"
static const char* CALL_KIT_REFUSE = "CALL_KIT_REFUSE";
static const char* CALL_KIT_CANCEL = "CALL_KIT_CANCEL";
bool isCallKitType(const std::string& t) {
return t == CALL_KIT_INVITE || t == CALL_KIT_ACCEPT || t == CALL_KIT_REFUSE || t == CALL_KIT_CANCEL;
}
struct Signal {
std::string callId;
std::string extra;
std::string type; // 仅 CALL_KIT_ACCEPT 使用
};
// 发送结果在 onPublishResult 中返回;USER 消息发送成功即表示对方已收到
using SendCallback = std::function;
void sendSignal(const std::string& peerUid, const char* customType, const Signal& signal, SendCallback callback) {
const std::string body = toJson(signal); // 由 App 的 JSON 库实现
PublishOptions options;
options.channelType = RTM_CHANNEL_TYPE_USER;
options.messageType = RTM_MESSAGE_TYPE_STRING;
options.customType = customType;
uint64_t requestId = 0;
rtmClient_->publish(peerUid.c_str(), body.c_str(), body.size(), options, requestId);
if (callback) pendingSends_[requestId] = std::move(callback);
}
// IRtmEventHandler
void onPublishResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override {
auto it = pendingSends_.find(requestId);
if (it == pendingSends_.end()) return;
SendCallback callback = std::move(it->second);
pendingSends_.erase(it);
callback(errorCode);
}
```
主叫发起呼叫时生成 `callId`:16 字节随机数转成 32 位大写十六进制字符串。
```cpp
std::string newCallId() {
std::random_device rd;
std::uniform_int_distribution dist(0, 255);
char buf[33] = {0};
for (int i = 0; i < 16; ++i) snprintf(buf + i * 2, 3, "%02X", dist(rd));
return std::string(buf);
}
```
### 3.2 安装与配置 [#32-安装与配置-4]
超时与重试参数使用 [2.5 超时与重试:用默认值,按需调整](#25-超时与重试用默认值按需调整) 中的默认值,可按业务调整:
```cpp
struct InvitationOptions {
int64_t sendTimeoutMs = 30000; // INVITE 发送总截止,包含重试
int maxRetries = 2; // 发送失败后的重试次数
int64_t retryIntervalMs = 2000; // 重试间隔
int64_t callerInvitationExpireMs = 30000; // 主叫等待接听或拒绝
int64_t calleeInvitationExpireMs = 30000; // 被叫处理来电与等待确认
};
```
C++ SDK 通过创建 client 时传入的唯一 `IRtmEventHandler` 分发事件。呼叫邀请模块不单独注册监听,而是由 App 的 handler 把事件转交给模块:登录成功后让模块开始处理事件(安装),登出前停止转交,并将未结束的邀请置为 `FAILURE`(`STOPPED`)(销毁)。模块同时记录连接状态,用于判断失败原因。
```cpp
// 以下成员函数属于 InvitationModule;App 用 shared_ptr 持有模块。
// InvitationModule 继承 std::enable_shared_from_this。
void install(bool messageLinkConnected) {
linkConnected_ = messageLinkConnected;
installed_ = true;
}
void dispose() {
installed_ = false;
for (auto& item : invitations_) {
cancelScheduled(item.second.deadlineTimer);
cancelScheduled(item.second.retryTimer);
fail(item.second, Reason::STOPPED);
}
pendingSends_.clear();
}
// 由 App 的 IRtmEventHandler::onLinkStateEvent 转交
void onLinkState(const IRtmEventHandler::LinkStateEvent& event) {
if (event.serviceType != RTM_SERVICE_TYPE_MESSAGE) return;
const auto currentState = event.currentState;
linkConnected_ = currentState == RTM_LINK_STATE_CONNECTED;
if (currentState == RTM_LINK_STATE_FAILED) {
// 连接彻底失败:未结束的邀请全部失败
for (auto& item : invitations_) fail(item.second, Reason::LOCAL_NETWORK_ERROR);
}
// 暂时断连不重置截止,也不立即结束邀请
}
```
每个阶段使用基于本地单调时钟的截止值 `endTs`,不与系统日期时间或其他设备的时钟比较。计时器只负责到点唤醒检查;收到消息、用户操作或发送结果时,也先检查截止。设备从休眠恢复时,对所有未结束的邀请执行一次 `onDeadline` 检查。
```cpp
using Clock = std::chrono::steady_clock;
bool isExpired(const Invitation& inv) { return Clock::now() >= inv.endTs; }
void enterStage(Invitation& inv, State state, Clock::time_point endTs) {
inv.state = state;
inv.endTs = endTs;
cancelScheduled(inv.deadlineTimer);
const auto delayMs = std::max(0,
std::chrono::duration_cast(endTs - Clock::now()).count());
const std::string callId = inv.callId;
std::weak_ptr weakSelf = shared_from_this();
inv.deadlineTimer = scheduleAfter(delayMs, [weakSelf, callId] {
auto self = weakSelf.lock();
if (self && self->installed_) self->onDeadline(callId);
});
notifyStateChanged(inv);
}
void onDeadline(const std::string& callId) {
Invitation* inv = get(callId);
if (inv == nullptr || inv->ended || !isExpired(*inv)) return;
switch (inv->state) {
case State::SENT_TO_CALLEE: fail(*inv, Reason::SEND_TIMEOUT); break;
case State::RECEIVED_BY_CALLEE: fail(*inv, linkConnected_ ? Reason::PEER_NO_RESPONSE : Reason::LOCAL_NETWORK_ERROR); break;
case State::INVITATION_RECEIVED: fail(*inv, Reason::INVITATION_EXPIRE); break;
case State::ACCEPT_SENT_TO_CALLER: fail(*inv, Reason::ACCEPT_ACK_TIMEOUT); break;
default: break;
}
}
// 进入终态后不再变化,迟到的消息和发送结果都不能改变它
void end(Invitation& inv, State terminal, Reason reason = Reason::NONE) {
if (inv.ended) return;
inv.ended = true;
inv.state = terminal;
inv.reason = reason;
cancelScheduled(inv.deadlineTimer);
cancelScheduled(inv.retryTimer);
notifyStateChanged(inv);
}
void fail(Invitation& inv, Reason reason) {
end(inv, State::FAILURE, reason); // 主叫为 FAILURE(6),被叫为 FAILURE(16)
}
```
### 3.3 接收与分发信令 [#33-接收与分发信令-3]
模块只处理 `USER` Channel 中 `CALL_KIT_` 系列 `customType` 的消息,按信令类型分发。格式不合法、`callId` 不存在或发送者不是该邀请的对方时,直接忽略。App 的 `onMessageEvent` 先把邀请信令交给模块,其他消息走 App 自己的业务逻辑:
```cpp
// App 的 IRtmEventHandler
void onMessageEvent(const MessageEvent& event) override {
const std::string customType = event.customType ? event.customType : "";
if (event.channelType == RTM_CHANNEL_TYPE_USER && isCallKitType(customType)) {
// 复制回调数据后切换到业务线程
std::string from = event.publisher;
std::string body(event.message, event.messageLength);
// App 的 invitation_ 类型为 std::shared_ptr
std::weak_ptr weakModule = invitation_;
postToAppThread([weakModule, from, customType, body] {
if (auto module = weakModule.lock()) module->onSignal(from, customType, body);
});
return; // 不再交给 App 自己的消息处理
}
handleAppMessage(event);
}
// 呼叫邀请模块
void onSignal(const std::string& from, const std::string& customType, const std::string& body) {
if (!installed_) return;
Signal signal;
if (!parseSignal(body, signal)) return; // 格式不合法时忽略
if (customType == CALL_KIT_INVITE) onInvite(from, signal);
else if (customType == CALL_KIT_ACCEPT && signal.type == "accepted") onAccepted(from, signal);
else if (customType == CALL_KIT_ACCEPT && signal.type == "ack") onAck(from, signal);
else if (customType == CALL_KIT_REFUSE) onRefuse(from, signal);
else if (customType == CALL_KIT_CANCEL) onCancel(from, signal);
}
Invitation* find(const std::string& callId, const std::string& from, bool isCaller) {
Invitation* inv = get(callId);
if (inv == nullptr || inv->isCaller != isCaller || inv->remoteUid != from) return nullptr;
return inv;
}
```
### 3.4 主叫:发起与取消 [#34-主叫发起与取消-4]
发起呼叫时进入 `SENT_TO_CALLEE`,并设置发送总截止。发送失败时在截止前按间隔重试,次数耗尽后按 [2.6 按失败原因提示用户](#26-按失败原因提示用户) 判断失败原因。发送成功即进入 `RECEIVED_BY_CALLEE`,开始等待对方响应:
```cpp
std::string call(const std::string& calleeUid, const std::string& extra) {
Invitation& inv = addOutgoing(newCallId(), calleeUid, extra);
enterStage(inv, State::SENT_TO_CALLEE, Clock::now() + std::chrono::milliseconds(options_.sendTimeoutMs));
sendInvite(inv.callId);
return inv.callId;
}
void sendInvite(const std::string& callId) {
Invitation* inv = get(callId);
if (!installed_ || inv == nullptr || inv->ended || isExpired(*inv)) return;
inv->publishing = true;
std::weak_ptr weakSelf = shared_from_this();
sendSignal(inv->remoteUid, CALL_KIT_INVITE, {inv->callId, inv->extra, ""}, [weakSelf, callId](RTM_ERROR_CODE code) {
auto self = weakSelf.lock();
if (!self || !self->installed_) return;
Invitation* inv = self->get(callId);
if (inv == nullptr || inv->ended || self->isExpired(*inv)) return;
inv->publishing = false;
if (code == RTM_ERROR_OK) {
if (inv->state != State::SENT_TO_CALLEE) return;
self->enterStage(*inv, State::RECEIVED_BY_CALLEE,
Clock::now() + std::chrono::milliseconds(self->options_.callerInvitationExpireMs));
} else if (inv->retries < self->options_.maxRetries) {
inv->retries++;
inv->retryTimer = scheduleAfter(self->options_.retryIntervalMs, [weakSelf, callId] {
auto self = weakSelf.lock();
if (!self || !self->installed_) return;
Invitation* inv = self->get(callId);
if (inv != nullptr && !inv->ended && !self->isExpired(*inv)) self->sendInvite(callId);
});
} else {
self->fail(*inv, self->classify(code));
}
});
}
Reason classify(RTM_ERROR_CODE code) {
if (code == RTM_ERROR_CHANNEL_RECEIVER_OFFLINE) return Reason::PEER_OFFLINE; // -11033
if (!linkConnected_) return Reason::LOCAL_NETWORK_ERROR;
if (code == RTM_ERROR_CHANNEL_PUBLISH_MESSAGE_TIMEOUT) return Reason::PUBLISH_TIMEOUT; // -11026
return Reason::PUBLISH_FAILED;
}
```
收到接听消息后立即进入接受终态并回复确认消息,不等待确认消息的发送结果。收到拒绝消息则进入拒绝终态:
```cpp
void onAccepted(const std::string& from, const Signal& signal) {
Invitation* inv = find(signal.callId, from, true);
if (inv == nullptr || inv->ended || inv->state != State::RECEIVED_BY_CALLEE || isExpired(*inv)) return;
end(*inv, State::ACCEPTED_BY_CALLEE);
sendSignal(from, CALL_KIT_ACCEPT, {inv->callId, inv->extra, "ack"}, nullptr);
}
void onRefuse(const std::string& from, const Signal& signal) {
Invitation* inv = find(signal.callId, from, true);
if (inv == nullptr || inv->ended || inv->state != State::RECEIVED_BY_CALLEE || isExpired(*inv)) return;
inv->remoteExtra = signal.extra;
end(*inv, State::REFUSED_BY_CALLEE);
}
```
等待期间用户点击取消时,先提交取消终态,再通知对方:
```cpp
void cancel(const std::string& callId) {
Invitation* inv = get(callId);
if (inv == nullptr || inv->ended) return;
end(*inv, State::CANCELED);
sendSignal(inv->remoteUid, CALL_KIT_CANCEL, {inv->callId, inv->extra, ""}, nullptr);
}
```
在 `extra` 中放入 RTC 频道名等通话所需信息。
### 3.5 被叫:接听与拒绝 [#35-被叫接听与拒绝-4]
首次收到合法的邀请时创建来电并开始计时;重复的邀请复用已有来电,不刷新截止。已结束的邀请在去重窗口内保留,避免重复邀请再次触发来电:
```cpp
void onInvite(const std::string& from, const Signal& signal) {
if (get(signal.callId) != nullptr) return;
Invitation& inv = addIncoming(signal.callId, from, signal.extra);
enterStage(inv, State::INVITATION_RECEIVED,
Clock::now() + std::chrono::milliseconds(options_.calleeInvitationExpireMs));
}
```
:::note[清理建议]
终态后释放不再需要的回调、计时任务和大体积 `extra`;仅保留对方 UID、`callId`、终态及过期时间等最小去重记录。去重缓存应同时设置 TTL 和容量上限,TTL 覆盖本业务允许的发送重试及迟到消息窗口;活动邀请不能因缓存淘汰被删除。定期清理过期记录,账号退出时清空。若要在去重记录淘汰后仍拒绝过期邀请,业务协议还应增加可校验的消息有效期,不能只依赖接收端从“首次收到”开始计时。
:::
用户点击接听时发送接听消息。发送期间 `publishing` 为 `true`,界面禁用接听和拒绝按钮;发送成功后进入 `ACCEPT_SENT_TO_CALLER`,沿用原截止时间等待确认消息;发送失败时来电保持,用户可以再次操作:
```cpp
void accept(const std::string& callId) {
Invitation* inv = get(callId);
if (inv == nullptr || inv->ended || inv->state != State::INVITATION_RECEIVED
|| inv->publishing || isExpired(*inv)) return;
inv->publishing = true;
notifyStateChanged(*inv);
std::weak_ptr weakSelf = shared_from_this();
sendSignal(inv->remoteUid, CALL_KIT_ACCEPT, {inv->callId, "", "accepted"}, [weakSelf, callId](RTM_ERROR_CODE code) {
auto self = weakSelf.lock();
if (!self || !self->installed_) return;
Invitation* inv = self->get(callId);
if (inv == nullptr || inv->ended) return;
inv->publishing = false;
if (code == RTM_ERROR_OK && !self->isExpired(*inv)) {
self->enterStage(*inv, State::ACCEPT_SENT_TO_CALLER, inv->endTs);
} else {
self->notifyStateChanged(*inv);
}
});
}
void onAck(const std::string& from, const Signal& signal) {
Invitation* inv = find(signal.callId, from, false);
if (inv == nullptr || inv->ended || inv->state != State::ACCEPT_SENT_TO_CALLER || isExpired(*inv)) return;
end(*inv, State::ACCEPTED);
}
```
用户点击拒绝时,先提交拒绝终态,再通知对方。收到取消消息时,进入取消终态:
```cpp
void refuse(const std::string& callId) {
Invitation* inv = get(callId);
if (inv == nullptr || inv->ended || inv->state != State::INVITATION_RECEIVED || inv->publishing) return;
end(*inv, State::REFUSED);
sendSignal(inv->remoteUid, CALL_KIT_REFUSE, {inv->callId, "", ""}, nullptr);
}
void onCancel(const std::string& from, const Signal& signal) {
Invitation* inv = find(signal.callId, from, false);
if (inv == nullptr || inv->ended || isExpired(*inv)) return;
if (inv->state == State::INVITATION_RECEIVED || inv->state == State::ACCEPT_SENT_TO_CALLER) {
end(*inv, State::CANCELED_BY_CALLER);
}
}
```
可用 `endTs` 计算剩余振铃毫秒数:
```cpp
const auto remainingMs = std::max(0,
std::chrono::duration_cast(inv.endTs - Clock::now()).count());
```
### 3.6 接通后进入 RTC 与挂断 [#36-接通后进入-rtc-与挂断-4]
进入接受状态后,由 App 加入 RTC,并设置媒体建立的绝对截止时间(Demo 默认 15 秒)。本地加入成功且确认目标用户的音频已开始播放(`onRemoteAudioStateChanged` 报告 `REMOTE_AUDIO_STATE_DECODING`)后,取消媒体等待截止。超时、建立失败或用户挂断时,幂等清理本次媒体会话;邀请保持原有接受终态。
```cpp
static const int64_t MEDIA_TIMEOUT_MS = 15000; // App 层配置,Demo 默认 15 秒
// IRtcEngineEventHandler(回调在 SDK 线程触发,切换到业务线程后处理)
void onRemoteAudioStateChanged(uid_t uid, REMOTE_AUDIO_STATE state,
REMOTE_AUDIO_STATE_REASON reason, int elapsed) override {
postToAppThread([=] {
if (!callActive_ || uid != remoteRtcUid_) return; // remoteRtcUid_:目标用户的 RTC uid
if (state == REMOTE_AUDIO_STATE_DECODING) cancelScheduled(mediaTimer_);
});
}
void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) override {
postToAppThread([=] {
if (callActive_ && uid == remoteRtcUid_) endCall("通话已结束");
});
}
void startCall(const std::string& rtcChannel, const std::string& rtcToken) {
callActive_ = true;
mediaTimer_ = scheduleAfter(MEDIA_TIMEOUT_MS, [this] { endCall("对方未接通"); });
ChannelMediaOptions options;
options.publishMicrophoneTrack = true;
options.autoSubscribeAudio = true;
if (rtcEngine_->joinChannel(rtcToken.c_str(), rtcChannel.c_str(), localRtcUid_, options) != 0) {
endCall("通话建立失败");
}
}
void endCall(const std::string& message) {
if (!callActive_) return; // 超时、对方离开、用户挂断可能先后触发
callActive_ = false;
cancelScheduled(mediaTimer_);
rtcEngine_->leaveChannel();
showToast(message);
backToIdle();
}
```
挂断时调用 `endCall("通话已结束")` 即可。
## 4. 常见错误 [#4-常见错误-4]
**App 的点对点消息监听没有过滤邀请信令**
邀请信令会同时到达 App 自己的监听,被当作普通消息解析或展示。在 App 监听中忽略 `CALL_KIT_` 系列 `customType`。
**为呼叫邀请单独创建或登录一个 RTM client**
同一用户维护多条连接,状态难以一致。模块应安装在 App 已登录的唯一 client 上。
**销毁模块后没有重新安装**
App 调用 dispose() 后,模块已解绑自身的事件监听。重新登录后需要创建新的模块实例,才能继续接收来电。
**用 RTM 消息通知挂断**
接受即邀请结束,挂断只需离开 RTC 频道。
**把"已接受"当作"已接通"**
确认消息可能丢失,RTC 可能加入失败。进入 RTC 时必须设置媒体等待截止。
**对所有失败自动重拨,或在 App 层叠加重试**
对方不在线时重拨仍会失败,无应答时重拨会打扰对方;模块已自动重试,叠加只会延长等待。
## 5. 上线检查清单 [#5-上线检查清单-4]
- 呼叫邀请模块安装在已登录的唯一 RTM client 上,`userId` 与登录 UID 一致
- 登出前销毁模块,重新登录后重新安装
- App 自有的点对点消息监听忽略 `CALL_KIT_` 系列 `customType`
- 界面按 [2.3 以状态驱动界面](#23-以状态驱动界面) 渲染,`publishing` 时禁用操作按钮
- 超时与重试配置已按业务确认,App 层未叠加重试
- 主叫和被叫都按 [2.6 按失败原因提示用户](#26-按失败原因提示用户) 给出提示
- 进入 RTC 时设置媒体等待截止,目标用户的媒体就绪后取消
- 挂断只离开 RTC 频道,不发 RTM 消息
- 已定义占线策略
## 附录:邀请状态与流转 [#附录邀请状态与流转-4]
本附录供需要深入了解模块行为或自行实现邀请逻辑的开发者参考。
### 主叫状态 [#主叫状态-4]
| 状态 | 含义 |
| ----------------------- | ---------------------------------------------- |
| `IDLE(0)` | 已创建,尚未开始 |
| `SENT_TO_CALLEE(1)` | 正在发送邀请,包括失败后的重试 |
| `RECEIVED_BY_CALLEE(2)` | 邀请已送达被叫,等待接听或拒绝 |
| `ACCEPTED_BY_CALLEE(3)` | 被叫已接听(终态) |
| `REFUSED_BY_CALLEE(4)` | 被叫已拒绝(终态) |
| `CANCELED(5)` | 主叫已取消(终态) |
| `FAILURE(6)` | 发送失败、等待超时、网络断开或模块销毁(终态) |
### 被叫状态 [#被叫状态-4]
| 状态 | 含义 |
| --------------------------- | ------------------------------------------------ |
| `IDLE(10)` | 已创建,尚未处理邀请 |
| `INVITATION_RECEIVED(11)` | 来电中,等待用户操作;接听消息发送中也保持此状态 |
| `ACCEPT_SENT_TO_CALLER(12)` | 接听消息已送达主叫,等待确认 |
| `ACCEPTED(13)` | 已收到确认(终态) |
| `REFUSED(14)` | 被叫已拒绝(终态) |
| `CANCELED_BY_CALLER(15)` | 主叫已取消(终态) |
| `FAILURE(16)` | 来电超时、确认超时、网络断开或模块销毁(终态) |
### 模块的消息校验规则 [#模块的消息校验规则-4]
模块收到邀请信令后,以下任一条件不满足即忽略该消息,不影响其他邀请:
1. 消息格式合法,字段完整;
2. `callId` 对应已有的邀请(首次收到的合法邀请会新建被叫邀请);
3. 消息发送者与该邀请的对方 UID 一致;
4. 当前状态允许处理该消息,且未过截止时间。