Sending a File to Device Cloud in C

A client application can send a file from any location on the device to which it has read access and add it to the global file storage or the file storage of a thing in Device Cloud.

The file_name parameter is optional. If you do not specify it, the file name in the Device Cloud storage matches the name of the file you uploaded.

To upload the contents of a directory, specify the name of the directory in the file_path parameter. It is stored in Device Cloud as an archive.

Your application can specify a callback function for the agent to call periodically during the file transfer. The callback can implement progress monitoring and perform any additional processing as needed. When you register the callback function, you can specify user data to pass to the callback function. The data is not sent to Device Cloud or used by the agent.

In the options parameter of the API, you can specify additional, optional information, including the following:

  • whether to send the file to the Device Cloud global file storage or the thing-specific file storage

  • maximum time to wait for the file transfer to complete

You must have initialized your application (see Initializing Your C Application).

To send files, the application must be connected to Device Cloud.

The application must have read access to the specified file and directory on the device.

  1. (Optional) Implement a callback function to check the upload progress.
    1. Use the following function signature. 
      void myFileUploadCallback (const iot_file_progress_t *progress, void* user_data)
    2. In the callback, call the function to monitor the file transfer progress. 
      iot_status_t result, file_upload_result;
iot_float32_t upload_percent = 0.0f;
iot_bool_t complete = IOT_FALSE;

result = iot_file_progress_get(progress, &file_upload_result, &upload_percent, 
                               &complete);

// Process progress results as needed.
  2. (Optional) Specify the file upload options.

    For the lib parameter, specify the value returned from the iot_initialize function, which you called when you registered your application.

    In the following example, the global option specifies that file will be sent to the global file storage in Device Cloud.

    iot_options_t *file_options = iot_options_allocate( agentLib );

iot_options_set(file_options, "global", IOT_TYPE_BOOL, IOT_TRUE); 

  3. Call the file upload API.

    For the lib parameter, specify the value returned from the iot_initialize function, which you called when you registered your application.

    If you do not want to specify any optional information, specify NULL for the options parameter.

    If you implemented a callback function, specify the address of the function for the func parameter. Otherwise, specify NULL.

    For the txn parameter, specify NULL.

    result = iot_file_upload(agentLib, file_options, "deviceCloudFileName", 
                         "/path/to/myLocalFile", 
                         &myFileUploadCallback, NULL);
  4. If applicable, call the iot_options_free function to free the memory allocated for the object.

When the application calls the function, the file appears in Device Cloud in the storage location as specified in the global field of the options parameter. If a file with the same name exists in the storage location, it is overwritten.