文件上传

1. 与云端建立连接

调用IOT_HTTP2_UploadFile_Connect建立HTTP2连接，指定设备的证书信息和服务器地址或端口号。

    http2_upload_conn_info_t conn_info;
    void *handle;

    memset(&conn_info, 0, sizeof(http2_upload_conn_info_t));
    conn_info.product_key = HTTP2_PRODUCT_KEY;
    conn_info.device_name = HTTP2_DEVICE_NAME;
    conn_info.device_secret = HTTP2_DEVICE_SECRET;
    conn_info.url = HTTP2_ONLINE_SERVER_URL;
    conn_info.port = HTTP2_ONLINE_SERVER_PORT;

    handle = IOT_HTTP2_UploadFile_Connect(&conn_info, NULL);

    if(handle == NULL) {
        return -1;
    }
            

目前各个区域对应的域名和端口如下，其中*符号应使用设备的ProductKey替换，如ProductKey为a1Ign******I时对应的URL、PORT如下：

#define HTTP2_ONLINE_SERVER_URL             "a1I******vI.iot-as-http2.cn-shanghai.aliyuncs.com"
#define HTTP2_ONLINE_SERVER_PORT            443
            

*.iot-as-http2.cn-shanghai.aliyuncs.com:443          // 上海正式
*.iot-as-http2.us-west-1.aliyuncs.com:443            // 美西正式
*.iot-as-http2.us-east-1.aliyuncs.com:443            // 美东正式
*.iot-as-http2.eu-central-1.aliyuncs.com:443         // 德国正式
*.iot-as-http2.ap-southeast-1.aliyuncs.com:443       // 新加坡正式
*.iot-as-http2.ap-northeast-1.aliyuncs.com:443       // 日本正式
            

2. 文件上传

使用IOT_HTTP2_UploadFile_Request请求文件上传，示例程序以UPLOAD_FILE_OPT_BIT_OVERWRITE的方式上传，每次上传都会覆盖云端文件。此接口为异步接口，可以插入多个上传请求到内部队列中。

    http2_upload_params_t fs_params;
    http2_upload_result_cb_t result_cb;

    memset(&result_cb, 0, sizeof(http2_upload_result_cb_t));
    result_cb.upload_completed_cb = upload_file_result;
    result_cb.upload_id_received_cb = upload_id_received_handle;

    memset(&fs_params, 0, sizeof(fs_params));
    fs_params.file_path = argv[1];      /* 文件名称以命令行参数传入 */
    fs_params.opt_bit_map = UPLOAD_FILE_OPT_BIT_OVERWRITE;

    ret = IOT_HTTP2_UploadFile_Request(handle, &fs_params, &result_cb, NULL);
    if(ret < 0) {
        return -1;
    }
            

示例程序中注册了2个回调函数，分别用于接收上传结果，和接收云端返回的上传标示符（upload_id），在SDK调用了upload_file_result后，文件上传操作结束，可进行下一步操作。

    void upload_file_result(const char *file_path, int result, void *user_data)
    {
        upload_end++;
        EXAMPLE_TRACE("=========== file_path = %s, result = %d, finish num = %d ===========", file_path, result, upload_end);
    }

    void upload_id_received_handle(const char *file_path, const char *upload_id, void *user_data)
    {
        EXAMPLE_TRACE("=========== file_path = %s, upload_id = %s ===========", file_path, upload_id);

        if (upload_id != NULL) {
            memcpy(g_upload_id, upload_id, strlen(upload_id));
        }
    }
            

3. 断开连接

所有文件上传结束后使用IOT_HTTP2_UploadFile_Disconnect断开云端连接。

ret = IOT_HTTP2_UploadFile_Disconnect(handle);
            

功能API接口

src/http2/http2_upload_api.h列出了HTTP2文件上传的所有API和相关数据类型定义。

src/http2/http2_wrapper.h列出了HTTP2所需的底层接口

HTTP2建立连接

接口原型

void *IOT_HTTP2_UploadFile_Connect(http2_upload_conn_info_t *conn_info, http2_status_cb_t *cb);
            

接口说明

