:SDK for C

This topic describes how to use the SDK for C and the related API. Link IoT Edge provides the SDK for C, which is named linkedge-thing-access-sdk-c.

/*
     * The callback function that is used to obtain the device properties that are defined in the device TSL. Driver developers must implement the business logic to obtain the properties.
     * 
     * When Link IoT Edge needs to obtain the properties of a device, the SDK calls this function to obtain the data, parse the data into a fixed format, and then sends it back to Link IoT Edge.
     * Developers must identify the device by using device ID and property names. Then, developers must assign the property values based on the @device_data_t format.
     *
     * @dev_handle: the device from which Link IoT Edge obtains the properties.
     * @properties: the property values. Driver developers must update the value of the properties parameter based on the obtained property values.
     * @properties_count: the number of properties.
     * @usr_data: the private data specified by the user when the device is registered.
     * If all properties are obtained, LE_SUCCESS is returned. If the request fails, an error code is returned. For more information, see the error code macros defined in the le_error.h file.
     * */
typedef int (*get_properties_callback)(device_handle_t dev_handle, 
                                       leda_device_data_t properties[], 
                                       int properties_count, 
                                       void *usr_data);

/*
     * The callback function that is used to set properties that are defined in the TSL. Driver developers must implement the business logic.
     * 
     * When Link IoT Edge needs to set the properties of a device, the SDK calls this function and sends the data to the edge application.
     * Developers must use this function to set device properties.
     *
     * @dev_handle: the device for which Link IoT Edge sets the properties.
     * @properties: the new property values to be set for the device.
     * @properties_count: the number of properties.
     * @usr_data: the private data specified by the user when the device is registered.
     * 
     * If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned. For more information, see the error code macros defined in the le_error.h file.
     * */
typedef int (*set_properties_callback)(device_handle_t dev_handle, 
                                       const leda_device_data_t properties[], 
                                       int properties_count, 
                                       void *usr_data);

/*
     * The callback function that is used to call a service that is based on the service defined in the device TSL. Driver developers must implement the business logic for the service.
     * 
     * When Link IoT Edge needs to call a service of a device, the SDK calls this function to pass specific service parameters to the application.
     * Developers must call the service in the function and assign the return value of the service to the output_data parameter based on the @device_data_t format. 
     *
     * @dev_handle: the specific device from which Link IoT Edge calls the service.
     * @service_name: the name of the service. The service name must be the same as that in the TSL.
     * @data: the parameters of the service. The parameters must be the same as the parameters in the TSL of the device.
     * @data_count: the number of parameters of the service.
     * @output_data: the output data. Developers must set this parameter to the return value of the service based on the format defined in the TSL of the device.
     * @usr_data: the private data specified by the user when the device is registered.
     * 
     * If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned. For more information, see the error code macros defined in the le_error.h file.
     * */
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 property reporting capability is specified in the TSL model of the product to which the device belongs.
 *
 * Reports properties. One or more properties can be reported together.
 *
 * dev_handle: the unique identifier of the device in Link IoT Edge.
 * properties: the @leda_device_data_t property array.
 * properties_count: the number of properties.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 *
 */
int leda_report_properties(device_handle_t dev_handle, const leda_device_data_t properties[], int properties_count);

/*
 * Reports device events defined in the device TSL.
 *
 * 
 * dev_handle: the unique identifier of the device in Link IoT Edge.
 * event_name: the event name.
 * data: the event parameter array @leda_device_data_t.
 * data_count: the length of the event parameter array.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 *
 */
int leda_report_event(device_handle_t dev_handle, const char *event_name, const leda_device_data_t data[], int data_count);

/*
 * Disconnects a device. If a device is malfunctioning or before you shut down a device, you may want to disconnect the device. you can first disconnect the device. After the device is disconnected, Link IoT Edge will not continue to route messages to the device.
 *
 * dev_handle: the unique identifier of the device in Link IoT Edge.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 *
 */
int leda_offline(device_handle_t dev_handle);

/*
 * Connects the device to IoT Platform. The device can be recognized by Link IoT Edge only after the device is connected to IoT Platform.
 *
 * dev_handle: the unique identifier of the device in Link IoT Edge.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 */
int leda_online(device_handle_t dev_handle);

/*
 * Uses the device_name that has been created in the Alibaba Cloud IoT Platform to register, activate, and generate a unique identifier for the device.
 *
 * If you want to register multiple devices, you can call this function multiple times.
 *
 * product_key: the ProductKey of the product created in Alibaba Cloud IoT Platform.
 * device_name: the device name (DeviceName) that is created in the Alibaba Cloud IoT Platform.
 * device_cb: the device callback struct. For more information, see @leda_device_callback.
 * @usr_data: the private data specified by the user when the device is registered. The data is sent to the device during the callback.
 *
 * A blocking function. The unique identifier of the device in Link IoT Edge is returned. A value of 0 indicates that the device is valid and a value that is less than 0 indicates that it 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);

/*
 * Uses an on-premises custom device_name to register, activate, and generate a unique identifier for the device.
 *
 * If you want to register multiple devices, you can call this function multiple times.
 *
 * product_key: the ProductKey of the product created in Alibaba Cloud IoT Platform.
 * local_name: the name of the device. The names of products under the same product must be unique.
 * device_cb: the device callback struct. For more information, see @leda_device_callback.
 * @usr_data: the private data specified by the user when the device is registered. The data is sent to the device during the callback.
 *
 * A blocking function. The unique identifier of the device in Link IoT Edge is returned. A value of 0 indicates that the device is valid and a value that is less than 0 indicates that it is invalid.
 *
 * Note: You cannot use this function and the eda_register_and_online_by_device_name function at the same time. 
 * All devices of the same ProductKey must use the same function for device registration. Otherwise, the registration may result in errors.
 */
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. During the initialization, a worker thread pool is created in the module to asynchronously process device operation requests from IoT Platform. You can set the number of worker threads by specifying the worker_thread_nums parameter.
 *
 * worker_thread_nums: the number of threads in the thread pool. This value is set based on the number of registered devices.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 */
