Azure云平台软件包用户手册的API说明

在使用 Azure 编写应用的过程中，使用 IoTHubClient 库就可以轻松发送和接收消息，本章介绍 IoTHubClient 库提供的常用 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)

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

参数	描述
connectionString	设备连接字符串
protocol	协议实现的函数指针
返回	描述
IOTHUB_CLIENT_LL_HANDLE	一个非空的 iothubclientllhandle 值，它在调用物联网中心客户端的其他函数时使用
NULL	失败

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

void

IoTHubDeviceClient_LL_Destroy(

IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle)

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

参数	描述
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 指定的消息。

参数	描述
iotHubClientHandle	已创建的物联网中心客户端句柄
eventMessageHandle	物联网中心消息句柄
eventConfirmation Callback	由设备指定的回调，用于接收物联网中心消息的交付确认。这个回调可以被同一消息调用：当 iothubclientllsendeventasync 函数，试图重试发送一条失败的消息。用户可以在这里指定一个NULL值，以表明不需要回调
userContextCallback	用户指定的上下文将被提供给回调，可以为空
返回	描述
IOTHUB_CLIENT_OK	设置成功
error code	失败

设置接收消息回调函数

IOTHUB_CLIENT_RESULT

IoTHubDeviceClient_LL_SetMessageCallback(

IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle,

IOTHUB_CLIENT_MESSAGE_CALLBACK_ASYNC messageCallback,

void* userContextCallback)

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

参数	描述
iotHubClientHandle	已创建的物联网中心客户端句柄
messageCallback	由设备指定的回调，用于接收来自物联网中心的消息
userContextCallback	用户指定的上下文将被提供给回调，可以为空
返回	描述
IOTHUB_CLIENT_RESULT	初始化 IoT 客户端成功
NULL	失败

设置物理中心客户端

IOTHUB_CLIENT_RESULT

IoTHubDeviceClient_LL_SetOption

IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle,

const char optionName, const void value)

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

参数	描述
iotHubClientHandle	已创建的物联网中心客户端句柄
optionName	选项名称
value	特定值
返回	描述
IOTHUB_CLIENT_OK	设置成功
error code	失败

设置连接状态回调

IOTHUB_CLIENT_RESULT

IoTHubDeviceClient_LL_SetConnectionStatusCallback(

IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle,

IOTHUB_CLIENT_CONNECTION_STATUS_CALLBACK connectionStatusCallback,

void * userContextCallback)

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

参数	描述
iotHubClientHandle	已创建的物联网中心客户端句柄
connectionStatusCallback	设备指定的回调，用于接收关于连接到物联网中心的状态的更新
userContextCallback	用户指定的上下文将被提供给回调，可以为空
返回	描述
IOTHUB_CLIENT_OK	设置成功
error code	失败