File upload

1. Establish a connection with the cloud

Call IOT_HTTP2_UploadFile_Connect to establish an HTTP/2 connection. Specify the device certificate information and the server address or port number.

    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;
    }
            

The domain names and ports for each region are as follows. You must replace the asterisk (*) with the ProductKey of your device. For example, if the ProductKey is a1Ign******I, the corresponding URL and port are as follows:

#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          // China (Shanghai)
*.iot-as-http2.us-west-1.aliyuncs.com:443            // US (West)
*.iot-as-http2.us-east-1.aliyuncs.com:443            // US (East)
*.iot-as-http2.eu-central-1.aliyuncs.com:443         // Germany (Frankfurt)
*.iot-as-http2.ap-southeast-1.aliyuncs.com:443       // Singapore
*.iot-as-http2.ap-northeast-1.aliyuncs.com:443       // Japan (Tokyo)
            

2. File upload

Call IOT_HTTP2_UploadFile_Request to request a file upload. The sample program uses the UPLOAD_FILE_OPT_BIT_OVERWRITE mode to upload the file. In this mode, each upload overwrites the file on the cloud. This is an asynchronous operation. You can insert multiple upload requests into the internal queue.

    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];      /* The file name is passed in as a command-line argument. */
    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;
    }
            

The sample program registers two callback functions. One is used to receive the upload result, and the other is used to receive the upload identifier (upload_id) from the cloud. The file upload operation is complete after the SDK calls the upload_file_result callback function. You can then proceed to the next step.

    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. Disconnect

After all files are uploaded, call IOT_HTTP2_UploadFile_Disconnect to disconnect from the cloud.

ret = IOT_HTTP2_UploadFile_Disconnect(handle);
            

Feature API operations

The src/http2/http2_upload_api.h file provides all API operations and related data type definitions for HTTP/2 file upload.

The src/http2/http2_wrapper.h file provides the underlying interfaces required for HTTP/2.

Establish an HTTP/2 connection

Function prototype

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

Description

This function creates an HTTP/2 connection and registers the relevant status callback functions. This is a synchronous operation. If the connection is established, the function returns an HTTP/2 connection handle. Otherwise, it returns NULL.

Parameters

Return values

Additional parameter information

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

• product_key: The ProductKey of the product.
• device_name: The name of the device.
• device_secret: The device's secret key.
• url: The address of the cloud server.
• port: The port of the cloud server.

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

• on_disconnect_cb: The HTTP/2 disconnection callback function.
• on_reconnect_cb: The HTTP/2 reconnection callback function.

File upload request

Function prototype

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

Description

This function uploads a file based on the specified parameter settings and registers the relevant result callback functions. This is an asynchronous operation. The upload result is returned using the callback function.

Parameters

Return values

typedef struct {
    const char *file_path;      /* The file path. The file name must be an ASCII string and its length must be less than 2014 characters. */
    uint32_t part_len;          /* The maximum content length of one HTTP/2 request. The value must be in the range of 100 KB to 100 MB. */
    const char *upload_id;      /* A specific ID that indicates an upload session. This parameter is required only when the UPLOAD_FILE_OPT_BIT_RESUME option is set. */
    uint32_t upload_len;        /* The upload length. This parameter is required only when the UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN option is set. */
    uint32_t opt_bit_map;       /* The option bit map. The supported options are UPLOAD_FILE_OPT_BIT_OVERWRITE, UPLOAD_FILE_OPT_BIT_RESUME, and UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN. */
} http2_upload_params_t;
            

• file_path: The file path.
  Note The file name must be in ASCII encoding and cannot start with a digit.
• part_len: The size of the upload shard. This is the maximum length of content_len in an HTTP/2 request. The value must be in the range of 100 KB to 100 MB. If the value is outside this range, the default length specified in http2_config.h is used.
• upload_id: The upload identifier. This is returned after the first upload. To resume an interrupted upload, you must set the opt_bit_map parameter to UPLOAD_FILE_OPT_BIT_RESUME and specify the corresponding upload identifier.
• upload_len: The length of the current request. This parameter takes effect only when the opt_bit_map parameter is set to UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN.
• opt_bit_map: The bit-defined option table. You can use a bitwise OR operation to configure this option.

  For example, opt_bit_map = UPLOAD_FILE_OPT_BIT_OVERWRITE | UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN indicates that you want to upload a file of a specified length by overwriting the existing file.

#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: Uploads the file by overwriting the existing file. If the file already exists on the cloud and you do not use this option, the file upload fails. If you do not use this option, a new file is created for the upload.
• UPLOAD_FILE_OPT_BIT_RESUME: Resumes an interrupted upload. If you use this option, you must specify the upload_id parameter.
• UPLOAD_FILE_OPT_BIT_SPECIFIC_LEN: Uploads a file of a specified length. If you use this option, you must specify the upload length parameter (upload_len). If you do not use this option, the entire file is uploaded.

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: This callback function is invoked when the upload identifier is received from the cloud server.
• upload_completed_cb: This callback function is invoked when the file upload is complete. The result parameter indicates the upload result.

Disconnect an HTTP/2 connection

API Prototype

int IOT_HTTP2_UploadFile_Disconnect(void *handle);
            

Description

This function disconnects the HTTP/2 connection specified by the handle parameter.

Parameters

Return values

Required HAL functions

The src/http2/http2_wrapper.h file provides some of the Hardware Abstraction Layer (HAL) functions that you must adapt for HTTP/2 file upload.