HAP - 网络授权保护

Appearance

HAP C++ SDK 文档 ​

概述 ​

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

枚举 ​

UserInfoType ​

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

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

数据结构 ​

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* ip, int port, const ClientVersion& version);

  • 功能

    初始化客户端连接信息。

  • 参数

    • ip: 服务器的 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 将指向已分配的内存，包含所请求的信息内容。在获取成功后，需要用户手动释放此指针：

      • 在用户层调用时，请使用 free() 或 HeapFree() 等效的堆释放函数。
      • 在内核模式下调用时，请使用 ExFreePool() 释放内存。

    • [out]pvResultLength: 输出指针，用于接收信息内容的长度

  • 返回值

    如果函数成功，则返回 true，并通过 pvResult 和 pvResultLength 返回请求的信息和其长度；
    如果函数失败，则返回 false，请检查输入的参数

HAP_GetLastError ​

cpp
HAP_API(uint32_t) HAP_GetLastError();

  • 功能

    返回 SDK 的最后一个错误代码。

  • 参数

    无

  • 返回值

    返回上次操作的错误代码

  • 注解

    此函数可在任何 API 调用失败后使用，以获取详细的错误信息

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_CloudFunction ​

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

  • 功能

    在服务器插件模块中执行云端函数。

  • 参数

    • [in]command

      指令字符串，用于指定要执行的操作

    • [out]pvResult:

      指向接收信息内容的指针。函数执行成功后，pvResult 将指向已分配的内存，包含所请求的信息内容。在获取成功后，需要用户手动释放此指针：

      • 在用户层调用时，请使用 free() 或 HeapFree() 等效的堆释放函数。
      • 在内核模式下调用时，请使用 ExFreePool() 释放内存。

    • [out]pvResultLength: 输出指针，用于接收信息内容的长度

  • 返回值

    无

  • 注解

    服务端未配置插件模块时不会返回有效数据，其它错误可通过 HAP_GetLastError() 获取详细错误信息