跳到主要内容

接口说明

更新时间：2026-09-22 13:28:09

PC C++ SDK 接口集合，覆盖初始化、账号登录与登出、设备列表、局域网发现、直播拉流、截图、物模型、DataChannel 指令通道等能力。Windows与Linux通用，参考如下。开发可先阅读用户账号开发指南。

API 总览​

初始化相关

方法说明自从
Initialize初始化 SDKv1.1.0
Uninitialize释放 SDK 资源v1.1.0
GetVersion获取 SDK 版本号v1.1.0
CreateRtcxPcApi创建 API 实例v1.1.0

账号相关

方法说明自从
Login内置账号登录v1.1.0
ThirdLogin自有账号登录v1.1.0
LoginLan进入局域网模式v1.1.0
IsLanMode是否处于局域网模式v1.1.0
Logout登出v1.1.0

局域网发现

方法说明自从
StartLanDiscover开始搜索局域网设备v1.1.0
StopLanDiscover停止搜索v1.1.0
IsLanDiscovering是否正在搜索v1.1.0

设备管理

方法说明自从
GetDeviceList获取设备列表v1.1.0
GetGatewaySubDeviceList获取网关子设备列表v1.1.0
GetDeviceGroupList获取设备分组列表v1.1.0
GetThirdPartyDeviceDetailsAsync异步查询第三方设备详情v1.1.0

物模型

方法说明自从
GetThingProperties获取物模型属性v1.1.0
SetThingProperties设置物模型属性v1.1.0

播放相关

方法说明自从
StartPlay开始拉流v1.1.0
StopPlay停止指定播放v1.1.0
GetPlayTimeline获取播放 Timelinev1.1.0
GetPlayStreamType获取码流类型描述v1.1.0

截图

方法说明自从
Snapshot异步截图v1.1.0

DataChannel

方法说明自从
SendCmdData发送指令数据v1.1.0
DestroyDataChannel销毁指令通道v1.1.0

事件回调

回调说明自从
OnPlayLoading拉流开始加载v1.1.0
OnPlayStarted拉流成功并开始播放v1.1.0
OnPlayRetrying拉流失败并将自动重连v1.1.0
OnPlayError拉流失败v1.1.0
OnSnapshotTaken截图完成v1.1.0
OnLanDeviceDiscovered发现一台局域网设备v1.1.0
OnLanDiscoverFinished局域网搜索结束v1.1.0
OnDataChannelStatusDataChannel 状态v1.1.0
OnDataChannelDataDataChannel 下行数据v1.1.0
OnEncodedVideoData编码视频帧v1.1.0
OnEncodedAudioData编码音频帧v1.1.0
OnThirdPartyDeviceDetails第三方设备详情查询完成v1.1.0
OnDeviceStatusChanged设备上下线v1.1.0

初始化相关​

Initialize​

初始化 SDK：加载配置、日志、网关、信令和播放器。

自从 v1.1.0

static int32_t Initialize(const InitParam &param);

调用时机​

在调用其他 API 之前必须先调用。同一进程只初始化一次。

参数​

参数类型必选默认值说明自从
paramInitParam是无初始化配置v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • < 0：失败。

所属接口类​

IRtcxPcApi（静态方法）

InitParam param;
param.cfgFileName = "config.ini";
param.appKey = "yourAppKey";
param.appSecret = "yourAppSecret";
IRtcxPcApi::Initialize(param);

Uninitialize​

释放 SDK 占用的资源。调用成功后不可再使用 SDK 中的方法或回调；如需再次使用，必须重新 Initialize 并 CreateRtcxPcApi。

自从 v1.1.0

static int32_t Uninitialize();

调用时机​

登出并释放 IRtcxPcApi 实例之后。不建议在任何 SDK 回调中调用。

参数​

无参数。

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • < 0：失败。

所属接口类​

IRtcxPcApi（静态方法）

GetVersion​

获取当前 SDK 版本号。

自从 v1.1.0

static int32_t GetVersion(std::string &version);

调用时机​

Initialize 之后即可调用。

参数​

参数类型必选默认值说明自从
versionstd::string &是（出参）无成功时写入版本字符串，例如 "1.1.0"v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • < 0：失败。

所属接口类​

IRtcxPcApi（静态方法）

CreateRtcxPcApi​

创建 IRtcxPcApi 智能指针，并绑定事件回调。

自从 v1.1.0

static IRtcxPcApi::Ptr CreateRtcxPcApi(const std::shared_ptr<IRtcxPcEvtHandler> handler);

调用时机​

Initialize 成功之后、登录之前。回调对象须在返回的 API 实例生命周期内保持有效。

参数​

参数类型必选默认值说明自从
handlerstd::shared_ptr<IRtcxPcEvtHandler>是无事件回调对象。拉流、截图、局域网发现、DataChannel、设备上下线等结果均通过该对象回调。完整回调列表见 事件回调v1.1.0

返回值​

  • 非空 IRtcxPcApi::Ptr：创建成功。
  • 调用方应在使用完毕后将指针置空，再调用 Uninitialize。

所属接口类​

IRtcxPcApi（静态方法）

