SyncFile Function

Format

b = syncfile(direction, from_pathʃ, to_pathʅ);

Description

The syncfile function transfers files between a device and a synchronization service. Files may be of any type: application files, images, text files, etc. However, if transferring CSPro data files, it is more efficient to use the function syncdata. Before calling syncfile, you must first connect to a service by calling syncconnect.

The syncfile function uploads or downloads one or more files from the service. Unlike syncdata, this sends or retrieves an entire file, not individual cases. It is therefore useful for transferring files that are not data files such as images or new versions of application files.

The function can upload files from the local device (client) to the service as well as download files from the service. The direction argument determines which of these operations is performed. It must be one of the following values:

GET: Download files from the service and save them on the client.
PUT: Upload files from the client to the service.

The from_path argument is a string expression that specifies the path of the file to transfer. If the direction is GET then this is the path of the file on the service to download. If the direction is PUT then this is the path to the file name on the client to upload.

The optional to_path argument is a string expression that specifies the destination path for the file. If the direction is GET then this is the path of the destination file name on the client device. If the direction is PUT then this is the path of the destination file or folder on the service. If to_path is not specified, then the file will have the same name as the file in the from_path and will be saved to the application directory on the client (for GET) or the service's root directory (for PUT).

The from_path argument may contain the wildcard characters "*" and "?" to specify a group of files to transfer. In this case, the to_path argument should be the name of a folder to copy all files that match the wildcard pattern into.

When downloading files using GET, syncfile first looks to see if the file already exists on the client device. If it does, and the synchronization service supports this functionality, it only downloads the file if the service has a different version. It uses the file signature (MD5) to determine if the version of the file on the service is different. This reduces the bandwidth used when downloading large files.

Return Value

The function returns a logical value of 1 (true) if the transfer was successful and 0 (false) otherwise.

Example

if syncconnect("https://example.org/csweb/api") then

// upload images in the "photos" directory to the "photos" directory on the server
syncfile(PUT, "photos/*.jpg", "/photos/");

syncdisconnect();

endif;