Downloads a file from a MobiLink server with the MobiLink interface.

Syntax

ul_bool MLFileTransfer ( ml_file_transfer_info * info );                                  

Parameters

info   A structure containing the file transfer information.

ML File Transfer parameters

The ML File Transfer parameters are members of a structure that is passed as a parameter to the MLFileTransfer function. The ml_file_transfer_info structure is defined in a header file named mlfiletransfer.h. The individual fields of the structure are specified as follows:

filename   Required. The file name to be transferred from the server running MobiLink. MobiLink searches the username subdirectory first, before defaulting to the root directory. See -ftr option.

If the file cannot be found, an error is set in the error field. The file name must not include any drive or path information, or MobiLink cannot find it.

dest_path   The local path to store the downloaded file. If this parameter is empty (the default), the downloaded file is stored in the current directory.

dest_filename   The local name for the downloaded file. If this parameter is empty, the value in file name is used.

stream   Required. The protocol can be one of: TCPIP, TLS, HTTP, or HTTPS. See Stream Type synchronization parameter.

stream_parms   The protocol options for a given stream. See Network protocol options for UltraLite synchronization streams.

username   Required. MobiLink user name.

password   The password for the MobiLink user name.

version   Required. The MobiLink script version.

observer   A callback can be provided to observe file download progress through the 'observer' field. For more details, see description of Callback Function that follows.

user_data   The application-specific information made available to the synchronization observer. See User Data synchronization parameter.

force_download   Set to true to download the file even if the timestamp indicates it is already present. Set to false to downloaded only if the server version and the local version are different. In this case, the server version of the file overwrites the client version. Any previous file of the same name on the client is discarded before the file is downloaded. MLFileTransfer compares the server and client version of the file by computing a cryptographic hash value for each file; the hash values are identical only if the files are identical in content.

enable_resume   If set to true, MLFileTransfer resumes a previous download that was interrupted because of a communications error or because it was canceled by the user. If the file on the server is newer than the partial local file, the partial file is discarded and the new version is downloaded from the beginning. The force_download parameter overrides this parameter.

num_auth_parms   The number of authentication parameters being passed to authentication parameters in MobiLink events. See Number of Authentication Parameters parameter.

auth_parms   Supplies parameters to authentication parameters in MobiLink events. See Authentication Parameters synchronization parameter.

downloaded_file   Is set to one of the following:

auth_status   Reports the status of MobiLink user authentication. The MobiLink server provides this information to the client. See Authentication Status synchronization parameter.

auth_value   Reports results of a custom MobiLink user authentication script. The MobiLink server provides this information to the client. See Authentication Value synchronization parameter.

file_auth_code   Contains the return code of the optional authenticate_file_transfer script on the server.

error   Contains information about any error that occurs.

Returns

Remarks

You must set the source location of the file to be transferred. This location must be specified as a MobiLink user's directory on the MobiLink server (or in the default directory on that server). You can also set the intended target location and file name of the file.

For example, you can program your application to download a new or replacement database from the MobiLink server. You can customize the file for specific users, since the first location that is searched is a specific user's subdirectory. You can also maintain a default file in the root folder on the server, since that location is used if the specified file is not found in the user's folder.

Callback Function

The callback to observe file transfer progress through the observer parameter has the following prototype:

typedef void(*ml_file_transfer_observer_fn)( ml_file_transfer_status * status );

The ml_file_transfer_status object passed to the callback is defined as follows:

typedef struct ml_file_transfer_status {
    asa_uint64                  file_size;
    asa_uint64                  bytes_received;
    asa_uint64                  resumed_at_size;
    ml_file_transfer_info_a *   info;
    asa_uint16                  flags;
    asa_uint8                   stop;
} ml_file_transfer_status;

file_size   The total size in bytes of the file being downloaded.

bytes_received   Indicates how much of the file has been downloaded so far, including previous synchronizations, if the download is resumed.

resumed_at_size   Used with download resumption and indicates at what point the current download resumed.

info   Points to the info object passed to MLFileTransfer. You can access the user_data parameter through this pointer.

flags   Provides additional information. The value MLFT_STATUS_FLAG_IS_BLOCKING is set when MLFileTransfer is blocking on a network call and the download status has not changed since the last time the observer function was called.

stop   May be set to true to cancel the current download. You can resume the download in a subsequent call to MLFileTransfer, but only if you have set the enable_resume parameter.