账号相关​

Login​

内置账号登录。账号含 @ 时按邮箱验证码登录，否则按手机密码登录。登录成功后会建立信令连接。

自从 v1.1.0

virtual int32_t Login(const std::string &account, const std::string &credential,
                      std::string *errorMessage = nullptr) = 0;

调用时机​

CreateRtcxPcApi 之后。与 ThirdLogin、LoginLan 互斥，同一实例同时只使用一种登录方式。

参数​

参数类型必选默认值说明自从
accountconst std::string &是无登录账号。含 @ 按邮箱验证码登录，否则按手机号密码登录v1.1.0
credentialconst std::string &是无登录凭证。邮箱登录时为验证码，手机登录时为密码v1.1.0
errorMessagestd::string *否nullptr失败时写入错误描述。不需要错误文本时可传 nullptrv1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • RTCX_PC_FAIL（-1）：失败，详见 errorMessage。

所属接口类​

IRtcxPcApi

std::string errorMessage;
int32_t ret = pcapi->Login("13800000000", "password", &errorMessage);

ThirdLogin​

自有账号登录。使用业务侧换取的 authCode 登录，并建立信令连接。

自从 v1.1.0

virtual int32_t ThirdLogin(const std::string &authCode,
                           const std::string &authFlag = "",
                           std::string *errorMessage = nullptr) = 0;

调用时机​

CreateRtcxPcApi 之后。账号体系说明见用户账号开发指南。

参数​

参数类型必选默认值说明自从
authCodeconst std::string &是无自有账号认证码v1.1.0
authFlagconst std::string &否""可选认证标识，按业务账号体系填写；无则保持空v1.1.0
errorMessagestd::string *否nullptr失败时写入错误描述v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • RTCX_PC_FAIL（-1）：失败，详见 errorMessage。

所属接口类​

IRtcxPcApi

LoginLan​

进入纯局域网模式。不走云端账号登录，之后只能通过局域网发现获取设备并拉流。

自从 v1.1.0

virtual int32_t LoginLan() = 0;

调用时机​

CreateRtcxPcApi 之后。进入局域网模式后，IsLanMode 返回 true；物模型、第三方设备详情等云端能力不可用。局域网模式下同时只支持一路播放。

参数​

无参数。

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • RTCX_PC_FAIL（-1）：失败。

所属接口类​

IRtcxPcApi

相关回调​

OnLanDeviceDiscovered、OnLanDiscoverFinished

IsLanMode​

查询当前实例是否处于局域网模式。

自从 v1.1.0

virtual bool IsLanMode() const = 0;

调用时机​

CreateRtcxPcApi 之后随时可调。LoginLan 成功后为 true，Logout 后为 false。

参数​

无参数。

返回值​

  • true：局域网模式。
  • false：云端账号模式。

所属接口类​

IRtcxPcApi

Logout​

登出：停止局域网搜索、停止全部播放、清理 DataChannel、取消设备订阅并断开账号会话。

自从 v1.1.0

virtual int32_t Logout() = 0;

调用时机​

不再使用当前登录会话时调用。之后如需再次使用，重新 Login / ThirdLogin / LoginLan。

参数​

无参数。

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • < 0：失败。

所属接口类​

IRtcxPcApi

局域网发现​

StartLanDiscover​

开始搜索局域网设备。targetIp 为空时广播，非空时向指定 IPv4 单播。

自从 v1.1.0

virtual int32_t StartLanDiscover(const LanDiscoverParam &param = {}) = 0;

调用时机​

LoginLan 成功之后。非局域网模式调用会失败。搜索过程中可再次调用以重启搜索。

参数​

参数类型必选默认值说明自从
paramLanDiscoverParam否{}（广播）搜索参数v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：已开始搜索。
  • RTCX_PC_FAIL（-1）：未处于局域网模式，或启动搜索失败。

所属接口类​

IRtcxPcApi

相关回调​

OnLanDeviceDiscovered、OnLanDiscoverFinished

LanDiscoverParam discoverParam;
discoverParam.targetIp = "";
pcapi->StartLanDiscover(discoverParam);

StopLanDiscover​

停止局域网设备搜索。

自从 v1.1.0

virtual void StopLanDiscover() = 0;

调用时机​

搜索过程中或搜索结束后均可调用。Logout 时会自动停止。

参数​

无参数。

返回值​

无。

所属接口类​

IRtcxPcApi

IsLanDiscovering​

查询是否正在进行局域网搜索。

自从 v1.1.0

virtual bool IsLanDiscovering() const = 0;

调用时机​

StartLanDiscover 之后。搜索结束（OnLanDiscoverFinished）或 StopLanDiscover 后为 false。

参数​

无参数。

返回值​

  • true：正在搜索。
  • false：未在搜索。

所属接口类​

IRtcxPcApi

设备管理​

GetDeviceList​

分页获取当前账号下的设备列表。默认只返回第一页，需自行按 total / pageNo / pageSize 遍历。成功返回的设备会被缓存，供后续 StartPlay、SendCmdData 解析设备身份。

自从 v1.1.0

