Retrieving a File from Device Cloud in C

A client application can retrieve a file from the global file storage or the file storage of a thing in Device Cloud and store it in any device location to which it has write access.

The file_name parameter is optional. If you do not specify it, the file name on the device matches the name of the file you downloaded from the Device Cloud storage.

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 retrieve the file from the Device Cloud global file storage or the thing-specific file storage
maximum time to wait for the file transfer to complete

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

The application must have write access to the specified directory.

The file must exist in the Device Cloud file storage from which you want to retrieve it.

(Optional) Implement a callback function to run to check the download progress.

Use the following function signature.

void myFileDownloadCallback (const iot_file_progress_t *progress, void* user_data)

In the callback, call the function to monitor the file transfer progress.

iot_status_t result, file_download_result;
iot_float32_t download_percent = 0.0f;
iot_bool_t complete = IOT_FALSE;

result = iot_file_progress_get(progress, &file_download_result, 
                               &download_percent, 
                               &complete);

// Process progress results as needed.

(Optional) Specify the file download 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 retrieved from 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); 
```
Call the file download API.
For the lib parameter, specify the value returned from the iot_initialize function, which you called when you registered your application.

For the txn parameter, specify NULL.

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.
```
result = iot_file_download(agentLib, NULL, file_options, "deviceCloudFileName",
                           "/path/to/myDirectory", &myFileDownloadCallback, NULL);
```
If applicable, call the iot_options_free function to free the memory allocated for the object.

When the application calls the function, the file is retrieved from the storage location in Device Cloud as specified in the flags field of the options parameter and stored in the specified directory on the device. If the file already exists, it is overwritten.