本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Hub SDK 用戶端
<a name="hub-sdk-client"></a>

Hub SDK 用戶端程式庫可做為受管整合 Hub SDK 與您在相同中樞上執行的自有通訊協定堆疊之間的界面。它會公開一組公有 APIs，以促進通訊協定堆疊與 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 SDK 用戶端 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)聯絡我們以存取中樞 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}} 必須與您在使用者引導設定中 [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) 中指定的相同，或在簡單設定佈建流程中用於 [create-managed-thing](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. 建立連線後，您現在可以從應用程式將請求發佈至受管整合中樞 SDK。您可以定義自己的任務訊息類型，針對不同的業務用途使用不同的承載。請求可以同時包含控制請求和佈建請求，類似於訂閱流程。最後，您可以為 指派地址`rspPayload`，以同步方式從受管整合中樞開發套件取得回應。

      ```
      // 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>

執行自訂應用程式之前，請完成下列步驟來設定中樞，並啟動受管整合中樞 SDK：
+ 遵循 的加入指示[將您的中樞加入受管整合](managedintegrations-sdk-v2-cookbook-usinghub.md)。
+ 完成 中記錄的安裝程序[安裝和驗證受管整合 Hub 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**  
代表要發佈至受管整合元件的請求。    
**messageType**  
訊息的類型 (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`：表示來自本機控制器的控制裝置狀態查詢。  
**reqPayload**  
請求承載，通常是 JSON 格式的字串。  
**rspPayload**  
由受管整合元件填入的回應承載。

**iotmi\_client\_event\_t**  
代表從受管整合元件接收的事件。    
**event\_id**  
事件的唯一識別符。  
**長度**  
事件資料的長度。  
**資料**  
事件資料的指標，包括 `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**  
與事件相關聯的自訂內容。