virtual std::shared_ptr<rtx::account::DeviceList> GetDeviceList(
    const rtx::account::DeviceListReq &deviceListReq) = 0;

调用时机​

云端账号 Login 或 ThirdLogin 成功之后。局域网模式无云端设备列表，应使用局域网发现。

参数​

参数类型必选默认值说明自从
deviceListReqDeviceListReq是无分页与过滤条件v1.1.0

返回值​

  • 非空 std::shared_ptr<DeviceList>：成功。字段见 DeviceList，列表项见 DeviceInfo。
  • 空指针：失败。

所属接口类​

IRtcxPcApi

相关回调​

OnDeviceStatusChanged

rtx::account::DeviceListReq req;
req.pageNo = 1;
req.pageSize = 100;
auto resp = pcapi->GetDeviceList(req);

GetGatewaySubDeviceList​

分页获取网关下的子设备列表。成功返回的子设备会被缓存，供后续拉流使用。

自从 v1.1.0

virtual std::shared_ptr<rtx::account::GatewaySubDeviceList> GetGatewaySubDeviceList(
    const rtx::account::GatewaySubDeviceListReq &req) = 0;

调用时机​

已登录且已拿到网关设备的 iotId 之后。子设备拉流时，StartPlay 的 dstUserId 传父网关 iotId。

参数​

参数类型必选默认值说明自从
reqGatewaySubDeviceListReq是无网关子设备查询条件v1.1.0

返回值​

所属接口类​

IRtcxPcApi

GetDeviceGroupList​

分页获取设备分组列表。默认只返回第一页，需自行遍历。

自从 v1.1.0

virtual std::shared_ptr<rtx::account::DeviceGroupList> GetDeviceGroupList(
    const rtx::account::DeviceGroupListReq &deviceGroupListReq) = 0;

调用时机​

云端账号登录成功之后。可用返回的 groupId 过滤 GetDeviceList。

参数​

参数类型必选默认值说明自从
deviceGroupListReqDeviceGroupListReq是无分组列表查询条件v1.1.0

返回值​

所属接口类​

IRtcxPcApi

GetThirdPartyDeviceDetailsAsync​

异步批量查询第三方设备详情。仅返回查询成功的设备，结果通过 OnThirdPartyDeviceDetails 回调。同一时刻只允许一次查询。

自从 v1.1.0

virtual int32_t GetThirdPartyDeviceDetailsAsync(
    const std::vector<rtx::account::ThirdPartyDeviceQuery> &devices,
    std::string *errorMessage = nullptr) = 0;

调用时机​

云端账号登录成功之后。局域网模式不支持。适用于业务侧已有 iotId / productKey / deviceName，需要补齐完整 DeviceInfo 的场景。

参数​

参数类型必选默认值说明自从
devicesstd::vector<rtx::account::ThirdPartyDeviceQuery>是无待查询设备列表，不能为空。元素见 ThirdPartyDeviceQueryv1.1.0
errorMessagestd::string *否nullptr调用失败时写入错误描述，例如局域网模式、列表为空、回调为空、查询进行中v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：已受理，结果走回调。
  • RTCX_PC_FAIL（-1）：失败，详见 errorMessage。

所属接口类​

IRtcxPcApi

相关回调​

OnThirdPartyDeviceDetails

物模型​

GetThingProperties​

获取设备物模型属性。lastUpdateTime 为 0 表示全量，非 0 表示按时间戳差量获取。

自从 v1.1.0

virtual std::shared_ptr<rtx::account::ThingPropertiesData> GetThingProperties(
    const std::string &iotId, int64_t lastUpdateTime = 0) = 0;

调用时机​

云端账号登录成功之后。局域网模式不支持，返回空指针。

参数​

参数类型必选默认值说明自从
iotIdconst std::string &是无设备唯一标识v1.1.0
lastUpdateTimeint64_t否0差量时间戳。0 为全量；传入上次返回的 maxUpdateTimeValue 可做增量v1.1.0

返回值​

  • 非空 std::shared_ptr<ThingPropertiesData>：成功。见 ThingPropertiesData。
  • 空指针：失败或局域网模式。

所属接口类​

IRtcxPcApi

SetThingProperties​

设置设备物模型属性。items 形如 {"powerstate":0}。多目设备可通过 lensId 指定镜头。

自从 v1.1.0

virtual int32_t SetThingProperties(const std::string &iotId, const Json::Value &items,
                                   int32_t lensId = -1, std::string *errorMessage = nullptr) = 0;

调用时机​

云端账号登录成功之后。局域网模式不支持。

参数​

参数类型必选默认值说明自从
iotIdconst std::string &是无设备唯一标识v1.1.0
itemsconst Json::Value &是无属性键值表，例如 items["powerstate"] = 0v1.1.0
lensIdint32_t否-1多目设备镜头 ID。< 0 表示不带镜头参数v1.1.0
errorMessagestd::string *否nullptr失败时写入错误描述v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：成功。
  • RTCX_PC_FAIL（-1）：失败，详见 errorMessage。

所属接口类​

IRtcxPcApi

Json::Value items;
items["powerstate"] = 0;
std::string errorMessage;
int32_t ret = pcapi->SetThingProperties(iotId, items, -1, &errorMessage);

