Android SDK 1.0.0 API 接口参考
SDK Version: 1.0.0
Platform: Android
本页是客户可调用接口的签名索引与行为卡。每张表同时给出用途、前置条件、默认值、结果/错误、线程和配对清理；可复制代码在“示例”列链接页面。诊断能力不属于客户 API。
通用规则
timeoutMs均为毫秒且必须非负；等待 GATT、AT、RF 或设备 callback 的方法在后台线程调用。Boolean只表示该接口定义的成功，不保证后续异步业务已完成；文件/连接等最终状态看 callback。- 返回
null表示无合法值、失败、超时或不支持；除非接口明确允许，否则不要用旧缓存替代。 - AT、Auth、Init、文件和模式切换共享无线通道，不得并发。
- 所有
add...Listener(x)与remove...Listener(x)使用同一个x配对。
XTalkBleClient：初始化、状态与连接
| 完整签名 | 用途/前置 | 返回、错误、线程/生命周期 | 示例 |
|---|---|---|---|
setApplicationContext(context: Context?) | 初始化前保存 Application Context | Unit；null 清除；主线程可调用 | 初始化 |
ensureInitialized(): InitResult | 初始化核心与 callbacks；可重复 | 仅 INIT_OK 继续；主线程可首次调用 | 初始化 |
addListener(listener: DeviceStateCallback) | 扫描/连接状态 | Unit；回调主线程；配 removeListener | 扫描 |
removeListener(listener: DeviceStateCallback) | 释放状态 listener | 必须同实例 | 清理 |
startScan(timeoutMs: Int = 5000, minRssiDbm: Int = -100, serviceUuids: List<String> = emptyList()): ScanStartResult | 权限/蓝牙/Init | 请求结果；callback 给设备；配 stopScan | 扫描 |
stopScan(): Unit | 取消扫描 | 幂等；连接前/离页调用 | 扫描 |
connect(device: XTalkDevice, timeoutMs: Int = 5000, maxReconnectAttempts: Int? = null): ConnectResult | 选中设备；后台线程 | 请求结果，不等于 CONNECTED | 连接 |
awaitConnected(macAddress: String? = null, timeoutMs: Long = 8000): Boolean | 等 CONNECTED；后台线程 | 断线/ERROR/超时 false；内部 listener 自动清理 | 全流程 |
ensureGattServicesOpened(forceReset: Boolean = false): Unit | CONNECTED；后台线程 | 打开 GATT 服务；forceReset 先清绑定 | 连接契约 |
awaitBleReady(timeoutMs: Long = 8000): Boolean | CONNECTED；后台线程 | GATT/AT 稳定为 true | 连接 |
disconnect(sendRemoteCommand: Boolean = true): DisconnectResult | 结束会话；后台线程 | 清缓存/ready；破损链路可传 false | 清理 |
awaitDisconnected(timeoutMs: Long = 6000): Boolean | 等本地 DISCONNECTED；后台 | ERROR/超时 false | 连接契约 |
stopAutoReconnect(reason: String): Boolean | 明确终止自动重连 | manager 不存在/不支持为 false | 连接契约 |
forceResetDisconnected(reason: String, clearLastRequestedDevice: Boolean = true): Unit | 本地/物理状态不一致的高级恢复 | 清追踪、ready、AT；正常路径不用 | 连接契约 |
getConnectedDevice(): XTalkDevice? | 查询当前设备 | 未连接为 null | 状态门槛 |
getConnectionState(): DeviceEventState | 查询状态 | 即时快照 | 状态门槛 |
hasActiveBleLink(): Boolean | CONNECTED 物理门槛 | 不代表 Auth/Init | 状态门槛 |
getDeviceLongId(): Long? | 读已应用结构化 DID | 未认证/可疑值为 null | Auth |
awaitDeviceLongId(timeoutMs: Long = 3000): Long? | 后台等待 DID | 断线/超时 null | Auth |
isWirelessReady(): Boolean | 查询 Init ready | 即时状态 | 状态门槛 |
awaitWirelessReady(timeoutMs: Long = 4000): Boolean | 后台等无线配置结果 | 断线/失败/超时 false | Init |
isReadyForSend(): Boolean | 业务总门槛 | CONNECTED 且 wireless ready | 全流程 |
markWirelessInitRequired(reason: String, resetAtMode: Boolean = true): Unit | 使 Auth/Init 状态失效 | 清 ready；通常由 Auth 调用 | Auth |
setWirelessInitReady(ready: Boolean, reason: String): Unit | Auth/Init 集成写状态 | 客户业务不得伪造 true | Init |
XTalkBleClient：AT、无线与高级状态
| 完整签名 | 契约 | 结果/错误/线程 | 示例 |
|---|---|---|---|
isAtXorEnabled(): Boolean | 当前连接 AT 编码 | 即时 | 编码选择 |
setAtXorEnabledForConnection(enabled: Boolean, reason: String): Unit | Auth/适配器切换编码 | Advanced；连接/断开重置 | 编码选择 |
chooseAtXorModeByFreqProbeResult(timeoutMs: Long = 1500, log: Boolean = true): AtXorModeProbeResult? | 普通/XOR 探测 | 后台；不可用/超时 null | 编码选择 |
withWirelessOpLock(block: () -> T): T | 串行客户高级操作 | 后台；block 异常透传；不可递归等待 | AT |
runAtCommand(command: String, timeoutMs: Long = 3000, log: Boolean = true, errorPolicy: BleAtErrorPolicy = FAIL_FAST, stopWhen: ((List<String>) -> Boolean)? = null, drainResponseTailAfterStop: Boolean = false): List<String> | 独占 AT 事务；CONNECTED | 未连接/服务/发送/ERROR/超时可抛；后台 | AT |
sendAtCommand(command: String): SendResult | 发送 AT，不取响应 | 后台；枚举结果 | AT |
sendAtCommandNoWait(command: String): Boolean | 低延迟写 AT | 只表示受理 | AT |
sendEncryptedAt(bytes: ByteArray): Boolean | 已编码 AT 字节 | Advanced；只表示发送受理 | AT |
setPassthroughListener(listener: ((ByteArray) -> Unit)?): Unit | 底层透传唯一所有者 | Advanced；null 释放；会与 AT 事务冲突 | AT |
restoreTextPttDefaults(defaultRateMode: Int = 7, defaultAddtl: Int = 1, defaultWorkMode: Int = 21): Boolean | 恢复业务模式 | 后台；全部 AT 成功才 true | 无线设置 |
setRateMode(rateMode: Int): Boolean | 设置 0..255 rate | 后台；设备不支持/断线 false | 无线设置 |
setChannelFrequency(freqHz: Long, timeoutMs: Long = 3000): Boolean | callback 配置 channel | 后台；失败/超时 false | 无线设置 |
setFrequencyHz(freqHz: Long, timeoutMs: Long = 3000): Boolean | AT 设置四路频率 | 后台；异常/超时 false | 无线设置 |
setRealtimeWorkModeOverride(workMode: Int?): Unit | 会话覆盖 work mode | null 清除 | 语音 |
getRealtimeWorkModeOverride(): Int? | 查询 override | 未设置 null | 语音 |
AtXorModeProbeResult 字段为 useXor: Boolean 与 normalFreqAccepted: Boolean。BleAtErrorPolicy 为 FAIL_FAST、COLLECT_UNTIL_COMPLETE。
XTalkBleClient：发送、媒体、设备
| 完整签名 | 返回/生命周期 | 示例 |
|---|---|---|
sendBinaryFrame(data: ByteArray): SendResult | 普通二进制；后台 | 二进制 |
sendRfPayloadAndWaitSendFinish(rawPayload: ByteArray, timeoutMs: Long): Boolean | 等完成；后台；失败/超时 false | RF |
sendRfPayloadNoWait(rawPayload: ByteArray): Boolean | 实时受理；空包 false；调用方节流 | RF |
sendText(text: String): SendResult | 文本；接收看 Text listener | 文本 |
sendFile(fileBytes: ByteArray): SendResult | 请求；最终看 FileSend callback | 文件 |
cancelFileSend(): SendResult | 取消发送请求 | 文件 |
cancelFileReceive(): SendResult | 取消接收请求 | 文件 |
startPttVoiceCapture(enablePcmCallback: Boolean = true): CaptureStartResult | 需录音权限；配 stopPttVoiceCapture | 语音 |
stopPttVoiceCapture(): CaptureStopResult | 停 PTT | 语音 |
startRealtimeVoiceCapture(peopleCount: Int = 2, mute: Int = 0): CaptureStartResult | 需录音权限；配 stopRealtimeVoiceCapture | 语音 |
stopRealtimeVoiceCapture(): CaptureStopResult | 停实时采集 | 语音 |
stopVoiceCaptureLocal(): CaptureStopResult | 本地异常清理 | 语音 |
startVoicePlayback(pcm: ByteArray): PlaybackStartResult | PCM 格式按交付要求；配 stop | 播放 |
stopVoicePlayback(): PlaybackStopResult | 停播放 | 播放 |
transcodeImage(imageBytes: ByteArray, targetTier: ImageTargetTier, inputFormat: ImageInputFormat? = null): ImageTranscodeResult | 离线；大图后台；无需 BLE | 图片 |
setCryptoKey16(key16: ByteArray): Boolean | 必须 16 字节；失败禁止加密业务 | 密钥 |
getHardwareVersion(timeoutMs: Long = 2000): String? | 后台；缓存；失败/不支持 null | 设备查询 |
getFirmwareVersion(timeoutMs: Long = 2000): String? | 同上 | 设备查询 |
getBatteryLevel(timeoutMs: Long = 4000): Int? | 后台；最多内部尝试；失败/不支持 null | 设备查询 |
Listener 接口
| 添加/移除签名 | Callback | 线程与数据规则 |
|---|---|---|
addDataListener(DataReceivedCallback) / removeDataListener(...) | bytes/len/SNR/RSSI | I/O；只读 len 范围 |
addDeviceManageListener(DeviceManageCallback) / removeDeviceManageListener(...) | type/value | 主线程；按 type 转换 value |
addTextListener(TextReceivedCallback) / removeTextListener(...) | source/text/SNR/RSSI | 主线程 |
addVoiceListener(VoiceReceivedCallback) / removeVoiceListener(...) | source/PCM/len/metrics/isLast | 实时线程，不阻塞 |
addVoiceCaptureListener(VoiceCaptureCallback) / removeVoiceCaptureListener(...) | PCM/len/isLast | 主线程 |
addFileSendListener(FileSendCallback) / removeFileSendListener(...) | progress/sent/total/result | 主线程 |
addFileReceiveListener(FileReceiveCallback) / removeFileReceiveListener(...) | progress/received/total/result/bytes | 主线程；客户保存最终 bytes |
BLE 顶层工具
| 签名 | 结果 |
|---|---|
requiredBluetoothPermissions(): List<String> | 当前系统扫描/连接权限 |
requiredStartupPermissions(): List<String> | BLE + 录音 + 适用时通知权限 |
hasBluetoothPermissions(context: Context): Boolean | 全部 BLE 权限是否已授予 |
hasStartupPermissions(context: Context): Boolean | 全部 startup 权限是否已授予 |
sanitizeBleDeviceName(rawName: String?): String? | 合法显示名或 null |
isSupportedBleDeviceName(rawName: String?): Boolean | 是否匹配支持名称 |
isSupportedBleDevice(device: XTalkDevice): Boolean | 同上，设备版 |
bleDeviceDisplayName(device: XTalkDevice): String | 合法名或大写 MAC |
mergeBleDeviceIdentity(reported: XTalkDevice?, fallback: XTalkDevice?): XTalkDevice? | 合并结果或 null |
XTALK_SCAN_UUID_5632G: String | 扫描服务 UUID 常量 |