# Android 原生 RTC SDK 函数参考

适用 同批交付 AAR。`AkNativeRtcClient` 负责信令、独立 WHIP/WHEP 媒体、设备会话、重连和资源释放；Activity/Fragment 负责按钮、布局、相机/麦克风授权、MediaProjection 和生命周期。构造时传 `Context`、本地 `SurfaceViewRenderer` 和 `Listener`，退出时调用 `close()`。先按[Android 接入步骤](android.md)完成依赖与只看入会。

```java
AkNativeRtcClient rtc = new AkNativeRtcClient(getApplicationContext(), localRenderer, listener);
rtc.setInitialMediaEnabled(false, false);
rtc.joinWithAccessTicket(serverUrl, roomId, accessTicket, null);
// 入会成功后的远端 VideoTrack 交给宿主自己的 SurfaceViewRenderer。
```

实际 `joinWithAccessTicket` 重载和回调参数以同批 AAR 源码/IDE 提示为准；`serverUrl` 必须是手机可信的 HTTPS 地址，不能填 Mac 的 `127.0.0.1`。加入会议的票据只用一次，SDK 内部维护设备令牌；宿主不保存 ZLM secret。

## 会话、身份与录制

| 方法 | 入参 | 结果 | 特殊情况 |
|---|---|---|---|
| `AkNativeRtcClient(context, localRenderer, listener)` | 应用上下文、本机渲染器、事件接收器 | SDK 对象 | 渲染器由 SDK 初始化；同一 Activity 不要重复构造多个活动客户端。 |
| `joinWithAccessTicket(...)` | 服务地址、会议 ID、一次性票据、可选口令/初始媒体参数 | `Listener.onJoined(participantId)` 或错误回调 | `Waiting` 仅等候准入；系统授权或网络失败不等于已经入会。 |
| `createMeeting(settings, creator, callback)` | JSON 设置、业务后端创建回调、结果回调 | `roomId/accessTicket` 或错误 | `creator` 由你的业务后端完成身份校验；相同失败重试保留幂等标识。 |
| `listMembers()` | 无 | `Listener.onMembers(JSONArray)` | 成员状态可能因断线/换机变化；用事件或重新查询更新 UI。 |
| `getParticipantId()`、`getCapabilities()`、`getRole()` | 无 | 当前成员 ID、能力集合、角色 | 未入会或重新入会时值可能变化；不能以 UI 上旧角色跳过服务端校验。 |
| `performRoomAction(action, payload, callback)` | [白名单动作](room-actions.md)、JSON 参数、`RoomCallback` | `success(value)` 或 `httpFailure(error)`/`failure(message)` | 控制操作结果与 HTTP 状态须分开处理；未知动作在 SDK 拒绝。 |
| `startContinuousRecording(callback)`、`stopContinuousRecording(recordingId, callback)`、`getContinuousRecording(callback)` | 停止需本次录制 ID | JSON 状态或无活动录制 | 启停仅当前主持人；`Stopping` 不是可下载，状态变化经 `onContinuousRecordingChanged`。 |
| `leave()`、`close()` | 无 | `onLeft()`；对象释放 | `leave` 离开当前设备；`close` 结束对象生命周期与线程/媒体资源。被踢后不要拿旧票重入。 |
| `listDemoRooms(baseUrl)`、`createDemoMeeting(...)`、`issueDemoAccessTicket(...)` | 测试环境参数 | 对应 `onDemoRooms/onDemoAccessTicket` 或回调 | 只用于 Demo；正式应用通过自己的后端取票。 |

`RoomCallback.httpFailure(RtcHttpException)` 保留状态码和可能存在的 `retryable`；该值可为空。401 要换票或重新认证，403 是角色/设备/能力被拒，不能循环重发。`onState` 是状态文字，不能代替 `success` 或实际媒体状态。

## 摄像头、麦克风与屏幕