播放相关​

StartPlay​

开始拉流。Windows 将画面渲染到 hWnd；Linux 无内置渲染时 hWnd 传空，通过编码帧回调取流。网关子设备须把父网关 iotId 传入 dstUserId。

自从 v1.1.0

virtual PlayHandle StartPlay(const std::string &deviceName,
                             const std::string &productKey,
                             void *hWnd,
                             const std::string &dstUserId = "") = 0;

调用时机​

已登录，且目标设备已通过 GetDeviceList、GetGatewaySubDeviceList 或局域网发现进入 SDK 缓存。云端模式支持多路播放；局域网模式同时只支持一路。

参数​

参数类型必选默认值说明自从
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
hWndvoid *是无Windows 渲染窗口句柄（HWND）。Linux 无内置渲染时传 nullptr，通过 OnEncodedVideoData / OnEncodedAudioData 取帧v1.1.0
dstUserIdconst std::string &否""网关子设备传父网关 iotId；普通设备保持空v1.1.0

返回值​

  • 非 INVALID_PLAY_HANDLE：播放句柄，后续 StopPlay / Snapshot / GetPlayTimeline 使用。
  • INVALID_PLAY_HANDLE（0）：失败。常见原因：未登录、设备未在列表中、局域网已有一路播放。设备未找到时还会触发 OnPlayError。

所属接口类​

IRtcxPcApi

相关回调​

OnPlayLoading、OnPlayStarted、OnPlayRetrying、OnPlayError、OnEncodedVideoData、OnEncodedAudioData

PlayHandle playHandle = pcapi->StartPlay(deviceName, productKey, renderHwnd);
PlayHandle subPlayHandle = pcapi->StartPlay(subDeviceName, subProductKey, renderHwnd, gatewayIotId);

StopPlay​

停止指定 PlayHandle 对应的播放。

自从 v1.1.0

virtual void StopPlay(PlayHandle playHandle) = 0;

调用时机​

StartPlay 返回有效句柄之后。传入无效句柄时无效果。Logout 会停止全部播放。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无StartPlay 返回的播放句柄v1.1.0

返回值​

无。

所属接口类​

IRtcxPcApi

GetPlayTimeline​

获取指定播放的 Timeline。出图前 valid 为 false。

自从 v1.1.0

virtual PlayTimelineInfo GetPlayTimeline(PlayHandle playHandle) const = 0;

调用时机​

StartPlay 之后随时可调。首帧出图前 valid=false，出图后可读取各阶段耗时。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄。无效句柄时返回 valid=false 的空结果v1.1.0

返回值​

PlayTimelineInfo。出图前 valid=false。

所属接口类​

IRtcxPcApi

GetPlayStreamType​

获取指定播放当前使用的码流类型描述。

自从 v1.1.0

virtual std::string GetPlayStreamType(PlayHandle playHandle) const = 0;

调用时机​

StartPlay 之后。出图前可能为空。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄。无效句柄返回空字符串v1.1.0

返回值​

码流类型描述字符串；无效句柄或尚未就绪时为空。

所属接口类​

IRtcxPcApi

截图​

Snapshot​

对正在播放的画面异步截图。结果通过 OnSnapshotTaken 回调。

自从 v1.1.0

virtual int32_t Snapshot(PlayHandle playHandle, const std::string &filePath,
                         bool withWatermark = false) = 0;

调用时机​

对应 PlayHandle 已开始播放之后。调用成功仅表示已提交截图请求。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
filePathconst std::string &是无本地保存路径，例如 D:/capture/snap.jpgv1.1.0
withWatermarkbool否false是否叠加水印v1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：已提交。最终成败见 OnSnapshotTaken 的 errCode（0 表示成功）。
  • RTCX_PC_FAIL（-1）：句柄无效或播放器未就绪。

所属接口类​

IRtcxPcApi

相关回调​

OnSnapshotTaken

int32_t ret = pcapi->Snapshot(playHandle, "D:/capture/snap.jpg", false);

DataChannel​

SendCmdData​

通过 DataChannel 向设备发送指令数据。默认可靠传输；需要不可靠传输时将 reliable 设为 false。同一 businessBatchId 绑定一台设备，通道未就绪时请求会入队。

自从 v1.1.0

virtual DataChannelResult SendCmdData(const std::string &businessBatchId,
                                      uint16_t cmdId,
                                      const std::vector<uint8_t> &data,
                                      const std::string &deviceName,
                                      const std::string &productKey,
                                      std::string *errorMessage = nullptr,
                                      bool reliable = true);

调用时机​

已登录，且目标设备已进入 SDK 缓存（先拉设备列表或完成局域网发现）。payload 不超过 128KB。

参数​

参数类型必选默认值说明自从
businessBatchIdconst std::string &是无业务批次 ID，用于标识一条 DataChannel 会话，不能为空。已绑定其他设备时返回 CHANNEL_ERRORv1.1.0
cmdIduint16_t是无指令 ID，由业务与设备约定v1.1.0
dataconst std::vector<uint8_t> &是无指令负载。超过 128KB 返回 DATA_TOO_LARGEv1.1.0
deviceNameconst std::string &是无目标设备名v1.1.0
productKeyconst std::string &是无目标产品 Keyv1.1.0
errorMessagestd::string *否nullptr失败时写入错误描述v1.1.0
reliablebool否truetrue 可靠传输，false 不可靠传输v1.1.0

