API目录
初始化模块介绍
初始化接口是Kalay SDK针对iOS平台提供的基础能力接口集，主要用于SDK的初始化与反初始化、分区分流配置、局域网设备搜索、版本信息获取及日志管理等核心基础场景，为后续P2P连接等业务功能提供必要的环境准备。
KY_InitIOTC
功能描述:用于P2P SDK和Kalay SDK的 IOTC初始化，完成SDK运行所需的基础环境配置和授权验证。
接口定义
+ (void)KY_InitIOTCWithLicenseKey:(NSString * _Nonnull)licenseKey
privateKey:(NSString * _Nonnull)privateKey
success:(DictionaryBlock)success
failure:(void (^ _Nonnull)(NSError * _Nullable))failure;
参数说明
回调说明
| 回调 | 类型 | 说明 |
|---|---|---|
| success | DictionaryBlock | 初始化成功的回调，返回一个包含相关信息的字典。 |
| failure | void (^)(NSError *) | 初始化失败的回调。NSError中的code返回码，详细定义参考：返回码 |
返回码
| 返回码 | 说明 |
|---|---|
| 10001 | privateKey 永久有效 |
| 10002 | privateKey 在有效期内 |
| -10000 | privateKey 无效 |
| -10003 | privateKey 已过期 |
| -1004 | sdk licenseKey 无效 |
| -1005 | sdk licenseKey 无效 |
| -3 | sdk licenseKey 重复初始化 |
| -20031 | sdk licenseKey 重复初始化 |
| -40032 | sdk licenseKey 重复初始化 |
代码示例
[Camera KY_InitIOTCWithLicenseKey:LICENSEKEY
privateKey:PRIVATEKEY
success:^(NSDictionary * _Nonnull dic) {
NSLog(@"KY_InitIOTC:success ip: %@ msg: %@", [dic objectForKey:@"ip"], [dic objectForKey:@"msg"]);
}
failure:^(NSError *error) {
if (error.code == KYPrivateKeyErrorNoValid) {
NSLog(@"KY_InitIOTC:false(KYPrivateKeyErrorNoValid) ip: %@ msg: %@ ", [error.userInfo objectForKey:@"ip"], error.userInfo.description);
}
else if (error.code == KYPrivateKeyErrorExpire) {
NSLog(@"KY_InitIOTC:false(KYPrivateKeyErrorExpire) ip: %@ msg: %@ ",[error.userInfo objectForKey:@"ip"], error.userInfo.description);
}
else {
NSLog(@"KY_InitIOTC:false() ip: %@ msg: %@ ", [error.userInfo objectForKey:@"ip"], error.userInfo.description);
}
}];
KY_UninitIOTC
功能描述:用于P2P SDK和Kalay SDK的 IOTC反初始化，释放SDK占用的资源并清理运行环境。
接口定义
+ (void)KY_UninitIOTC;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| 无 | - | 该接口无需传入参数 |
回调说明
该接口无回调函数，调用后直接完成反初始化操作。
返回码
该接口无返回值，操作结果可通过后续SDK调用状态判断。
代码示例
[KYCamera KY_UninitIOTC];
KY_SetMasterRegion
功能描述:设置分区分流方案的地区，指定P2P服务挂载的区域，优化设备连接的网络路径。
接口定义
+ (enum KYError)KY_SetMasterRegion:(TUTKRegion)region;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| region | TUTKRegion | P2P服务挂载的区域。详细区域设定参考：REGION_ENUM |
REGION_ENUM:
| ENUM | 说明 |
|---|---|
| REGION_ALL | 所有区域 |
| REGION_CN | 中国大陆地区 |
| REGION_EU | 欧洲地区 |
| REGION_US | 美洲地区 |
| REGION_ASIA | 亚洲地区 |
| REGION_COUNT | 枚举值数量，无实际意义 |
回调说明
该接口无回调函数，通过返回值直接返回设置操作的结果状态码。
返回码
| 返回码 | 说明 |
|---|---|
| 0 | 设置成功 |
| -3 | IOTC模块 重复初始化 |
| -46 | 该区域无效 |
代码示例
// 设置区域为中国大陆
enum KYError error = [KYCamera KY_SetMasterRegion:REGION_CN];
if (error == 0) {
NSLog(@"区域设置成功");
} else {
NSLog(@"区域设置失败，错误码：%d", error);
}
KY_LanSearch
功能描述:搜索本地局域网内的Kalay/P2P设备，获取设备的UID、IP、端口等基础信息。
接口定义
+ (void)KY_LanSearch:(NSInteger)timeout
block:(void (^ _Nonnull)(NSInteger, NSData * _Nullable))block;
设备信息结构体：
struct st_LanSearchInfo
{
char UID[21]; //!< The UID of discovered device
char IP[16]; //!< The IP address of discovered device
uint16_t port; //!< The port number of discovered device used for IOTC session connection
char Reserved; //!< Reserved, no use
};
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| timeout | NSInteger | 超时时间，单位：ms |
| block | void (^)(NSInteger, NSData *) | 1. 搜索到的设备数量； 2. 包含搜索到的设备信息结构体数组的 NSData 对象，需自行解析。详细参考 st_LanSearchInfo。 |
st_LanSearchInfo 结构体说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| UID | char[21] | 发现设备的 UID |
| IP | char[16] | 发现设备的 IP 地址 |
| port | uint16_t | 设备用于 IOTC 会话连接的端口号 |
| Reserved | char | 保留位，无实际用途 |
回调说明
搜索结果通过
block 参数异步返回，包含设备数量和设备信息数据，需自行解析结构体获取具体设备信息。返回码
该接口无直接返回值，搜索结果通过block回调中的设备数量参数判断（数量>0表示搜索到设备，数量=0表示未搜索到设备）。
代码示例
[KYCamera KY_LanSearch:5000 block:^(NSInteger count, NSData * _Nullable data) {
if (count > 0 && data) {
NSLog(@"Found %ld devices.", (long)count);
// 解析 data 中的 st_LanSearchInfo 结构体数组
const struct st_LanSearchInfo *devices = (const struct st_LanSearchInfo *)data.bytes;
for (NSInteger i = 0; i < count; i++) {
NSString *uid = [NSString stringWithCString:devices[i].UID encoding:NSUTF8StringEncoding];
NSString *ip = [NSString stringWithCString:devices[i].IP encoding:NSUTF8StringEncoding];
uint16_t port = devices[i].port;
NSLog(@"Device %ld: UID=%@, IP=%@, Port=%d", (long)i, uid, ip, port);
}
} else {
NSLog(@"No devices found or search failed.");
}
}];
KY_GetSDKVersion
功能描述:获取Kalay/P2P SDK的版本号信息，用于版本校验和问题排查。
接口定义
+ (NSString * _Nullable)KY_GetSDKVersion;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| 无 | - | 该接口无需传入参数 |
回调说明
该接口无回调函数，版本号信息通过返回值直接返回。
返回码
返回一个
NSString 对象，包含SDK的版本号（如 "3.3.0"）；如果获取失败，返回 nil。代码示例
NSString *version = [KYCamera KY_GetSDKVersion];
if (version) {
NSLog(@"SDK Version: %@", version);
} else {
NSLog(@"Failed to get SDK version.");
}
KY_setLogEnable
功能描述:设置SDK日志的记录开关、日志级别及存储路径，用于调试和问题排查。
接口定义
+ (void) KY_setLogEnable:(BOOL)enable
Level:(logLevel_t)level;
+ (void) KY_setLogEnable:(BOOL)enable
Level:(logLevel_t)level
path:(NSString *)path;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | BOOL | 是否开启log记录 |
| path | NSString * | 日志文件存储的路径。设置后，log将按以下结构存储在沙盒中：<path>/yyyy-MM-dd/HH:mm:ss/Console.txt<path>/yyyy-MM-dd/HH:mm:ss/IOTC.txt<path>/yyyy-MM-dd/HH:mm:ss/AVAPI.txt<path>/yyyy-MM-dd/HH:mm:ss/RDT.txt<path>/yyyy-MM-dd/HH:mm:ss/Global.txt |
| level | logLevel_t | log等级。详细定义参考：LOGLEVEL_ENUM |
LOGLEVEL_ENUM：
| 值 | 枚举 | 说明 |
|---|---|---|
| 0 | LEVEL_VERBOSE | 最详细的日志级别，包含所有信息 |
| 1 | LEVEL_DEBUG | 调试级别日志 |
| 2 | LEVEL_INFO | 信息级别日志 |
| 3 | LEVEL_WARNING | 警告级别日志 |
| 4 | LEVEL_ERROR | 错误级别日志 |
| 5 | LEVEL_SILENCE | 关闭所有日志 |
回调说明
该接口无回调函数，调用后直接生效，日志会按照指定的级别和路径进行记录。
返回码
该接口无返回值，日志设置的有效性可通过查看指定路径下的日志文件是否生成来验证。
代码示例
// 开启日志，级别为 DEBUG
[KYCamera KY_setLogEnable:YES Level:1];
// 开启日志，级别为 INFO，并指定存储路径
NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *logPath = [documentsPath stringByAppendingPathComponent:@"KalayLogs"];
[KYCamera KY_setLogEnable:YES Level:2 path:logPath];
