本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 中心 SDK 客户端
<a name="hub-sdk-client"></a>

Hub SDK 客户端库充当托管集成 Hub SDK 和在同一集线器上运行的您自己的协议堆栈之间的接口。它公开了一组公共 API，以方便您的协议栈与 Device Hub SDK 组件的交互。用例包括自定义插件控件、自定义插件供应器和本地控制器。

**Topics**
+ [获取您的托管集成 Hub SDK](#custom-protocol-plugin-getting-started)
+ [关于 Hub SDK 工具包](#custom-protocol-plugin-toolkit)
+ [使用 Hub SDK 客户端创建您的自定义应用程序](#custom-protocol-plugin-create-app)
+ [运行您的自定义应用程序](#custom-protocol-plugin-running-application)
+ [Hub 软件开发工具包客户端 API](hub-sdk-client-api-reference.md)
+ [数据类型](#custom-protocol-plugin-data-types)

## 获取您的托管集成 Hub SDK
<a name="custom-protocol-plugin-getting-started"></a>

Hub SDK 客户端附带托管集成 SDK。请通过[托管集成控制台](https://console.aws.amazon.com/iot/home#/managed-integrations/intro)联系我们，访问 Hub SDK。

## 关于 Hub SDK 工具包
<a name="custom-protocol-plugin-toolkit"></a>

下载后，您将看到一个`IotMI-DeviceSDK-Toolkit`文件夹，其中包含所有公共头`.so`文件和可以在应用程序中使用的文件。托管集成团队还提供了一个`main.cpp`用于演示目的的示例，以及您可以直接执行的演示应用程序二进制文件。`bin/`您可以选择将其用作应用程序的起点。

## 使用 Hub SDK 客户端创建您的自定义应用程序
<a name="custom-protocol-plugin-create-app"></a>

使用以下步骤创建您的自定义应用程序。

1. 在应用程序中包含头文件 (.h) 和共享目标文件 (.so)。

   您必须在应用程序中包含公共头文件 (.h) 和共享目标文件 (.so)。对于.so 文件，您可以将它们放在 lib 文件夹中。最终布局将如下所示：

   ```
   ├── include
   │   ├── iotmi_device_sdk_client
   │   │   └── iotmi_device_sdk_client_common_types.h
   │   ├── iotmi_device_sdk_client.h
   │   └── iotshd_status.h
   ├── lib
   │   ├── libiotmi_devicesdk_client_module.so
   │   └── libiotmi_log_c.so
   ```

1. 在主应用程序中创建 Hub SDK 客户端。

   1. 在主应用程序中，必须先初始化 Hub SDK 客户端，然后才能使用它来处理请求。你可以简单地使用来构造客户端`clientId`。

   1. 拥有客户端后，您可以将其连接到托管集成设备 SDK。

      以下是创建 Hub SDK 客户端以及如何连接的示例。

      ```
      #include <cstdlib>
      #include <string>
      #include "iotshd_status.h"
      #include "iotmi_device_sdk_client.h"
      
      auto client = std::make_unique<DeviceSDKClient>({{your_own_clientId}});
      iotmi_statusCode_t status = client->connect();
      ```
**注意**  
{{your\_own\_clientId}}必须与您在用户指导设置的[启动设备发现中指定的相同，或者在简单](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html)设置配置流程中为[创建管理](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html)的事物指定的相同。

1. 通过执行以下步骤进行发布和订阅。

   1. 建立连接后，您现在可以从托管集成 Hub SDK 订阅传入的任务。传入的任务可以是控制任务或预配任务。您还需要根据收到的任务定义自己的回调函数，并定义自己的自定义上下文以用于自己的跟踪目的。

      ```
            // subscribe to provisioning tasks
            iotmi_statusCode_t status = client->iotmi_provision_subscribe_to_tasks(
            example_subscriber_callback, custom_context);
            
            // subscribe to control tasks
            iotmi_statusCode_t status = client->iotmi_control_subscribe_to_tasks(
            example_subscriber_callback, custom_context);
      ```

   1. 建立连接后，您现在可以将来自应用程序的请求发布到托管集成 Hub SDK。您可以定义自己的任务消息类型，为不同的业务目的使用不同的负载。这些请求可以包括控制请求和配置请求，类似于订阅流程。最后，你可以为你分配一个地址，让你`rspPayload`以同步的方式从托管集成 Hub SDK 获得响应。

      ```
      // publish control request
        iotmi_client_request_t api_payload = {
                  .messageType = C2MIMessageType::C2MI_CONTROL_EVENT,
                  .reqPayload = (uint8_t *)"{{define_your_req_payload}}",
                  .rspPayload = (uint8_t *)calloc(1000, sizeof(uint8_t))
        };
      
        status = client->iotmi_control_publish_request(&api_payload); 
        
        // publish provision request 
        iotmi_client_request_t api_payload = {
                  .messageType = C2MIMessageType::C2MI_DEVICE_ONBOARDED,
                  .reqPayload = (uint8_t *)"{{define_your_req_payload}}",
                  .rspPayload = (uint8_t *)calloc(1000, sizeof(uint8_t))
        };
        status = client->iotmi_provision_publish_request(&api_payload);
      ```

1. 自己构建`CMakeLists.txt`，然后从那里构建应用程序。最终输出可能是可执行的二进制文件，例如 `MyFirstApplication`

## 运行您的自定义应用程序
<a name="custom-protocol-plugin-running-application"></a>

在运行自定义应用程序之前，请完成以下步骤来设置中心并启动托管集成 Hub SDK：
+ 请按照中的入职说明进行操作。[将您的集线器加入托管集成](managedintegrations-sdk-v2-cookbook-usinghub.md)
+ 完成中记录的安装过程[安装和验证托管集成中心 SDK](managedintegrations-sdk-v2-cookbook-deployment.md)。

满足先决条件后，您就可以运行您的自定义应用程序了。例如：

```
./MyFirstApplication
```

**重要**  
必须[使用脚本部署 Hub SDK](managedintegrations-sdk-v2-cookbook-deployment-nogg.md)使用脚本手动更新中列出的启动脚本才能启动自己的应用程序。顺序很重要，不要更改顺序。  
更新以下内容。更改  

```
./IotMI-DeviceSDK-Toolkit/bin/DeviceSDKClientDemo >> $LOGS_DIR/logDeviceSDKClientDemo_logs.txt &
```
修改为  

```
./MyFirstApplication >> $LOGS_DIR/MyFirstApplication_logs.txtt &
```

## 数据类型
<a name="custom-protocol-plugin-data-types"></a>

本节定义了用于自定义协议插件的数据类型。

**iotmi\_client\_request\_t**  
表示要发布到托管集成组件的请求。    
**消息类型**  
消息的类型 (CommonTypes::C2MIMessageType)。以下列表显示了有效值。  
+ `C2MI_DEVICE_ONBOARDED`: 表示带有相关负载的设备启动消息。
+ `C2MI_DE_PROVISIONING_PRE_ASSOCIATED_COMPLETE`：表示预关联设备的取消配置任务完成通知。
+ `C2MI_DE_PROVISIONING_ACTIVATED_COMPLETE`：表示已激活设备的取消配置任务完成通知。
+ `C2MI_DE_PROVISIONING_COMPLETE_RESPONSE`：表示取消置备任务已完成响应。
+ `C2MI_CONTROL_EVENT`：表示可能发生设备状态变化的控制事件。
+ `C2MI_CONTROL_SEND_COMMAND`: 表示来自本地控制器的控制命令。
+ `C2MI_CONTROL_SEND_DEVICE_STATE_QUERY`: 表示来自本地控制器的控制设备状态查询。  
**reqPayl**  
请求有效负载，通常是一个 JSON-formatted 字符串。  
**RSPPayloa**  
由托管集成组件填充的响应有效负载。

**iotmi\_client\_event\_t**  
表示从托管集成组件收到的事件。    
**事件\_id**  
事件的唯一标识符。  
**length**  
事件数据的长度。  
**data**  
指向事件数据的指针，包括`messageType`。以下列表显示了可能的值。  
+ `C2MI_PROVISION_UGS_TASK`：表示 UGS 流程的配置任务。
+ `C2MI_PROVISION_SS_TASK`：表示 SimpleSetup 流程的置备任务。
+ `C2MI_DE_PROVISION_PRE_ASSOCIATED_TASK`：表示预关联设备的取消配置任务。
+ `C2MI_DE_PROVISION_ACTIVATED_TASK`：表示已激活设备的取消配置任务。
+ `C2MI_DEVICE_ONBOARDED_RESPONSE`: 表示设备加载响应。
+ `C2MI_CONTROL_TASK`：表示控制任务。
+ `C2MI_CONTROL_EVENT_NOTIFICATION`: 表示本地控制器的控制事件通知。  
**ctx**  
与事件关联的自定义上下文。