本文以C Link SDK中的Demo文件./demos/devinfo_posix_demo.c为例,介绍如何调用Link SDK的API,向物联网平台,上报或删除设备标签。

背景信息

  • 设备标签功能的更多信息,请参见概述

  • 设备标签功能基于MQTT接入,开发过程中涉及MQTT接入的代码说明,请参见MQTT接入

步骤一:初始化

  1. 添加头文件。
    ……
    ……
    
    #include "aiot_devinfo_api.h"
  2. 配置底层依赖和日志输出。
        aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
        aiot_state_set_logcb(demo_state_logcb);
  3. 调用aiot_devinfo_init,创建Devinfo客户端实例,并初始化默认参数。
        devinfo_handle = aiot_devinfo_init();
        if (devinfo_handle == NULL) {
            demo_mqtt_stop(&mqtt_handle);
            printf("aiot_devinfo_init failed\n");
            return -1;
        }

步骤二:配置功能

调用aiot_devinfo_setopt,配置以下功能。

  1. 关联MQTT连接的句柄。
    注意 配置设备标签功能参数前,请确保已配置设备认证信息等相关参数。具体操作,请参见MQTT配置连接参数
    • 示例代码:
          aiot_devinfo_setopt(devinfo_handle, AIOT_DEVINFOOPT_MQTT_HANDLE, mqtt_handle);
    • 相关参数:
      配置项 示例 说明
      AIOT_DEVINFOOPT_MQTT_HANDLE mqtt_handle 设备标签功能的请求基于MQTT连接,通过该配置项,关联MQTT连接句柄。
  2. 配置消息回调
    • 示例代码:
          aiot_devinfo_setopt(devinfo_handle, AIOT_DEVINFOOPT_RECV_HANDLER, (void *)demo_devinfo_recv_handler);
    • 相关参数:
      配置项 示例值 说明
      AIOT_DEVINFOOPT_RECV_HANDLER demo_devinfo_recv_handler 接收到设备标签相关消息时,调用该函数。
  3. 配置状态监控
    1. 定义状态监控回调函数。
      您可以参考以下内容,编写回调函数的处理逻辑:
      • 如果上报标签失败,会返回以下事件类型:
        事件类型 说明
        AIOT_DEVINFOEVT_INVALID_DEVINFO 收到的应答中,设备信息非法,无法获取ProductKeyDeviceName
        AIOT_DEVINFOEVT_INVALID_RESPONSE 收到的应答中字段不合法。
        AIOT_DEVINFOEVT_INVALID_RESPONSE_FORMAT 收到的应答中字段格式错误。
      • 示例代码仅做打印处理,您可根据业务需要编写处理逻辑。
      void demo_devinfo_event_handler(void *handle, const aiot_devinfo_event_t *event, void *userdata)
      {
          switch (event->type) {
              case AIOT_DEVINFOEVT_INVALID_DEVINFO: {
                  printf("AIOT_DEVINFOEVT_INVALID_DEVINFO\n");
              }
              break;
              case AIOT_DEVINFOEVT_INVALID_RESPONSE: {
                  printf("AIOT_DEVINFOEVT_INVALID_RESPONSE\n");
              }
              break;
              case AIOT_DEVINFOEVT_INVALID_RESPONSE_FORMAT: {
                  printf("AIOT_DEVINFOEVT_INVALID_RESPONSE_FORMAT\n");
              }
              break;
              default: {
      
              }
          }
      }
    2. 配置状态监控的回调函数。
      • 示例代码:
            aiot_devinfo_setopt(devinfo_handle, AIOT_DEVINFOOPT_EVENT_HANDLER, (void *)demo_devinfo_event_handler);
      • 相关参数:
        配置项 示例值 说明
        AIOT_DEVINFOOPT_EVENT_HANDLER demo_devinfo_event_handler 当设备连接状态发生变化时,根据该函数的设置,执行对应的处理。

