API Reference - Azure IoT SDK for C

This section provides detailed documentation for the C API of the Azure IoT SDK. It covers the core components for connecting and interacting with Azure IoT Hub from embedded devices and other C-based applications.

Core Modules

The SDK is structured into several core modules, each responsible for specific functionalities:

1. IoTHubClient

This module provides the primary interface for communicating with Azure IoT Hub. It handles device-to-cloud messages, cloud-to-device commands, and device twin operations.

Key Functions:

• IoTHubClient_CreateFromConnectionString: Creates a client instance from a connection string.
• IoTHubClient_SendDeviceToCloudMessageAsync: Sends telemetry data to IoT Hub.
• IoTHubClient_CreateDeviceTwin: Initiates a device twin operation.
• IoTHubClient_Destroy: Frees resources associated with the client.

Example: Sending a message

#include "azure_iot_hub.h"

// ...

IOTHUB_CLIENT_HANDLE iotHubClientHandle = NULL;
const char* connectionString = "HostName=your_hub.azure-devices.net;DeviceId=your_device;SharedAccessKey=your_key";
const char* messagePayload = "{ \"message\": \"Hello from C SDK!\" }";

if (IoTHubClient_CreateFromConnectionString(connectionString, IoTHubProtocol_MQTT) != NULL)
{
    iotHubClientHandle = IoTHubClient_CreateFromConnectionString(connectionString, IoTHubProtocol_MQTT);
    if (iotHubClientHandle != NULL)
    {
        IOTHUB_MESSAGE_HANDLE messageHandle = IoTHubMessage_CreateFromByteArray((const unsigned char*)messagePayload, strlen(messagePayload));
        if (messageHandle != NULL)
        {
            IoTHubClient_SendDeviceToCloudMessageAsync(iotHubClientHandle, messageHandle, NULL, NULL);
            IoTHubMessage_Destroy(messageHandle);
        }
        IoTHubClient_Destroy(iotHubClientHandle);
    }
}
            

2. IoTHubDeviceClient

A specialized client for devices. This module focuses on device-specific operations and configurations.

Key Functions:

• IoTHubDeviceClient_Create: Creates a device client.
• IoTHubDeviceClient_SetMessageCallback: Registers a callback for incoming cloud-to-device messages.
• IoTHubDeviceClient_GetTwinAsync: Retrieves the current state of the device twin.

3. IoTHubModuleClient

This module is used when the application runs as an IoT Edge module. It provides APIs for module-to-module communication and interaction with the IoT Edge runtime.

Key Functions:

• IoTHubModuleClient_CreateFromEnvironment: Creates a module client by reading environment variables.
• IoTHubModuleClient_SendEventAsync: Sends messages from a module.
• IoTHubModuleClient_RegisterModuleTwinCallback: Registers a callback for module twin updates.

4. IoTHubTransport (MQTT, AMQP, HTTP)

These modules encapsulate the transport layer protocols used for communication with IoT Hub. You typically select the desired protocol during client creation.

Supported Protocols:

• MQTT: The default and recommended protocol for most scenarios.
• AMQP: An alternative messaging protocol.
• HTTP: A fallback protocol for devices with limited network capabilities.

5. Device Twin and Direct Methods

APIs for managing device twins (desired and reported properties) and handling direct method calls from the cloud.

Key Concepts:

• Device Twin: A JSON document representing the state of a device. It has 'desired' and 'reported' properties.
• Direct Methods: Synchronous calls from the cloud to a device to invoke specific actions.

6. Security and Authentication

The SDK supports various security mechanisms for authenticating devices with IoT Hub.

Authentication Methods:

• Symmetric Keys
• X.509 Certificates (Self-Signed and CA-Signed)
• TPM (Trusted Platform Module)

Common Data Structures

Key data structures used throughout the SDK:

IOTHUB_CLIENT_HANDLE

An opaque handle representing an IoT Hub client instance. It must be managed carefully and destroyed when no longer needed.

IOTHUB_MESSAGE_HANDLE

An opaque handle representing a message to be sent to or received from IoT Hub.

IOTHUB_DEVICE_TWIN_HANDLE

An opaque handle for managing device twin operations.

Error Handling

The SDK functions typically return an IOTHUB_CLIENT_RESULT enum value to indicate success or failure. Always check the return values of API calls.