接口说明
更新时间：2026-07-30 15:13:04
接口集合，包括：用户登录、登出，设备列表，直播等功能。开发可先阅读用户账号开发指南
接口集
#pragma once
#include <stdint.h>
#include <functional>
#include <string>
#include <memory>
#include <vector>
#include "AccountDevice.h"
namespace rtx
{
namespace pcsdk
{
// 错误码
enum RtcxPcCode {
RTCX_PC_SUCCESS = 0,
RTCX_PC_FAIL = -1
};
// 初始化参数
struct InitParam
{
std::string cfgFileName = "config.ini"; // 配置文件名
std::string appKey;
std::string appSecret;
};
// 拉流失败原因
enum class PlayFailReason : int32_t
{
SIGNAL_ERROR = 0, // 信令请求失败（设备/网关返回非成功状态），errCode 为信令返回的业务错误码
SIGNAL_TIMEOUT = 1, // 信令请求超时（20 秒内未收到设备响应），errCode 无实际意义
PLAYER_ERROR = 2 // 播放器/流媒体内部错误，errCode 为播放器错误码
};
struct PlayTimelineStep
{
std::string label;
int64_t elapsedMs = 0;
int64_t stepMs = 0;
};
struct PlayTimelineInfo
{
std::string playMode;
std::string streamType;
std::vector<PlayTimelineStep> steps;
bool valid = false;
};
struct LanDiscoveredDevice
{
std::string ip;
int32_t sigPort = 9821;
std::string protocol = "TCP";
std::string productKey;
std::string deviceName;
bool isGateway = false;
std::string iotId() const { return productKey + deviceName; }
};
struct LanDiscoverParam
{
std::string targetIp; // 空=广播；非空=单播指定 IPv4
};
// 事件回调接口
class IRtcxPcEvtHandler
{
public:
typedef std::shared_ptr<IRtcxPcEvtHandler> Ptr;
IRtcxPcEvtHandler() {}
virtual ~IRtcxPcEvtHandler() {}
// 拉流开始加载（信令交互完成，播放器开始建立连接）
virtual void OnPlayLoading(const std::string &deviceName) {}
// 拉流成功，已开始播放
virtual void OnPlayStarted(const std::string &deviceName) {}
// 拉流失败且即将自动重连（attempt 从 1 开始，maxAttempts 一般为 3）
virtual void OnPlayRetrying(const std::string &deviceName, int32_t attempt, int32_t maxAttempts) {}
// 拉流失败（重试耗尽或不可重试错误）
virtual void OnPlayError(const std::string &deviceName, PlayFailReason reason, int32_t errCode) {}
// 截图完成（errCode 为 PLAYERCODE_SUCCESS 表示成功）
virtual void OnSnapshotTaken(const std::string &deviceName, int32_t errCode, const std::string &filePath) {}
// 局域网发现：每发现一台新设备
virtual void OnLanDeviceDiscovered(const LanDiscoveredDevice &device) {}
// 局域网发现：搜索结束（可能为空列表）
virtual void OnLanDiscoverFinished(const std::vector<LanDiscoveredDevice> &devices) {}
};
// 接口
class IRtcxPcApi
{
public:
typedef std::shared_ptr<IRtcxPcApi> Ptr;
IRtcxPcApi() {}
virtual ~IRtcxPcApi() {}
// 初始化
static int32_t Initialize(const InitParam ¶m);
// 反初始化
static int32_t Uninitialize();
// 获取版本号
static int32_t GetVersion(std::string &version);
// 创建PC API智能指针
static IRtcxPcApi::Ptr CreateRtcxPcApi(const std::shared_ptr<IRtcxPcEvtHandler> handler);
// 登入；失败时可通过 errorMessage 获取接口返回的错误描述
virtual int32_t Login(const std::string &userName, const std::string &password, std::string *errorMessage = nullptr) = 0;
virtual int32_t LoginLan() = 0;
virtual void SetLanDeviceEndpoint(const std::string &iotId, const std::string &ip, int32_t sigPort,
const std::string &protocol, const std::string &productKey,
const std::string &deviceName) = 0;
virtual bool IsLanMode() const = 0;
// 局域网设备发现；targetIp 为空广播，非空单播指定 IPv4
virtual int32_t StartLanDiscover(const LanDiscoverParam ¶m = {}) = 0;
virtual void StopLanDiscover() = 0;
virtual bool IsLanDiscovering() const = 0;
// 登出
virtual int32_t Logout() = 0;
// 获取设备列表
virtual std::shared_ptr<rtx::account::DeviceList> GetDeviceList(const rtx::account::DeviceListReq &deviceListReq) = 0;
// 获取网关子设备列表
virtual std::shared_ptr<rtx::account::GatewaySubDeviceList> GetGatewaySubDeviceList(const rtx::account::GatewaySubDeviceListReq &req) = 0;
// 获取设备分组列表
virtual std::shared_ptr<rtx::account::DeviceGroupList> GetDeviceGroupList(const rtx::account::DeviceGroupListReq &deviceGroupListReq) = 0;
// 开始播放；子设备拉流可传父网关 iotId 作为 dstUserId，普通设备保持默认
virtual void StartPlay(const std::string &deviceName, const std::string &productKey, void *hWnd, const std::string &dstUserId = "") = 0;
// 结束播放
virtual void StopPlay() = 0;
// 截图（异步）；filePath 为本地保存路径；结果通过 OnSnapshotTaken 回调
virtual int32_t Snapshot(const std::string &filePath, bool withWatermark = false) = 0;
// 获取当前播放 Timeline（出图前 valid=false）
virtual PlayTimelineInfo GetPlayTimeline() const = 0;
// 获取当前码流类型描述
virtual std::string GetPlayStreamType() const = 0;
};
}
}
SDK 初始化与反初始化
InitParam param;
param.cfgFileName = "config.ini";
param.appKey = "aaaaaaaa";
param.appSecret = "bbbbbbbbbbbbbbb";
IRtcxPcApi::Initialize(param);
std::string version;
IRtcxPcApi::GetVersion(version);
IRtcxPcApi::Uninitialize();
用户登录与登出
InitParam param;
param.appKey = "aaaaaaaa";
param.appSecret = "bbbbbbbbbbbbbbb";
IRtcxPcApi::Initialize(param);
std::shared_ptr<TestPcEvtHandler> handler = std::make_shared<TestPcEvtHandler>();
IRtcxPcApi::Ptr pcapi = IRtcxPcApi::CreateRtcxPcApi(handler);
// 用户登录
pcapi->Login("xxxx", "yyyyy");
// ....
// 用户登出
pcapi->Logout();
获取设备列表
// 获取设备列表，默认只获取第一页，所有列表需要自行遍历获取
rtx::account::DeviceListReq req;
std::shared_ptr<rtx::account::DeviceList> resp = pcapi->GetDeviceList(req);
if (resp && resp->total > 0)
{
std::cout << "total:" << resp->total << ", pageNo:" << resp->pageNo << ", pageSize:" << resp->pageSize << std::endl;
for (size_t i = 0; i < resp->data.size(); i++)
{
const rtx::account::DeviceInfo &deviceInfo = resp->data[i];
iotIdDeviceMap[deviceInfo.iotId] = deviceInfo;
std::cout << deviceInfo.toJsonString() << std::endl;
}
}
// 请求参数结构
struct DeviceListReq
{
/**
* 该参数仅调用客户端API时生效，主要用于确认请求发起者的系统参数，使用生活物联网平台提供的账号SDK时该值会自动生成。
*/
std::string iotToken;
/**
* 当前页码，从1开始。
*/
uint32_t pageNo = 1;
/**
* 分页大小，大于等于1，小于等于100。
*/
uint32_t pageSize = 100;
/**
* 绑定类型。取值为：0（表示被分享的设备）；1（表示拥有的设备）；null（表示所有的设备）。
*/
OwnedType owned = OwnedType::ALL;
/**
* 分组id，可按照分组id过滤列表
*/
uint64_t groupId = 0;
/**
* 是否为子设备，true（表示获取子设备列表），false（表示获取直连设备列表）
*/
bool isSubDevice = false;
};
// 响应参数结构
enum class OwnedType : uint32_t
{
/**
* 分享者
*/
SHARED = 0,
/**
* 拥有者
*/
OWNED = 1
};
enum class DeviceStatus : uint32_t
{
/**
* 未激活
*/
INACTIVE = 0,
/**
* 在线
*/
ONLINE = 1,
/**
* 休眠
*/
SLEEP = 2,
/**
* 离线
*/
OFFLINE = 3,
/**
* 禁用
*/
DISABLE = 8
};
enum class NodeType : uint32_t
{
/**
* 普通节点
*/
DEVICE = 0,
/**
* 网关节点
*/
GATEWAY = 1,
UNKNOWN = 10000
};
enum class NetType : uint32_t
{
/**
* 表示LoRa
*/
NET_LORA = 0,
/**
* 表示2G/3G/4G/5G蜂窝网
*/
NET_CELLULAR = 1,
/**
* 表示Wi-Fi
*/
NET_WIFI = 2,
/**
* 表示ZigBee
*/
NET_ZIGBEE = 3,
/**
* 表示以太网
*/
NET_ETHERNET = 4,
/**
* 表示其他网络类型
*/
NET_OTHER = 5,
/**
* 未知
*/
NET_UNKNOWN = 10000
};
struct DeviceInfo
{
/**
* 用户的身份ID。
*/
uint64_t identityId;
/**
* 平台为设备颁发的ID，设备的唯一标识符。
*/
std::string iotId;
std::string deviceName;
std::string productKey;
std::string productName;
/**
* 设备所属产品的型号。
*/
std::string productModel;
/**
* 设备的昵称
*/
std::string nickName;
/**
* 产品下设备的联网方式，可取值： NET_LORA（表示LoRa）；NET_CELLULAR（表示2G/3G/4G/5G蜂窝网）；NET_WIFI（表示Wi-Fi）；NET_ZIGBEE（表示ZigBee）；NET_ETHERNET（表示以太网）；NET_OTHER（表示其他网络类型）。
*/
NetType netType = NetType::NET_UNKNOWN;
/**
* DEVICE:普通设备
*/
std::string thingType;
/**
* 设备状态。0（表示未激活）；1（表示在线）；3（表示离线）；8（表示禁用）。
*/
DeviceStatus status = DeviceStatus::OFFLINE;
/**
* 设备和用户的关系，可取值：0（表示分享者），1（表示拥有者）。
*/
OwnedType owned = OwnedType::ALL;
/**
* 设备的节点类型，可取值包括：DEVICE，GATEWAY。
*/
NodeType nodeType = NodeType::DEVICE;
/**
* gmtModified
*/
uint64_t gmtModified;
/**
* 设备当前所在的机房
*/
std::string region;
/**
* 只有owned=0有值，分享权限列表，live：直播，control：设备控制，record：录像回看，ptz：云台控制，voiceIntercom：语音对讲，setting：高级设置，notification：消息通知
*/
std::vector<std::string> sharePermissionList;
/**
* 分组id
*/
uint64_t groupId = 0;
};
struct DeviceList
{
/**
* 列表总数
*/
uint32_t total;
/**
* 当前页码
*/
uint32_t pageNo;
/**
* 分页大小
*/
uint32_t pageSize;
/**
* 设备列表详细信息
*/
std::vector<DeviceInfo> data;
};
获取设备分组列表
std::map<uint64_t, std::string> groupMap;
bool bHasMore = false;
int pageNo = 1;
do {
DeviceGroupListReq deviceGroupListReq;
deviceGroupListReq.pageNo = pageNo;
deviceGroupListReq.pageSize = 100;
std::shared_ptr<DeviceGroupList> deviceGroupList = pcapi->GetDeviceGroupList(deviceGroupListReq);
if (deviceGroupList && deviceGroupList->total > 0) {
bHasMore = deviceGroupList->total > deviceGroupList->pageNo * deviceGroupList->pageSize;
}
pageNo++;
for (size_t i = 0; i < deviceGroupList->items.size(); i++)
{
DevicGroupInfo& groupInfo = deviceGroupList->items[i];
groupMap[groupInfo.groupId] = groupInfo.name;
}
} while (bHasMore);
// 请求参数结构
struct DeviceGroupListReq
{
/**
* 该参数仅调用客户端API时生效，主要用于确认请求发起者的系统参数，使用生活物联网平台提供的账号SDK时该值会自动填充。
*/
std::string iotToken;
/**
* 当前页码，从1开始。
*/
uint32_t pageNo = 1;
/**
* 分页大小，大于等于1，小于等于100。
*/
uint32_t pageSize = 100;
};
// 响应参数结构
struct DevicGroupInfo
{
/**
* 分组id
*/
uint64_t groupId;
/**
* 设备组的名称
*/
std::string name;
};
struct DeviceGroupList
{
/**
* 列表总数
*/
uint32_t total;
/**
* 当前页码
*/
uint32_t pageNo;
/**
* 分页大小
*/
uint32_t pageSize;
/**
* 设备分组列表详细信息
*/
std::vector<DevicGroupInfo> items;
};
局域网模式
InitParam param;
param.appKey = "aaaaaaaa";
param.appSecret = "bbbbbbbbbbbbbbb";
IRtcxPcApi::Initialize(param);
std::shared_ptr<TestPcEvtHandler> handler = std::make_shared<TestPcEvtHandler>();
IRtcxPcApi::Ptr pcapi = IRtcxPcApi::CreateRtcxPcApi(handler);
pcapi->LoginLan();
// 广播搜索
LanDiscoverParam discoverParam;
discoverParam.targetIp = "";
pcapi->StartLanDiscover(discoverParam);
// 指定 IP 单播搜索
LanDiscoverParam unicastParam;
unicastParam.targetIp = "192.168.1.100";
pcapi->StartLanDiscover(unicastParam);
pcapi->StopLanDiscover();
bool searching = pcapi->IsLanDiscovering();
bool lanMode = pcapi->IsLanMode();
pcapi->SetLanDeviceEndpoint(iotId, "192.168.1.100", 9821, "TCP", productKey, deviceName);
pcapi->Logout();
struct LanDiscoveredDevice
{
std::string ip;
int32_t sigPort = 9821;
std::string protocol = "TCP";
std::string productKey;
std::string deviceName;
bool isGateway = false;
std::string iotId() const { return productKey + deviceName; }
};
struct LanDiscoverParam
{
std::string targetIp;
};
事件回调
class TestPcEvtHandler : public IRtcxPcEvtHandler
{
public:
void OnPlayLoading(const std::string &deviceName) override {}
void OnPlayStarted(const std::string &deviceName) override {}
void OnPlayRetrying(const std::string &deviceName, int32_t attempt, int32_t maxAttempts) override {}
void OnPlayError(const std::string &deviceName, PlayFailReason reason, int32_t errCode) override {}
void OnSnapshotTaken(const std::string &deviceName, int32_t errCode, const std::string &filePath) override {}
void OnLanDeviceDiscovered(const LanDiscoveredDevice &device) override {}
void OnLanDiscoverFinished(const std::vector<LanDiscoveredDevice> &devices) override {}
};
enum class PlayFailReason : int32_t
{
SIGNAL_ERROR = 0,
SIGNAL_TIMEOUT = 1,
PLAYER_ERROR = 2
};
开始播放和停止播放
// 开始播放
pcapi->StartPlay(deviceInfo.deviceName, deviceInfo.productKey, renderHwnd);
// 网关子设备拉流，dstUserId 传父网关 iotId
pcapi->StartPlay(subDevice.deviceName, subDevice.productKey, renderHwnd, gatewayIotId);
// 停止播放
pcapi->StopPlay();
截图
#include "CorePlayerDef.h"
int32_t ret = pcapi->Snapshot("D:/capture/snap.jpg", false);
enum PlayerErrorCode_en
{
PLAYERCODE_SUCCESS = 0,
PLAYERCODE_STREAM_ERR,
PLAYERCODE_SNAPSHOT_ERR,
PLAYERCODE_SNAPSHOT_MEMORY_LEAK,
};
获取网关子设备列表
rtx::account::GatewaySubDeviceListReq req;
req.iotId = gatewayDeviceInfo.iotId;
req.pageNo = 1;
req.pageSize = 100;
std::shared_ptr<rtx::account::GatewaySubDeviceList> resp = pcapi->GetGatewaySubDeviceList(req);
if (resp && resp->total > 0)
{
for (const auto &sub : resp->data)
{
std::cout << sub.deviceName << ", " << sub.productKey << std::endl;
}
}
// 请求参数结构
struct GatewaySubDeviceListReq
{
std::string iotToken;
std::string iotId;
uint32_t pageNo = 1;
uint32_t pageSize = 100;
uint64_t groupId = 0;
};
struct GatewaySubDeviceInfo
{
std::string iotId;
std::string productKey;
std::string deviceName;
std::string nickName;
std::string status;
std::string owned;
uint64_t gmtModified = 0;
std::string region;
std::vector<std::string> sharePermissionList;
uint64_t groupId = 0;
};
struct GatewaySubDeviceList
{
uint32_t total = 0;
uint32_t pageNo = 0;
uint32_t pageSize = 0;
std::vector<GatewaySubDeviceInfo> data;
};