API目錄
初始化模塊介紹
初始化接口是Kalay SDK針對(duì)iOS平臺(tái)提供的基礎(chǔ)能力接口集，主要用于SDK的初始化與反初始化、分區(qū)分流配置、局域網(wǎng)設(shè)備搜索、版本信息獲取及日志管理等核心基礎(chǔ)場(chǎng)景，為后續(xù)P2P連接等業(yè)務(wù)功能提供必要的環(huán)境準(zhǔn)備。
KY_InitIOTC
功能描述:用于P2P SDK和Kalay SDK的 IOTC初始化，完成SDK運(yùn)行所需的基礎(chǔ)環(huán)境配置和授權(quán)驗(yàn)證。
接口定義
+ (void)KY_InitIOTCWithLicenseKey:(NSString * _Nonnull)licenseKey
privateKey:(NSString * _Nonnull)privateKey
success:(DictionaryBlock)success
failure:(void (^ _Nonnull)(NSError * _Nullable))failure;
參數(shù)說(shuō)明
| 參數(shù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| privateKey | NSString * | 初始化Kalay SDK所需的授權(quán)碼（什么是授權(quán)碼？） |
| licenseKey | NSString * | 初始化P2P SDK所需的授權(quán)碼（什么是授權(quán)碼？） |
回調(diào)說(shuō)明
| 回調(diào) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| success | DictionaryBlock | 初始化成功的回調(diào)，返回一個(gè)包含相關(guān)信息的字典。 |
| failure | void (^)(NSError *) | 初始化失敗的回調(diào)。NSError中的code返回碼，詳細(xì)定義參考：返回碼 |
返回碼
| 返回碼 | 說(shuō)明 |
|---|---|
| 10001 | privateKey 永久有效 |
| 10002 | privateKey 在有效期內(nèi) |
| -10000 | privateKey 無(wú)效 |
| -10003 | privateKey 已過(guò)期 |
| -1004 | sdk licenseKey 無(wú)效 |
| -1005 | sdk licenseKey 無(wú)效 |
| -3 | sdk licenseKey 重復(fù)初始化 |
| -20031 | sdk licenseKey 重復(fù)初始化 |
| -40032 | sdk licenseKey 重復(fù)初始化 |
代碼示例
[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占用的資源并清理運(yùn)行環(huán)境。
接口定義
+ (void)KY_UninitIOTC;
參數(shù)說(shuō)明
| 參數(shù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| 無(wú) | - | 該接口無(wú)需傳入?yún)?shù) |
回調(diào)說(shuō)明
該接口無(wú)回調(diào)函數(shù)，調(diào)用后直接完成反初始化操作。
返回碼
該接口無(wú)返回值，操作結(jié)果可通過(guò)后續(xù)SDK調(diào)用狀態(tài)判斷。
代碼示例
[KYCamera KY_UninitIOTC];
KY_SetMasterRegion
功能描述:設(shè)置分區(qū)分流方案的地區(qū)，指定P2P服務(wù)掛載的區(qū)域，優(yōu)化設(shè)備連接的網(wǎng)絡(luò)路徑。
接口定義
+ (enum KYError)KY_SetMasterRegion:(TUTKRegion)region;
參數(shù)說(shuō)明
| 參數(shù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| region | TUTKRegion | P2P服務(wù)掛載的區(qū)域。詳細(xì)區(qū)域設(shè)定參考：REGION_ENUM |
REGION_ENUM:
| ENUM | 說(shuō)明 |
|---|---|
| REGION_ALL | 所有區(qū)域 |
| REGION_CN | 中國(guó)大陸地區(qū) |
| REGION_EU | 歐洲地區(qū) |
| REGION_US | 美洲地區(qū) |
| REGION_ASIA | 亞洲地區(qū) |
| REGION_COUNT | 枚舉值數(shù)量，無(wú)實(shí)際意義 |
回調(diào)說(shuō)明
該接口無(wú)回調(diào)函數(shù)，通過(guò)返回值直接返回設(shè)置操作的結(jié)果狀態(tài)碼。
返回碼
| 返回碼 | 說(shuō)明 |
|---|---|
| 0 | 設(shè)置成功 |
| -3 | IOTC模塊 重復(fù)初始化 |
| -46 | 該區(qū)域無(wú)效 |
代碼示例
// 設(shè)置區(qū)域?yàn)橹袊?guó)大陸
enum KYError error = [KYCamera KY_SetMasterRegion:REGION_CN];
if (error == 0) {
NSLog(@"區(qū)域設(shè)置成功");
} else {
NSLog(@"區(qū)域設(shè)置失敗，錯(cuò)誤碼：%d", error);
}
KY_LanSearch
功能描述:搜索本地局域網(wǎng)內(nèi)的Kalay/P2P設(shè)備，獲取設(shè)備的UID、IP、端口等基礎(chǔ)信息。
接口定義
+ (void)KY_LanSearch:(NSInteger)timeout
block:(void (^ _Nonnull)(NSInteger, NSData * _Nullable))block;
設(shè)備信息結(jié)構(gòu)體：
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
};
參數(shù)說(shuō)明
| 參數(shù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| timeout | NSInteger | 超時(shí)時(shí)間，單位：ms |
| block | void (^)(NSInteger, NSData *) | 1. 搜索到的設(shè)備數(shù)量； 2. 包含搜索到的設(shè)備信息結(jié)構(gòu)體數(shù)組的 NSData 對(duì)象，需自行解析。詳細(xì)參考 st_LanSearchInfo。 |
st_LanSearchInfo 結(jié)構(gòu)體說(shuō)明:
| 字段 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| UID | char[21] | 發(fā)現(xiàn)設(shè)備的 UID |
| IP | char[16] | 發(fā)現(xiàn)設(shè)備的 IP 地址 |
| port | uint16_t | 設(shè)備用于 IOTC 會(huì)話連接的端口號(hào) |
| Reserved | char | 保留位，無(wú)實(shí)際用途 |
回調(diào)說(shuō)明
搜索結(jié)果通過(guò)
block 參數(shù)異步返回，包含設(shè)備數(shù)量和設(shè)備信息數(shù)據(jù)，需自行解析結(jié)構(gòu)體獲取具體設(shè)備信息。返回碼
該接口無(wú)直接返回值，搜索結(jié)果通過(guò)block回調(diào)中的設(shè)備數(shù)量參數(shù)判斷（數(shù)量>0表示搜索到設(shè)備，數(shù)量=0表示未搜索到設(shè)備）。
代碼示例
[KYCamera KY_LanSearch:5000 block:^(NSInteger count, NSData * _Nullable data) {
if (count > 0 && data) {
NSLog(@"Found %ld devices.", (long)count);
// 解析 data 中的 st_LanSearchInfo 結(jié)構(gòu)體數(shù)組
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的版本號(hào)信息，用于版本校驗(yàn)和問(wèn)題排查。
接口定義
+ (NSString * _Nullable)KY_GetSDKVersion;
參數(shù)說(shuō)明
| 參數(shù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| 無(wú) | - | 該接口無(wú)需傳入?yún)?shù) |
回調(diào)說(shuō)明
該接口無(wú)回調(diào)函數(shù)，版本號(hào)信息通過(guò)返回值直接返回。
返回碼
返回一個(gè)
NSString 對(duì)象，包含SDK的版本號(hào)（如 "3.3.0"）；如果獲取失敗，返回 nil。代碼示例
NSString *version = [KYCamera KY_GetSDKVersion];
if (version) {
NSLog(@"SDK Version: %@", version);
} else {
NSLog(@"Failed to get SDK version.");
}
KY_setLogEnable
功能描述:設(shè)置SDK日志的記錄開(kāi)關(guān)、日志級(jí)別及存儲(chǔ)路徑，用于調(diào)試和問(wèn)題排查。
接口定義
+ (void) KY_setLogEnable:(BOOL)enable
Level:(logLevel_t)level;
+ (void) KY_setLogEnable:(BOOL)enable
Level:(logLevel_t)level
path:(NSString *)path;
參數(shù)說(shuō)明
| 參數(shù) | 類(lèi)型 | 說(shuō)明 |
|---|---|---|
| enable | BOOL | 是否開(kāi)啟log記錄 |
| path | NSString * | 日志文件存儲(chǔ)的路徑。設(shè)置后，log將按以下結(jié)構(gòu)存儲(chǔ)在沙盒中：<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等級(jí)。詳細(xì)定義參考：LOGLEVEL_ENUM |
LOGLEVEL_ENUM：
| 值 | 枚舉 | 說(shuō)明 |
|---|---|---|
| 0 | LEVEL_VERBOSE | 最詳細(xì)的日志級(jí)別，包含所有信息 |
| 1 | LEVEL_DEBUG | 調(diào)試級(jí)別日志 |
| 2 | LEVEL_INFO | 信息級(jí)別日志 |
| 3 | LEVEL_WARNING | 警告級(jí)別日志 |
| 4 | LEVEL_ERROR | 錯(cuò)誤級(jí)別日志 |
| 5 | LEVEL_SILENCE | 關(guān)閉所有日志 |
回調(diào)說(shuō)明
該接口無(wú)回調(diào)函數(shù)，調(diào)用后直接生效，日志會(huì)按照指定的級(jí)別和路徑進(jìn)行記錄。
返回碼
該接口無(wú)返回值，日志設(shè)置的有效性可通過(guò)查看指定路徑下的日志文件是否生成來(lái)驗(yàn)證。
代碼示例
// 開(kāi)啟日志，級(jí)別為 DEBUG
[KYCamera KY_setLogEnable:YES Level:1];
// 開(kāi)啟日志，級(jí)別為 INFO，并指定存儲(chǔ)路徑
NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *logPath = [documentsPath stringByAppendingPathComponent:@"KalayLogs"];
[KYCamera KY_setLogEnable:YES Level:2 path:logPath];
