HAP C++ SDK 文档

概述

本 SDK 文档提供了 HAP C++ 库中可用的函数、类型和常量的详细说明。
为每个 API 函数提供了详细的参数和返回值说明，方便用户理解每个参数的含义和使用方法。

枚举

UserInfoType

用于指定要获取的用户信息类型的枚举。

cpp

enum class UserInfoType : uint8_t {
    License,        // 许可证
    Owner,          // 所属管理员
    Note,           // 备注
    ExpireTime,     // 剩余时间(秒数)
    Credits         // 点数
};

ClientVersionInfoType

用于指定要获取的客户端版本信息类型的枚举。

cpp

enum class ClientVersionInfoType : uint8_t
{
    Note_UTF8,      // UTF8 编码备注
    Note_GBK,       // GBK 编码备注
    Note_UTF16_LE,  // UTF16_LE 编码备注
} ClientVersionInfoType;

数据结构

ClientVersion

ClientVersion 结构用于表示客户端软件的版本号，可以通过单个 64 位整数或单独的组件表示。

cpp

union ClientVersion {
    struct {
        uint16_t major;     // 主版本号
        uint16_t minor;     // 次版本号
        uint16_t revision;  // 修订版本号
        uint16_t build;     // 构建版本号
    };
    uint64_t value;         // 版本的64位整数值

    inline ClientVersion() : value(0) {}
    inline ClientVersion(uint64_t value_) : value(value_) {}
    inline ClientVersion(uint16_t major_, uint16_t minor_, uint16_t revision_, uint16_t build_) :
        major(major_), minor(minor_), revision(revision_), build(build_) {}
};

用例：

ClientVersion(1, 0, 0, 0)（C++）
ClientVersion{1, 0, 0, 0}

API 函数

HAP_MakeVersion

cpp

HAP_API(int64_t) HAP_MakeVersion(uint16_t major, uint16_t minor, uint16_t revision, uint16_t build);

功能
根据版本创建一个版本号。
该 API 主要是为了方便 C 用户创建 ClientVersion，C++ 用户可以通过类似 ClientVersion(1, 0, 0, 0) 的形式直接创建 ClientVersion。
参数
- major: 主版本号
- minor: 次版本号
- revision: 修订版本号
- build: 构建版本号
返回值
返回生成的版本号

HAP_Initialize

cpp

HAP_API(bool) HAP_Initialize(const char* host, int port, const ClientVersion& version);

功能
初始化客户端连接信息。
参数
- host: 服务器的 IP 地址或主机名
- port: 服务器端口号
- version: 客户端版本信息
返回值
成功时返回 true，失败时返回 false

HAP_Cleanup

cpp

HAP_API(void) HAP_Cleanup();

功能
清理 SDK 使用的资源。

HAP_Login

cpp

HAP_API(bool) HAP_Login(const char* key);

功能
使用提供的许可证登录服务器。
参数
- key: 用户的许可证
返回值
成功时返回 true，失败时返回 false
错误代码
调用失败时可通过 HAP_GetLastError() 获取详细错误码

HAP_GetUserInfo

cpp

HAP_API(bool) HAP_GetUserInfo(UserInfoType type, void** pvResult, size_t* pvResultLength);

功能
根据指定的类型获取用户信息。
参数
- [in]type
  指定要获取的用户信息类型，使用 UserInfoType 枚举值之一。可选值包括：
  - License: char* 类型许可证
  - Owner: char* 类型所属管理员
  - Note: char* 类型许可证备注
  - ExpireTime: unsigned long long 类型剩余时间(秒数)
  - Credits: unsigned int 类型剩余点数
- [out]pvResult:
  指向接收信息内容的指针。函数执行成功后，pvResult 将指向已分配的内存，包含所请求的信息内容。在获取成功后，需要用户手动释放此指针：
  - 在用户态调用时，请使用 HeapFree(GetProcessHeap(), 0, ptr) 释放结果缓冲区。
  - 在内核模式下调用时，请使用 ExFreePool() 释放内存。
- [out]pvResultLength: 输出指针，用于接收信息内容的长度
返回值
如果函数成功，则返回 true，并通过 pvResult 和 pvResultLength 返回请求的信息和其长度；
如果函数失败，则返回 false，请检查输入的参数

HAP_GetLastError

cpp

HAP_API(uint32_t) HAP_GetLastError();

功能
返回 HAP SDK 记录的最后一个错误码，涵盖验证、协议和客户端错误。错误码含义见错误码表。
参数
无
返回值
返回上次操作的错误代码
注解
SDK 调用失败后，先读取此错误码。排查网络失败时，可同时读取 HAP_GetLastNetworkError 获取系统错误码。

HAP_GetLastNetworkError

cpp

HAP_API(uint32_t) HAP_GetLastNetworkError();

功能
返回最近一次网络失败对应的系统错误码，用于补充 HAP_GetLastError() 提供的 HAP 错误信息。
参数
无
返回值
- Windows 用户态 SDK 返回 WinSock 错误码，通常以十进制记录。
- Windows 内核态 SDK 返回以 uint32_t 表示的 NTSTATUS，通常以十六进制记录。
- 系统错误码不可用时返回 0。即使返回 0，仍应根据原调用的返回值和 HAP 错误码判断失败原因。

