C SDK

This topic describes how to use the C software development kit (SDK) and its APIs. IoT Edge provides a C SDK named linkedge-thing-access-sdk-c.

/*
     * A callback function to get properties. These properties correspond to the property definitions in the device's Thing Specification Language (TSL) model.
     * The driver developer must implement the business logic for getting properties.
     * 
     * When Link IoT Edge needs to get the properties of a device, the SDK calls this interface to retrieve the data.
     * The SDK then encapsulates the data into a fixed format and sends it back to Link IoT Edge.
     * The developer must find the device based on the device ID and property name, and then fill the retrieved property values in the @device_data_t format.
     *
     * @dev_handle:         The specific device whose properties Link IoT Edge needs to get.
     * @properties:         A key-value structure for property values. The driver developer must update this parameter with the property values retrieved based on the property names.
     * @properties_count:   The number of properties.
     * @usr_data:           The private data passed by the user when the device was registered.
     * Returns LE_SUCCESS if all properties are retrieved successfully. Otherwise, returns an error code. For more information about error codes, see the macro definitions in le_error.h.
     * */
typedef int (*get_properties_callback)(device_handle_t dev_handle, 
                                       leda_device_data_t properties[], 
                                       int properties_count, 
                                       void *usr_data);

/*
     * A callback function to set properties. These properties correspond to the property definitions in the device's TSL model.
     * The driver developer must implement the business logic for setting properties.
     * 
     * When Link IoT Edge needs to set the properties of a device, the SDK calls this interface to pass the specific property values to the application.
     * The developer must set the properties on the device within this callback function.
     *
     * @dev_handle:         The specific device whose properties Link IoT Edge needs to set.
     * @properties:         The names and values of the properties that Link IoT Edge needs to set for the device.
     * @properties_count:   The number of properties.
     * @usr_data:           The private data passed by the user when the device was registered.
     * 
     * Returns LE_SUCCESS if the operation is successful. Otherwise, returns an error code. For more information about error codes, see the macro definitions in le_error.h.
     * */
typedef int (*set_properties_callback)(device_handle_t dev_handle, 
                                       const leda_device_data_t properties[], 
                                       int properties_count, 
                                       void *usr_data);

/*
     * A callback function for service invocations. These invocations correspond to the service definitions in the device's TSL model.
     * The driver developer must implement the corresponding business logic for the service.
     * 
     * When Link IoT Edge needs to invoke a service of a device, the SDK calls this interface to pass the specific service parameters to the application.
     * The developer must invoke the specific service within this callback function and fill the service's return value into output_data in the @device_data_t format. 
     *
     * @dev_handle:   The specific device whose service Link IoT Edge needs to invoke.
     * @service_name: The name of the specific service that Link IoT Edge needs to invoke. The name must be consistent with the device's TSL model.
     * @data:         The parameters for the specific service that Link IoT Edge needs to invoke. The parameters must be consistent with the device's TSL model.
     * @data_count:   The number of parameters for the specific service.
     * @output_data:  The return value of the service invocation. The developer must fill this parameter according to the service format specified in the device's TSL model.
     * @usr_data:     The private data passed by the user when the device was registered.
     * 
     * Returns LE_SUCCESS if the operation is successful. Otherwise, returns an error code. For more information about error codes, see the macro definitions in le_error.h.
     * */
typedef int (*call_service_callback)(device_handle_t dev_handle, 
                                     const char *service_name, 
                                     const leda_device_data_t data[], 
                                     int data_count, 
                                     leda_device_data_t output_data[], 
                                     void *usr_data);

/*
 * Reports properties. The device's capability to report properties is defined in the TSL model of the product to which the device belongs.
 *
 * You can report one or more properties at a time.
 *
 * dev_handle:          The unique identifier of the device in Link IoT Edge.
 * properties:          An array of properties of the @leda_device_data_t type.
 * properties_count:    The number of properties to report in this call.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 *
 */
int leda_report_properties(device_handle_t dev_handle, const leda_device_data_t properties[], int properties_count);

/*
 * Reports an event. The device's capability to report events is defined in the TSL model of the product to which the device belongs.
 *
 * 
 * dev_handle:  The unique identifier of the device in Link IoT Edge.
 * event_name:  The event name.
 * data:        An array of event parameters of the @leda_device_data_t type.
 * data_count:  The length of the event parameter array.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 *
 */