返回值​

见 DataChannelResult：

  • SUCCESS（0）：通道已就绪，数据已发送。
  • QUEUED（1）：通道尚未就绪，请求已入队，通道建立后自动发送。
  • INVALID_CMD_ID（-1）：指令 ID 无效。
  • DATA_TOO_LARGE（-2）：负载超过 128KB。
  • CHANNEL_ERROR（-3）：未登录、设备未找到、参数为空、会话冲突等。
  • TIMEOUT（-4）：超时。

所属接口类​

IRtcxPcApi

相关回调​

OnDataChannelStatus、OnDataChannelData

std::string errorMessage;
DataChannelResult result = pcapi->SendCmdData(
    "batch-001", 1001, payload, deviceName, productKey, &errorMessage, true);

DestroyDataChannel​

销毁指定 businessBatchId 的 DataChannel 会话。

自从 v1.1.0

virtual int32_t DestroyDataChannel(const std::string &businessBatchId);

调用时机​

该批次指令发送完毕、不再需要通道时。Logout 会清理全部会话。

参数​

参数类型必选默认值说明自从
businessBatchIdconst std::string &是无要销毁的业务批次 IDv1.1.0

返回值​

  • RTCX_PC_SUCCESS（0）：成功（含会话不存在）。
  • < 0：失败。

所属接口类​

IRtcxPcApi

事件回调​

继承 IRtcxPcEvtHandler 并重写所需回调。未重写的回调为空实现。

自从 v1.1.0

所属接口类： IRtcxPcEvtHandler

OnPlayLoading​

拉流信令交互完成，播放器开始建立连接。

自从 v1.1.0

virtual void OnPlayLoading(PlayHandle playHandle, const std::string &deviceName,
                           const std::string &productKey);

触发时机​

StartPlay 之后、画面出现之前。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0

OnPlayStarted​

拉流成功，已开始播放。

自从 v1.1.0

virtual void OnPlayStarted(PlayHandle playHandle, const std::string &deviceName,
                           const std::string &productKey);

触发时机​

播放器开始出流之后。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0

OnPlayRetrying​

拉流失败且即将自动重连。

自从 v1.1.0

virtual void OnPlayRetrying(PlayHandle playHandle, const std::string &deviceName,
                            const std::string &productKey,
                            int32_t attempt, int32_t maxAttempts);

触发时机​

可重试错误发生后、发起下一次重连前。重试耗尽后触发 OnPlayError。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
attemptint32_t是无当前重试序号，从 1 开始v1.1.0
maxAttemptsint32_t是无最大重试次数，一般为 3v1.1.0

OnPlayError​

拉流失败（重试耗尽或不可重试错误）。

自从 v1.1.0

virtual void OnPlayError(PlayHandle playHandle, const std::string &deviceName,
                         const std::string &productKey,
                         PlayFailReason reason, int32_t errCode);

触发时机​

拉流无法恢复时。若 StartPlay 时设备未在缓存中，playHandle 可能为 INVALID_PLAY_HANDLE。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄；设备未找到时可能为 INVALID_PLAY_HANDLEv1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
reasonPlayFailReason是无失败类别v1.1.0
errCodeint32_t是无SIGNAL_ERROR 时为信令业务错误码；SIGNAL_TIMEOUT 时无实际意义；PLAYER_ERROR 时为播放器错误码v1.1.0

OnSnapshotTaken​

截图完成。

自从 v1.1.0

virtual void OnSnapshotTaken(PlayHandle playHandle, const std::string &deviceName,
                             const std::string &productKey,
                             int32_t errCode, const std::string &filePath);

触发时机​

Snapshot 提交后，无论成功失败都会回调。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
errCodeint32_t是无0（PLAYERCODE_SUCCESS）表示成功；PLAYERCODE_SNAPSHOT_ERR 截图失败；PLAYERCODE_SNAPSHOT_MEMORY_LEAK 内存不足v1.1.0
filePathconst std::string &是无保存路径（与调用 Snapshot 时传入的路径一致）v1.1.0

OnLanDeviceDiscovered​

局域网搜索过程中每发现一台新设备回调一次。设备会被写入缓存，之后可直接 StartPlay。

自从 v1.1.0

virtual void OnLanDeviceDiscovered(const LanDiscoveredDevice &device);

触发时机​

StartLanDiscover 过程中。

参数​

参数类型必选默认值说明自从
deviceLanDiscoveredDevice是无发现的设备信息v1.1.0

OnLanDiscoverFinished​

局域网搜索结束。列表可能为空。

自从 v1.1.0

virtual void OnLanDiscoverFinished(const std::vector<LanDiscoveredDevice> &devices);

触发时机​

搜索超时结束或搜索流程完成后。之后 IsLanDiscovering 为 false。

参数​

