API 说明

在使用 Azure 编写应用的过程中，使用 IoTHubClient 库就可以轻松发送和接收消息，本章介绍 IoTHubClient 库提供的常用 API。更多详细的 API 请参考 Azure SDK 的 C API 参考。

编程模型选择

IoTHubClient 库提供两套简单易用的 API，一套 API 的名称中包含 “LL”，另外一套则不包含，名称中包含 “LL” 的API 级别较低。无论选择带 “LL” 的 API 还是选择不带 “LL” 的 API，都必须前后相一致。 如果首先调用IoTHubClient_LL_CreateFromConnectionString，则对于任何后续工作，请务必只使用相应的较低级别的 API：

• IoTHubClient_LL_SendEventAsync
• IoTHubClient_LL_SetMessageCallback
• IoTHubClient_LL_Destroy
• IoTHubClient_LL_DoWork

相反的情况也成立。 如果首先调用 IoTHubClient_CreateFromConnectionString，请使用非 LL API 进行任何其他处理。

这些函数的 API 名称中包含“LL”。 除此之外，其中每个函数的参数都与其非 LL 的对等项相同。 但是，这些函数的行为有一个重要的差异。

当你调用 IoTHubClient_CreateFromConnectionString 时，基础库将创建在后台运行的新线程。 此线程将事件发送到 IoT 中心以及从 IoT 中心接收消息。 使用 “LL” API 时则不会创建此类线程。 创建后台线程是为了给开发人员提供方便。 你无需担心如何明确与 IoT 中心相互发送和接收消息，因为此操作会在后台自动进行。 相比之下，借助 “LL”API，可根据需要明确控制与 IoT 中心的通信。

IoTHubClient 常用 API

下面以名称中包含 “LL” 的 API 为例介绍常用 API。

物联网中心客户端初始化

IOTHUB_CLIENT_LL_HANDLE IoTHubClient_LL_CreateFromConnectionString(
                                const char* connectionString,
                                IOTHUB_CLIENT_TRANSPORT_PROVIDER protocol)

使用指定的连接字符串参数创建一个物联网中心客户端来与现有的物联网中心通信。

物联网中心客户端资源释放

void IoTHubDeviceClient_LL_Destroy(IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle)

释放物联网中心客户端分配的资源。这是一个阻塞的调用。

设置发送事件回调函数

IOTHUB_CLIENT_RESULT IoTHubClient_LL_SendEventAsync(
                IOTHUB_CLIENT_LL_HANDLE iotHubClientHandle, 
                IOTHUB_MESSAGE_HANDLE eventMessageHandle, 
                IOTHUB_CLIENT_EVENT_CONFIRMATION_CALLBACK eventConfirmationCallback, 
                void* userContextCallback)

异步调用发送由 eventMessageHandle 指定的消息。

设置接收消息回调函数

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetMessageCallback(
                                IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, 
                                IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC messageCallback, 
                                void* userContextCallback)

当物联网中心向设备发送消息时，设置要调用的消息回调。这是一个阻塞的调用。

设置物理中心客户端

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetOption(
                            IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, 
                            const char* optionName, 
                            const void* value)

这个API设置了一个由参数 optionName 标识的运行时选项，选项名和数据类型值指向每个选项都是特定的。

设置连接状态回调

IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetConnectionStatusCallback(
                            IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, 
                            IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK connectionStatusCallback, 
                            void * userContextCallback)

设置要调用的连接状态回调，表示连接到物联网中心的状态。这是一个阻塞的调用。

完成（发送/接收）工作

void IoTHubDeviceClient_LL_DoWork(IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle)

当工作（发送/接收）可以由 IoTHubClient 完成时，该函数将被用户调用。所有 IoTHubClient 交互（关于网络流量和/或用户级回调）都是调用这个函数的效果，它们在 DoWork 中同步进行。