注解

在调用失败后立即读取并保存两个错误码，再继续其他 SDK 操作。后续调用可能清除或覆盖已记录的错误。

cpp

if (!HAP_Heartbeat()) {
    const uint32_t hap_error = HAP_GetLastError();
    const uint32_t network_error = HAP_GetLastNetworkError();
    // 记录 hap_error。若 network_error 非零，一并记录。
}

HAP_Heartbeat

cpp

HAP_API(bool) HAP_Heartbeat();

功能
对服务端进行心跳连接，确保授权合法化。
参数
无
返回值
成功时返回 true，失败时返回 false
注解
调用失败时可通过 HAP_GetLastError() 获取详细错误信息

HAP_LoginIntegrity

cpp

HAP_API(bool) HAP_LoginIntegrity();

功能
检查当前登录会话的完整性和合法性。
参数
无
返回值
成功时返回 true，失败时返回 false
注解
登录成功后，可调用此函数检查当前会话。返回 true 表示本次检查通过。返回 false 时，应停止当前业务操作，并按运行环境安全退出。

安全提示

登录成功后，可在对性能要求不高的业务函数中调用 HAP_LoginIntegrity()，检查当前授权的合法性和会话完整性。将检查分散到不同的业务功能中，可让授权验证与业务逻辑结合，增强安全性。

HAP_CloudFunction

cpp

HAP_API(void) HAP_CloudFunction(const char* command, uint8_t** pvResult, size_t* pvResultLength);

功能
在服务器插件模块中执行云端函数。
参数
- [in]command
  指令字符串，用于指定要执行的操作
- [out]pvResult:
  指向接收信息内容的指针。函数执行成功后，pvResult 将指向已分配的内存，包含所请求的信息内容。在获取成功后，需要用户手动释放此指针：
  - 在用户态调用时，请使用 HeapFree(GetProcessHeap(), 0, ptr) 释放结果缓冲区。
  - 在内核模式下调用时，请使用 ExFreePool() 释放内存。
- [out]pvResultLength: 输出指针，用于接收信息内容的长度
返回值
函数返回 void。请同时传入两个有效的输出参数。调用后，结果指针非空且长度大于 0 时，可按返回的字节数读取结果。
注解
服务端未配置插件模块时，调用不会返回有效数据。插件返回空内容、请求失败或客户端分配结果缓冲区失败时，输出也可能是空指针和零长度。
遇到空输出时，立即读取 HAP_GetLastError。如果 SDK 记录了连接、收发或服务端返回的错误，可按错误码排查。若错误码为 0，仍可能是插件返回了空内容，或客户端未能分配结果缓冲区。当前接口没有单独的缓冲区分配失败错误码。

HAP_GetClientVersionInfo

cpp

HAP_API(bool) HAP_GetClientVersionInfo(ClientVersionInfoType type, void** pvResult, size_t* pvResultLength);

功能
获取指定客户端版本号在管理系统中填写的备注信息。
参数
- [in]type
  指定要获取的信息类型，使用 ClientVersionInfoType 枚举值之一。
  - Note_UTF8: char* 类型，UTF8编码
  - Note_GBK: char* 类型，GBK编码
  - Note_UTF16_LE: char* 类型，UTF16_LE编码
- [out]pvResult
  指向接收信息内容的指针。函数执行成功后，pvResult 将指向已分配的内存，包含所请求的信息内容。需要用户手动释放此指针：
  - 在用户态调用时，请使用 HeapFree(GetProcessHeap(), 0, ptr) 释放结果缓冲区。
  - 内核模式下请用 ExFreePool()
- [out]pvResultLength
  输出指针，用于接收信息内容的长度
返回值
成功时返回 true，并通过 pvResult 和 pvResultLength 返回内容。失败时返回 false，请立即调用 HAP_GetLastError 读取 SDK 错误码。排查网络失败时，可同时调用 HAP_GetLastNetworkError 获取系统错误码。
注解
数据实时从服务端获取，可用于客户端获取版本公告、更新提示等信息。该函数允许在未登录时调用

HAP_TerminateProcess

cpp

HAP_API(void) HAP_TerminateProcess(uint32_t exit_code);

功能
主动终止当前进程。用于心跳异常、云函数异常、许可证到期等不安全场景下，确保进程被强制结束，防止被 Hook 或拦截导致无法退出。
参数
- exit_code: 进程退出码
返回值
无
注解
仅支持用户层调用，内核层不可用。推荐在检测到安全风险时调用，确保进程无法被非法手段阻止退出

HAP C++ SDK 文档 ​

概述 ​

枚举 ​

UserInfoType ​

ClientVersionInfoType ​

数据结构 ​

ClientVersion ​

API 函数 ​

HAP_MakeVersion ​

HAP_Initialize ​

HAP_Cleanup ​

HAP_Login ​

HAP_GetUserInfo ​

HAP_GetLastError ​

HAP_GetLastNetworkError ​

HAP_Heartbeat ​

HAP_LoginIntegrity ​

HAP_CloudFunction ​

HAP_GetClientVersionInfo ​

HAP_TerminateProcess ​