创建HTTP2连接，并注册相关状态回调函数，此接口为同步接口，当建连成功后会返回HTTP2连接句柄，否则返回NULL。

参数说明

返回值说明

参数附加说明

typedef struct {
    char  *product_key;
    char  *device_name;
    char  *device_secret;
    char  *url;
    int   port;
} http2_upload_conn_info_t;
            

• product_key：产品标示符。
• device_name：设备名称。
• device_secret：识别密钥。
• url：云端服务器地址。
• port：云端服务器端口。

typedef struct {
    http2_disconnect_cb_t   on_disconnect_cb;
    http2_reconnect_cb_t    on_reconnect_cb;
} http2_status_cb_t;
            

• on_disconnect_cb：HTTP2断连回调函数。
• on_reconnect_cb：HTTP2重连回调函数。

文件上传请求

接口原型

int IOT_HTTP2_UploadFile_Request(void *http2_handle, http2_upload_params_t *params, http2_upload_result_cb_t *cb, void *user_data);
            

接口说明

按照指定参数配置上传文件，并注册相关结果回调函数，此接口为异步接口，上传结果由回调函数返回。

参数说明

返回值说明

typedef struct {
    const char *file_path;      /* file path, filename must be ASCII string and strlen < 2014 */
    uint32_t part_len;          /* maximum content len of one http2 request, must be in range of 100KB ~ 100MB */
    const char *upload_id;      /* a specific id used to indicate one upload session, only required when UPLOAD_FILE_OPT_BIT_RESUME option set */
    uint32_t upload_len;        /* used to indicate the upload length, only required when UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN option set */
    uint32_t opt_bit_map;       /* option bit map, support UPLOAD_FILE_OPT_BIT_OVERWRITE, UPLOAD_FILE_OPT_BIT_RESUME and UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN */
} http2_upload_params_t;
            

• file_path：文件路径。
  说明 文件名必须为ASCII编码，且不能使用数字开头。
• part_len：文件上传分片大小，即HTTP2请求content_len的最大长度, 必须在100KB ~ 100MB范围内, 否则会使用http2_config.h中的默认长度。
• upload_id：上传标示符，首次上传时返回。在需要使用断点续传方式上传时需添加opt_bit_map参数UPLOAD_FILE_OPT_BIT_RESUME, 并指定对应上传标示符。
• upload_len：指定本次请求的长度，仅在opt_bit_map参数中有配置UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN时才能起作用。
• opt_bit_map：位定义的选项表，可以使用按位或的方式配置此选项。

  如opt_bit_map = UPLOAD_FILE_OPT_BIT_OVERWRITE | UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN表示使用覆盖方式上传指定的文件长度。

#define UPLOAD_FILE_OPT_BIT_OVERWRITE       (0x00000001)
#define UPLOAD_FILE_OPT_BIT_RESUME          (0x00000002)
#define UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN    (0x00000004)
            

• UPLOAD_FILE_OPT_BIT_OVERWRITE：使用覆盖的方式上传文件。如果云端文件已存在，而未使用覆盖方式，则文件上传会失败。未使用此选项，将使用创建文件的方式上传文件。
• UPLOAD_FILE_OPT_BIT_RESUME：使用断点续传的方式上传文件。使用此选项需填写上传标示符参数upload_id。
• UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN：使用指定长度的方式上传。使用此选项需要填写上传长度参数（upload_len），否则将上传整个文件。

typedef struct {
    http2_upload_id_received_cb_t   upload_id_received_cb;
    http2_upload_completed_cb_t     upload_completed_cb;
} http2_upload_result_cb_t;
            

• upload_id_received_cb：接收到云端服务器返回的上传标示符时，将调用此回调函数。
• upload_completed_cb：文件上传结束时，将调用此回调函数，result参数指示了上传结果。

HTTP2断开连接

接口原型

int IOT_HTTP2_UploadFile_Disconnect(void *handle);
            

接口说明

断开参数handle指定的HTTP2连接。

参数说明

返回值说明

需要对接的HAL接口

文件src/http2/http2_wrapper.h中包含了对接HTTP2文件上传需要适配的部分HAL接口。