参数类型必选默认值说明自从
devicesstd::vector<LanDiscoveredDevice>是无本次搜索发现的全部设备，可能为空。元素见 LanDiscoveredDevicev1.1.0

OnDataChannelStatus​

DataChannel 状态回调，失败时触发。

自从 v1.1.0

virtual void OnDataChannelStatus(const std::string &deviceName,
                                 const std::string &productKey,
                                 const std::string &businessBatchId,
                                 int32_t statusCode,
                                 int32_t errorCode,
                                 const std::string &message);

触发时机​

通道打开失败或异常时。statusCode 为 -101（POLARIS_RTC_DATA_CHANNEL_NON_OPENED）表示通道未打开。

参数​

参数类型必选默认值说明自从
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
businessBatchIdconst std::string &是无业务批次 IDv1.1.0
statusCodeint32_t是无状态码。失败时常见 -101v1.1.0
errorCodeint32_t是无错误码v1.1.0
messageconst std::string &是无错误描述v1.1.0

OnDataChannelData​

收到设备经 DataChannel 返回的数据。

自从 v1.1.0

virtual void OnDataChannelData(const std::string &deviceName,
                               const std::string &productKey,
                               const std::string &businessBatchId,
                               uint16_t cmdId,
                               const std::vector<uint8_t> &body);

触发时机​

设备下行指令数据到达时。

参数​

参数类型必选默认值说明自从
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
businessBatchIdconst std::string &是无业务批次 IDv1.1.0
cmdIduint16_t是无指令 IDv1.1.0
bodyconst std::vector<uint8_t> &是无数据内容v1.1.0

OnEncodedVideoData​

编码视频帧回调。Linux 无内置渲染时，StartPlay 传入空 hWnd 后通过本回调取视频。

自从 v1.1.0

virtual void OnEncodedVideoData(PlayHandle playHandle, const std::string &deviceName,
                                const std::string &productKey,
                                uint32_t codecType,
                                uint64_t timestamp,
                                int64_t utcTimeMs,
                                const std::vector<uint8_t> &data);

触发时机​

拉流过程中每帧编码视频到达时。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
codecTypeuint32_t是无编码类型。1 = H264，2 = H265v1.1.0
timestampuint64_t是无媒体时间戳v1.1.0
utcTimeMsint64_t是无UTC 时间，毫秒v1.1.0
dataconst std::vector<uint8_t> &是无编码后的视频数据v1.1.0

OnEncodedAudioData​

编码音频帧回调。codecType 与播放器 POLARISAudioCodecID 一致。

自从 v1.1.0

virtual void OnEncodedAudioData(PlayHandle playHandle, const std::string &deviceName,
                                const std::string &productKey,
                                uint32_t codecType,
                                int32_t sampleRate,
                                int32_t channelNum,
                                uint64_t timestamp,
                                const std::vector<uint8_t> &data);

触发时机​

拉流过程中每帧编码音频到达时。

参数​

参数类型必选默认值说明自从
playHandlePlayHandle是无播放句柄v1.1.0
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
codecTypeuint32_t是无1 = AAC，2 = PCMA，3 = PCMU，4 = G726，5 = OPUSv1.1.0
sampleRateint32_t是无采样率v1.1.0
channelNumint32_t是无声道数v1.1.0
timestampuint64_t是无媒体时间戳v1.1.0
dataconst std::vector<uint8_t> &是无编码后的音频数据v1.1.0

OnThirdPartyDeviceDetails​

第三方设备详情批量查询完成。仅包含查询成功的设备。

自从 v1.1.0

virtual void OnThirdPartyDeviceDetails(
    const std::vector<rtx::account::DeviceInfo> &devices);

触发时机​

GetThirdPartyDeviceDetailsAsync 后台查询结束后。

参数​

参数类型必选默认值说明自从
devicesstd::vector<rtx::account::DeviceInfo>是无查询成功的设备详情，失败项不会出现在列表中。元素见 DeviceInfov1.1.0

OnDeviceStatusChanged​

设备上下线通知。在 GetDeviceList 或 GetGatewaySubDeviceList 成功后，SDK 会订阅对应设备状态。

自从 v1.1.0

virtual void OnDeviceStatusChanged(const std::string &deviceName,
                                   const std::string &productKey,
                                   const std::string &iotId,
                                   DeviceOnlineStatus status,
                                   int64_t timestampMs);

触发时机​

已订阅设备的在线状态变化时。局域网模式不订阅云端状态。

参数​

参数类型必选默认值说明自从
deviceNameconst std::string &是无设备名v1.1.0
productKeyconst std::string &是无产品 Keyv1.1.0
iotIdconst std::string &是无设备唯一标识v1.1.0
statusDeviceOnlineStatus是无在线状态v1.1.0
timestampMsint64_t是无状态变更时间戳，毫秒v1.1.0

数据结构​

RtcxPcCode​

通用返回码。命名空间：rtx::pcsdk。

自从 v1.1.0

枚举值数值说明自从
RTCX_PC_SUCCESS0成功v1.1.0
RTCX_PC_FAIL-1失败v1.1.0

PlayHandle​