int leda_init(int worker_thread_nums);

/*
 * Terminates the driver module.
 *
 * Before the module exits, the resources are released.
 *
 * A blocking function.
 */
void leda_exit(void);

/*
 * Obtains the length of the driver information.
 *
 * A blocking function. If the length of the driver information is obtained, LE_SUCCESS is returned. If the request fails, 0 is returned.
 */
int leda_get_driver_info_size(void);

/*
 * Obtains the information of the driver that is configured on IoT Platform.
 *
 * driver_info: the driver information. You must allocate the memory in advance.
 * size: the driver information length. If the size of the driver_info is larger than the size parameter, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 * 
 * The 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 number"
            }
        ],
        "fileList":[
            {
                "path":"device_config.json"
            }
        ]
    }
 */
int leda_get_driver_info(char *driver_info, int size);

/*
 * Obtains the length of the device information.
 *
 * A blocking function. If the length of the device information is obtained, LE_SUCCESS is returned. If the request fails, 0 is returned.
 */
int leda_get_device_info_size(void);

/*
 * Obtains the information of the device that is configured on IoT Platform.
 *
 * driver_info: the device information. You must allocate the memory in advance.
 * size: the device information length. You can obtain the length by calling the leda_get_device_info_size method. If the size of the device_info is larger than the size parameter, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 * 
 * The configuration format:
    [
        {
            "custom":{
                "port":12345,
                "ip":"127.0.0.1"
            },
            "deviceName":"device1",
            "productKey":"a1ccxxeypky"
        }
    ]
 */
int leda_get_device_info(char *device_info, int size);

/*
 * Obtains the length of the driver configuration information.
 *
 * A blocking function. If the length of the driver configuration is obtained, LE_SUCCESS is returned. If the request fails, 0 is returned.
 */
int leda_get_config_size(void);

/*
 * Obtains all driver configurations.
 *
 * config: the driver configuration. You must allocate the memory in advance.
 * size: the device information length. You can obtain the length by calling the leda_get_config_size method. If the size of the device_info is larger than the size parameter, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 * 
 * The 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 number"
                }
            ],
            "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);

/*
 * The callback method that is used to modify driver configurations.
 *
 * config: the configuration information.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 */
typedef int (*config_changed_callback)(const char *config);

/*
 * Configure the subscription-driven configuration change listener for callbacks.
 *
 * config_cb: the callback function that is used to notify configuration changes.
 *
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 */
int leda_register_config_changed_callback(config_changed_callback config_cb);

/*
 * Obtains the length of the TSL based on the ProductKey.
 *
 * product_key: the ProductKey of the product.
 *
 * A blocking function. If the length of the TSL is obtained, LE_SUCCESS is returned. If the request fails, 0 is returned.
 */
int leda_get_tsl_size(const char *product_key);

/*
 * Obtains the TSL information of a product based on the ProductKey.
 *
 * product_key: the ProductKey of the product.
 * tsl: the content of the TSL model. You need to apply for memory resources in advance to upload the data.
 * size: the TSL content size. You can obtain the size by calling the leda_get_tsl_size method. If the size of the tsl parameter is larger than the size parameter, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 */
int leda_get_tsl(const char *product_key, char *tsl, int size);

/*
 * Obtains the extended TSL information length of a product based on the ProductKey.
 *
 * product_key: the ProductKey of the product.
 *
 * A blocking function. If the request is successful, the length of the extended TSL information is returned. If the request fails, 0 is returned.
 */
int leda_get_tsl_ext_info_size(const char *product_key);

/*
 * Obtains the extended TSL information of a product based on the ProductKey.
 *
 * product_key: the ProductKey of the product.
 * tsl_ext_info: the extended TSL information. You need to request memory information in advance.
 * size: the length of the extended TSL information. You can obtain the length by calling the leda_get_tsl_ext_info_size method. If the size of the device_info is larger than the size parameter, LE_ERROR_INVAILD_PARAM is returned.
 *  
 * A blocking function. If the request is successful, LE_SUCCESS is returned. If the request fails, an error code is returned.
 */
int leda_get_tsl_ext_info(const char *product_key, char *tsl_ext_info, int size);

/*
 * Obtains the device handle.
 *
 * product_key: the ProductKey of the product.
 * device_name: the device name (DeviceName).
 *
 * A blocking function. If the request is successful, a device handle is returned. If the request fails, a number that is less than 0 is returned.
 */
device_handle_t leda_get_device_handle(const char *product_key, const char *device_name);