步骤三:更新标签

  1. 调用aiot_devinfo_send,根据上一步配置的参数,向物联网平台发送更新标签的请求。

    发送请求时,需注意:

    • 更新标签消息的数据结构类型为aiot_devinfo_msg_t,是aiot_devinfo_send()的入参。
    • 更新标签消息的类型为AIOT_DEVINFO_MSG_UPDATE
    • 示例消息内容说明:
      上报的消息 对应的Alink格式 说明
      [
          {
              "attrKey": "testKey",
              "attrValue": "testValue"
          }
      ]
      {
        "id": "123",
        "version": "1.0",
        "sys":{
            "ack":0
        },
        "params": [
          {
              "attrKey": "testKey",
              "attrValue": "testValue"
          }
        ],
        "method": "thing.deviceinfo.update"
      }
      更新标签的消息的内容为JSON格式,是Alink格式数据中params的值。详细说明,请参见标签信息上报

      示例代码更新标签的信息为testKey: testValue

        {
            aiot_devinfo_msg_t devinfo_update;
            char *update = "[{\"attrKey\":\"testKey\",\"attrValue\":\"testValue\"}]";
    
            memset(&devinfo_update, 0, sizeof(aiot_devinfo_msg_t));
            devinfo_update.product_key = product_key;
            devinfo_update.device_name = device_name;
            devinfo_update.type = AIOT_DEVINFO_MSG_UPDATE;
            devinfo_update.data.update.params = update;
    
            res = aiot_devinfo_send(devinfo_handle, &devinfo_update);
            if (res < STATE_SUCCESS) {
                aiot_devinfo_deinit(&devinfo_handle);
                demo_mqtt_stop(&mqtt_handle);
                return -1;
            }
            printf("aiot_devinfo_send update msg id: %d\n", res);
        }
  2. 物联网平台接收到请求消息后,更新设备标签,并返回应答报文。
  3. 设备接收应答报文后,触发回调函数demo_devinfo_recv_handler,并执行对应的应答处理。
    您可以参考以下内容,编写回调函数的处理逻辑:
    • 应答报文的数据结构类型为aiot_devinfo_recv_t,是回调函数的入参。
    • 应答报文消息的类型为AIOT_DEVINFORECV_GENERIC_REPLY
    • 示例代码仅做打印处理。
    void demo_devinfo_recv_handler(void *handle, const aiot_devinfo_recv_t *packet, void *userdata)
    {
        switch (packet->type) {
            /* 物联网平台对devinfo消息的应答 */
            case AIOT_DEVINFORECV_GENERIC_REPLY: {
                printf("pk: %s, dn: %s, code: %d, msg id: %d, data: %.*s, message: %.*s\n", packet->product_key, packet->device_name,
                       packet->data.generic_reply.code, packet->data.generic_reply.msg_id, packet->data.generic_reply.data_len,
                       packet->data.generic_reply.data, packet->data.generic_reply.message_len, packet->data.generic_reply.message);
            }
            break;
            default: {
    
            }
        }
    }

(可选)步骤四:删除标签

  1. 设备上报标签后,调用aiot_devinfo_send,向物联网平台发送一条删除标签的请求。

    发送请求时,需注意:

    • 删除标签消息的数据结构类型为aiot_devinfo_msg_t,是aiot_devinfo_send()的入参。
    • 删除标签消息的类型为AIOT_DEVINFO_MSG_DELETE
    • 示例消息内容说明:
      上报的消息 对应的Alink格式 说明
          {
              "attrKey": "testKey"
          }
      {
        "id": "123",
        "version": "1.0",
        "sys":{
            "ack":0
        },
        "params": [
          {
              "attrKey": "testKey",
          }
        ],
        "method": "thing.deviceinfo.update"
      }
      删除标签的消息的内容为JSON格式,是Alink格式数据中params的值。详细说明,请参见删除标签信息

      示例代码删除的标签为testKey

           {
              aiot_devinfo_msg_t devinfo_delete;
              char *delete = "[{\"attrKey\":\"testKey\"}]";
      
              memset(&devinfo_delete, 0, sizeof(aiot_devinfo_msg_t));
              devinfo_delete.product_key = product_key;
              devinfo_delete.device_name = device_name;
              devinfo_delete.type = AIOT_DEVINFO_MSG_DELETE;
              devinfo_delete.data.delete.params = delete;
      
              res = aiot_devinfo_send(devinfo_handle, &devinfo_delete);
              if (res < STATE_SUCCESS) {
                  aiot_devinfo_deinit(&devinfo_handle);
                  demo_mqtt_stop(&mqtt_handle);
                  return -1;
              }
              printf("aiot_devinfo_send delete msg id: %d\n", res);
          } 
  2. 物联网平台接收到请求消息后,删除对应的标签,并返回应答报文。
  3. 设备接收应答报文后,触发回调函数demo_devinfo_recv_handler,并执行对应的应答处理。
    具体操作,请参见处理应答报文

步骤五:退出程序

调用aiot_devinfo_deinit,销毁Devinfo客户端实例,释放资源。

    res = aiot_devinfo_deinit(&devinfo_handle);
    if (res < STATE_SUCCESS) {
        demo_mqtt_stop(&mqtt_handle);
        printf("aiot_devinfo_deinit failed: -0x%04X\n", -res);
        return -1;
    }

后续步骤

  • 例程文件配置完成后,需进行编译,生成可执行文件./demos/devinfo-posix-demo

    更多信息,请参见编译与运行

  • 关于运行结果的详细说明,请参见运行日志