播放句柄，类型为 uint64_t。INVALID_PLAY_HANDLE 为 0，表示无效句柄。

自从 v1.1.0

InitParam​

SDK 初始化参数。

自从 v1.1.0

struct InitParam
{
    std::string cfgFileName = "config.ini";
    std::string appKey;
    std::string appSecret;
};
字段类型必选默认值说明自从
cfgFileNamestd::string否"config.ini"配置文件名v1.1.0
appKeystd::string是空平台分配的 App Keyv1.1.0
appSecretstd::string是空平台分配的 App Secretv1.1.0

PlayFailReason​

拉流失败原因。

自从 v1.1.0

枚举值数值说明自从
SIGNAL_ERROR0信令请求失败（设备/网关返回非成功状态），errCode 为信令业务错误码v1.1.0
SIGNAL_TIMEOUT1信令请求超时（20 秒内未收到设备响应），errCode 无实际意义v1.1.0
PLAYER_ERROR2播放器/流媒体内部错误，errCode 为播放器错误码v1.1.0

DataChannelResult​

SendCmdData 返回值。

自从 v1.1.0

枚举值数值说明自从
SUCCESS0通道已就绪，数据已发送v1.1.0
QUEUED1通道尚未就绪，请求已入队v1.1.0
INVALID_CMD_ID-1指令 ID 无效v1.1.0
DATA_TOO_LARGE-2负载超过 128KBv1.1.0
CHANNEL_ERROR-3通道错误（未登录、设备未找到、参数非法等）v1.1.0
TIMEOUT-4超时v1.1.0

DeviceOnlineStatus​

设备在线状态（上下线回调使用）。

自从 v1.1.0

枚举值数值说明自从
Offline0离线v1.1.0
Online1在线v1.1.0
Sleep2休眠v1.1.0

PlayTimelineStep​

Timeline 中的一个阶段。

自从 v1.1.0

字段类型默认值说明自从
labelstd::string空阶段名称v1.1.0
elapsedMsint64_t0从开始到该阶段的累计耗时（毫秒）v1.1.0
stepMsint64_t0该阶段自身耗时（毫秒）v1.1.0

PlayTimelineInfo​

播放 Timeline。

自从 v1.1.0

字段类型默认值说明自从
playModestd::string空播放模式：P2P / CMS / Autov1.1.0
streamTypestd::string空码流类型描述v1.1.0
stepsstd::vector<PlayTimelineStep>空各阶段耗时v1.1.0
validboolfalse是否已出图、数据可用v1.1.0

LanDiscoveredDevice​

局域网发现到的设备。

自从 v1.1.0

字段类型默认值说明自从
ipstd::string空设备 IPv1.1.0
sigPortint32_t9821信令端口v1.1.0
protocolstd::string"TCP"信令协议v1.1.0
productKeystd::string空产品 Keyv1.1.0
deviceNamestd::string空设备名v1.1.0
isGatewayboolfalse是否网关v1.1.0

iotId() 返回 productKey + deviceName。自从 v1.1.0

LanDiscoverParam​

局域网搜索参数。

自从 v1.1.0

字段类型必选默认值说明自从
targetIpstd::string否空空=广播；非空=单播指定 IPv4v1.1.0

OwnedType​

设备与用户的绑定关系。命名空间：rtx::account。

自从 v1.1.0

枚举值数值说明自从
SHARED0被分享的设备v1.1.0
OWNED1拥有的设备v1.1.0
ALL10000全部设备v1.1.0

DeviceStatus​

设备状态。命名空间：rtx::account。

自从 v1.1.0

枚举值数值说明自从
INACTIVE0未激活v1.1.0
ONLINE1在线v1.1.0
SLEEP2休眠v1.1.0
OFFLINE3离线v1.1.0
DISABLE8禁用v1.1.0

NodeType​

设备节点类型。命名空间：rtx::account。

自从 v1.1.0

枚举值数值说明自从
DEVICE0普通设备v1.1.0
GATEWAY1网关v1.1.0
UNKNOWN10000未知v1.1.0

NetType​

设备联网方式。命名空间：rtx::account。

自从 v1.1.0

枚举值数值说明自从
NET_LORA0LoRav1.1.0
NET_CELLULAR12G/3G/4G/5G 蜂窝网v1.1.0
NET_WIFI2Wi-Fiv1.1.0
NET_ZIGBEE3ZigBeev1.1.0
NET_ETHERNET4以太网v1.1.0
NET_OTHER5其他v1.1.0
NET_UNKNOWN10000未知v1.1.0

DeviceListReq​

设备列表请求。命名空间：rtx::account。

自从 v1.1.0

字段类型必选默认值说明自从
iotTokenstd::string否空使用本 SDK 登录后由 SDK 自动填充v1.1.0
pageNouint32_t否1页码，从 1 开始v1.1.0
pageSizeuint32_t否100分页大小，1～100v1.1.0
ownedOwnedType否OwnedType::ALL绑定类型：分享 / 拥有 / 全部v1.1.0
groupIduint64_t否0按分组过滤；0 表示不过滤v1.1.0
isSubDevicebool否falsetrue 获取子设备，false 获取直连设备v1.1.0