| 方法 | 入参 | 结果 | 特殊情况 |
|---|---|---|---|
| `setInitialMediaEnabled(microphone, camera)`、`setInitialMicrophoneEnabled(enabled)` | 布尔值 | 更新首次入会意图 | 入会前设置；不跳过系统权限。 |
| `hasLocalMicrophone()`、`hasLocalCamera()`、`isMicrophoneEnabled()`、`isCameraEnabled()` | 无 | 本机能力与实际开关 | 不把设备存在等同于已授予发布权限。 |
| `setMicrophoneEnabled(enabled)`、`setCameraEnabled(enabled)` | 布尔值 | 异步改变本地轨道 | 以 `onLocalMediaState` 和远端接收确认；主持人收权或网络失败时不能假设成功。 |
| `setCameraForeground(foreground)` | Activity 是否在前台 | 调整摄像头生命周期 | 退到后台时遵守 Android 采集限制；回前台由 SDK 恢复可恢复的轨道。 |
| `listCameras()`、`switchCamera(cameraId)` | 摄像头 ID | `CameraDevice` 列表 / `onCameraChanged` | 前后摄以 `frontFacing` 区分；设备拔插后 ID 可能变化。 |
| `getInputDevices()`、`getAudioRouter()` | 无 | 输入设备和音频路由控制对象 | 宿主用它们显示设备/扬声器选择，尊重蓝牙与系统路由变化。 |
| `startScreenShare(permission, width, height)`、`stopScreenShare()` | 用户批准的 MediaProjection `Intent`、目标尺寸 | `onScreenSharingChanged` | 必须先由宿主触发系统授权；屏幕是独立发布，权限被撤销应停止。 |
| `attachScreenSession(...)`、`updateScreenSessionToken(token)` | 受信任广播/共享服务的会话上下文 | 更新共享发布身份 | 仅同 App 受信任进程；短时令牌不得日志输出或跨应用传递。 |
| `getSupportedVideoModes()`、`getEndpointInfo()` | 无 | `JSONArray` 模式 / `JSONObject` 终端参数 | 分辨率是设备候选，不保证当前已达到；实际值看媒体统计。 |

## 远端、协作与诊断

| 方法 | 入参 | 结果 | 特殊情况 |
|---|---|---|---|
| `getVideoPresentation()` | 无 | 远端显示变换控制器 | 镜像/旋转只改变本地渲染，不更改源视频或录像。 |
| `applyVideoTransform(renderer, transform)` | `SurfaceViewRenderer`、镜像/翻转/旋转 | 静态渲染辅助方法 | 对支持变换的渲染器应用本地显示效果；普通渲染器不保证全部变换能力。 |
| `participantForPublication(publicationId)` | 独立发布 ID | 成员 ID 或 `null` | 同一成员多路视频与多台设备不要按显示名合并。 |
| `getActiveSpeakerIds()`、`setRemoteAudioVolume(publicationId, volume)` | 发布 ID、0～1 音量 | 发言成员快照 / 本地音量改变 | 发言是媒体活动检测；音量只影响本机，不向远端下静音命令。 |
| `sendChatMessage(text, targetParticipantId)`、`uploadAttachment(...)` | 文本/文件、可选私发目标 | 聊天/附件事件 | 私发附件仅目标与发送者可见；上传完成边界重新校验设备。 |
| `downloadAttachment(...)`、`copyAttachmentTo(...)`、`downloadWhiteboardImage(...)` | 获准附件对象或 ID、回调/输出流 | 字节或错误 | 不把物理文件路径暴露给业务端；大文件用流式复制。 |
| `uploadWhiteboardImage(uri, callback)` | 本机图片 URI | 白板素材附件 | 上传素材不等于绘制；还需白板对象事件，收权会阻止最终提交。 |
| `sendHandRaised(raised)`、`sendReaction(reaction)` | 布尔值或受支持的反应名 | 会议事件 | 不改变媒体发布权限。 |

`Listener` 的关键事件：`onRemoteVideo/onRemoteVideoRemoved`、`onRemoteAudio/onRemoteAudioRemoved` 管每路视图和声音；`onLocalMediaState` 与 `onMediaPermissionChanged` 管按钮；`onCapabilitiesChanged` 管主持权限；`onWhiteboardEvent/onChatMessage` 管协作；`onContinuousRecordingChanged` 管录制标志；`onHttpError` 管状态码；`onLeft` 做最终清理。旧会话事件不能应用到新设备会话。

会后独立客户端 `AkRtcArchiveClient` 的初始化、查询与资源方法见[档案 SDK](archive-api.md)。当前 AAR 可编译不等于旧安装包已更新，验收须在目标真机看见双向视频帧与声音。