int leda_report_event(device_handle_t dev_handle, const char *event_name, const leda_device_data_t data[], int data_count);

/*
 * Takes a device offline. If a device is not working correctly or before it exits, take it offline.
 * This stops Link IoT Edge from sending messages to the device.
 *
 * dev_handle:  The unique identifier of the device in Link IoT Edge.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 *
 */
int leda_offline(device_handle_t dev_handle);

/*
 * Brings a device online. A device must be online to be recognized by Link IoT Edge.
 *
 * dev_handle:  The unique identifier of the device in Link IoT Edge.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 */
int leda_online(device_handle_t dev_handle);

/*
 * Registers and brings a device online using the DeviceName of a device created in Alibaba Cloud IoT Platform.
 * This requests a unique device identifier.
 *
 * To register multiple devices, call this interface multiple times.
 *
 * product_key: The ProductKey of the product created in Alibaba Cloud IoT Platform.
 * device_name: The DeviceName of the device created in Alibaba Cloud IoT Platform.
 * device_cb:   A struct for the device callback function to be invoked. For a detailed description, see @leda_device_callback.
 * usr_data:    Private data passed during device registration. This data is passed to the device in the callback.
 *
 * This is a blocking interface. The return value is the unique identifier of the device in Link IoT Edge. A value greater than or equal to 0 is valid. A value less than 0 is invalid.
 *
 */
device_handle_t leda_register_and_online_by_device_name(const char *product_key, const char *device_name, leda_device_callback_t *device_cb, void *usr_data);

/*
 * Registers and brings a device online using a custom local device name.
 * This requests a unique device identifier.
 *
 * To register multiple devices, call this interface multiple times.
 *
 * product_key: The ProductKey of the product created in Alibaba Cloud IoT Platform.
 * local_name:  A unique description composed of device feature values. Ensure that each device name is unique for the same ProductKey.
 * device_cb:   A struct for the device callback function to be invoked. For a detailed description, see @leda_device_callback.
 * usr_data:    Private data passed during device registration. This data is passed to the device in the callback.
 *
 * This is a blocking interface. The return value is the unique identifier of the device in Link IoT Edge. A value greater than or equal to 0 is valid. A value less than 0 is invalid.
 *
 * Note: For device registration under the same ProductKey, do not use this interface and the leda_register_and_online_by_device_name interface at the same time. 
 * You must use the same interface for all device registrations for a given ProductKey. Otherwise, unpredictable behavior may occur.
 */
device_handle_t leda_register_and_online_by_local_name(const char *product_key, const char *local_name, leda_device_callback_t *device_cb, void *usr_data);

/*
 * Initializes the driver module. The module creates a worker thread pool to asynchronously execute device operation requests sent from Alibaba Cloud IoT Platform.
 * The number of worker threads is configured by worker_thread_nums.
 *
 * worker_thread_nums: The number of worker threads in the thread pool. Set this value based on the number of registered devices.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 */
int leda_init(int worker_thread_nums);

/*
 * Exits the driver module.
 *
 * Releases resources before the module exits.
 *
 * This is a blocking interface.
 */
void leda_exit(void);

/*
 * Gets the length of the driver information.
 *
 * This is a blocking interface. Returns the length of the driver information on success or 0 on failure.
 */
int leda_get_driver_info_size(void);

/*
 * Gets the driver information, which is the driver configuration set in IoT Platform.
 *
 * driver_info: The driver information. Allocate memory for this parameter in advance and pass it in.
 * size:        The length of the driver information, obtained from leda_get_driver_info_size. If the memory allocated for driver_info is smaller than the actual configuration content, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 * 
 * Configuration format:
    {
        "json":{
            "ip":"127.0.0.1",
            "port":54321
        },
        "kv":[
            {
                "key":"ip",
                "value":"127.0.0.1",
                "note":"IP address"
            },
            {
                "key":"port",
                "value":"54321",
                "note":"port"
            }
        ],
        "fileList":[
            {
                "path":"device_config.json"
            }
        ]
    }
 */
int leda_get_driver_info(char *driver_info, int size);