DeviceInfo​

设备详情。命名空间：rtx::account。

自从 v1.1.0

字段类型默认值说明自从
identityIduint64_t—用户身份 IDv1.1.0
iotIdstd::string空平台颁发的设备唯一标识v1.1.0
deviceNamestd::string空设备名v1.1.0
productKeystd::string空产品 Keyv1.1.0
productNamestd::string空产品名称v1.1.0
productModelstd::string空产品型号v1.1.0
nickNamestd::string空设备昵称v1.1.0
netTypeNetTypeNET_UNKNOWN联网方式v1.1.0
thingTypestd::string空物类型，普通设备为 DEVICEv1.1.0
statusDeviceStatusOFFLINE设备状态v1.1.0
ownedOwnedTypeALL与用户的关系v1.1.0
nodeTypeNodeTypeDEVICE节点类型v1.1.0
gmtModifieduint64_t—最后修改时间v1.1.0
regionstd::string空设备所在机房v1.1.0
sharePermissionListstd::vector<std::string>空分享权限列表（仅 owned=SHARED 有值）：live、control、record、ptz、voiceIntercom、setting、notificationv1.1.0
groupIduint64_t0分组 IDv1.1.0

DeviceList​

设备列表响应。命名空间：rtx::account。

自从 v1.1.0

字段类型说明自从
totaluint32_t列表总数v1.1.0
pageNouint32_t当前页码v1.1.0
pageSizeuint32_t分页大小v1.1.0
datastd::vector<DeviceInfo>当前页设备v1.1.0

DeviceGroupListReq​

设备分组列表请求。命名空间：rtx::account。

自从 v1.1.0

字段类型必选默认值说明自从
iotTokenstd::string否空使用本 SDK 登录后由 SDK 自动填充v1.1.0
pageNouint32_t否1页码，从 1 开始v1.1.0
pageSizeuint32_t否100分页大小，1～100v1.1.0

DevicGroupInfo​

设备分组信息。命名空间：rtx::account。

自从 v1.1.0

字段类型说明自从
groupIduint64_t分组 IDv1.1.0
namestd::string分组名称v1.1.0

DeviceGroupList​

设备分组列表响应。命名空间：rtx::account。

自从 v1.1.0

字段类型说明自从
totaluint32_t列表总数v1.1.0
pageNouint32_t当前页码v1.1.0
pageSizeuint32_t分页大小v1.1.0
itemsstd::vector<DevicGroupInfo>当前页分组v1.1.0

GatewaySubDeviceListReq​

网关子设备列表请求。命名空间：rtx::account。

自从 v1.1.0

字段类型必选默认值说明自从
iotTokenstd::string否空使用本 SDK 登录后由 SDK 自动填充v1.1.0
iotIdstd::string是空父网关的设备唯一标识v1.1.0
pageNouint32_t否1页码，从 1 开始v1.1.0
pageSizeuint32_t否100分页大小，1～100v1.1.0
groupIduint64_t否0按分组过滤；0 表示不过滤v1.1.0

GatewaySubDeviceInfo​

网关子设备信息。命名空间：rtx::account。

自从 v1.1.0

字段类型默认值说明自从
iotIdstd::string空子设备唯一标识v1.1.0
productKeystd::string空产品 Keyv1.1.0
deviceNamestd::string空设备名v1.1.0
nickNamestd::string空昵称v1.1.0
statusstd::string空设备状态v1.1.0
ownedstd::string空绑定关系v1.1.0
gmtModifieduint64_t0最后修改时间v1.1.0
regionstd::string空所在机房v1.1.0
sharePermissionListstd::vector<std::string>空分享权限列表v1.1.0
groupIduint64_t0分组 IDv1.1.0

GatewaySubDeviceList​

网关子设备列表响应。命名空间：rtx::account。

自从 v1.1.0

字段类型默认值说明自从
totaluint32_t0列表总数v1.1.0
pageNouint32_t0当前页码v1.1.0
pageSizeuint32_t0分页大小v1.1.0
datastd::vector<GatewaySubDeviceInfo>空当前页子设备v1.1.0

ThingPropertyValue​

单个物模型属性值。命名空间：rtx::account。

自从 v1.1.0

字段类型默认值说明自从
lensIdint32_t-1镜头 ID，< 0 表示不区分镜头v1.1.0
valuestd::string空属性值v1.1.0
timeint64_t0属性更新时间v1.1.0

ThingPropertiesData​

物模型属性集合。命名空间：rtx::account。

自从 v1.1.0

字段类型默认值说明自从
propertyMapstd::map<std::string, std::vector<ThingPropertyValue>>空key 为属性标识符，value 为该属性在各镜头上的取值v1.1.0
maxUpdateTimeValueint64_t0本次数据的最大更新时间，可用于下次差量查询v1.1.0

ThirdPartyDeviceQuery​

第三方设备详情查询项。命名空间：rtx::account。

自从 v1.1.0

字段类型必选默认值说明自从
iotIdstd::string是空设备唯一标识v1.1.0
productKeystd::string是空产品 Keyv1.1.0
deviceNamestd::string是空设备名v1.1.0