/*
 * Gets the length of the device information.
 *
 * This is a blocking interface. Returns the length of the device information on success or 0 on failure.
 */
int leda_get_device_info_size(void);

/*
 * Gets the device information, which is the device configuration set in IoT Platform.
 *
 * device_info:  The device information. Allocate memory for this parameter in advance and pass it in.
 * size:         The length of the device information, obtained from the leda_get_device_info_size interface. If the memory allocated for device_info is smaller than the actual configuration content, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 * 
 * Configuration format:
    [
        {
            "custom":{
                "port":12345,
                "ip":"127.0.0.1"
            },
            "deviceName":"device1",
            "productKey":"a1ccxxeypky"
        }
    ]
 */
int leda_get_device_info(char *device_info, int size);

/*
 * Gets the length of the driver configuration.
 *
 * This is a blocking interface. Returns the length of the driver configuration on success or 0 on failure.
 */
int leda_get_config_size(void);

/*
 * Gets all driver configurations.
 *
 * config:       The driver configuration. Allocate memory for this parameter in advance and pass it in.
 * size:         The length of the driver configuration, obtained from the leda_get_config_size interface. If the memory allocated for config is smaller than the actual configuration content, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 * 
 * Configuration format:
    {
        "config":{
            "json":{
                "ip":"127.0.0.1",
                "port":54321
            },
            "kv":[
                {
                    "key":"ip",
                    "value":"127.0.0.1",
                    "note":"IP address"
                },
                {
                    "key":"port",
                    "value":"54321",
                    "note":"port"
                }
            ],
            "fileList":[
                {
                    "path":"device_config.json"
                }
            ]
        },
        "deviceList":[
            {
                "custom":"{"port":12345,"ip":"127.0.0.1"}",
                "deviceName":"device1",
                "productKey":"a1ccxxeypky"
            }
        ]
    }
 */
int leda_get_config(char *config, int size);

/*
 * A callback interface for driver configuration changes.
 *
 * config:       The configuration information.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 */
typedef int (*config_changed_callback)(const char *config);

/*
 * Subscribes to the listener callback for driver configuration changes.
 *
 * config_cb:      The callback interface for configuration change notifications.
 *
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 */
int leda_register_config_changed_callback(config_changed_callback config_cb);

/*
 * Gets the content length of the TSL model for a specified ProductKey.
 *
 * product_key:   The ProductKey of the product.
 *
 * This is a blocking interface. Returns the content length of the TSL model for the specified ProductKey on success or 0 on failure.
 */
int leda_get_tsl_size(const char *product_key);

/*
 * Gets the content of the TSL model for a specified ProductKey.
 *
 * product_key:  The ProductKey of the product.
 * tsl:          The TSL model content. Allocate memory for this parameter in advance and pass it in.
 * size:         The length of the TSL model content, obtained from the leda_get_tsl_size interface. If the memory allocated for tsl is smaller than the actual TSL model content, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 */
int leda_get_tsl(const char *product_key, char *tsl, int size);

/*
 * Gets the content length of the TSL model extension information for a specified ProductKey.
 *
 * product_key:   The ProductKey of the product.
 *
 * This is a blocking interface. Returns the content length of the TSL model extension information for the specified ProductKey on success or 0 on failure.
 */
int leda_get_tsl_ext_info_size(const char *product_key);

/*
 * Gets the content of the TSL model extension information for a specified ProductKey.
 *
 * product_key:  The ProductKey of the product.
 * tsl_ext_info: The TSL model extension information. Allocate memory for this parameter in advance and pass it in.
 * size:         The length of the TSL model extension information, obtained from the leda_get_tsl_ext_info_size interface. If the memory allocated for tsl_ext_info is smaller than the actual TSL model extension information, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * This is a blocking interface. Returns LE_SUCCESS on success or an error code on failure.
 */
int leda_get_tsl_ext_info(const char *product_key, char *tsl_ext_info, int size);

/*
 * Gets a device handle.
 *
 * product_key: The ProductKey of the product.
 * device_name: The DeviceName of the device.
 *
 * This is a blocking interface. Returns a device_handle_t on success or a value less than 0 on failure.
 */
device_handle_t leda_get_device_handle(const char *product_key, const char *device_name);