|
Downloads a file from a MobiLink server with the MobiLink interface.
ul_bool MLFileTransfer ( ml_file_transfer_info * info );
info A structure containing the file transfer information.
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.
On Windows CE, if dest_path is empty, the file is stored in the root (\) directory of the device.
On the desktop and on Symbian OS, if the dest_path is empty, the file is stored in the user's current directory.
On Palm OS, when downloading to the device external storage, prefix the dest_path with vfs:. The path should then be specified with the platform file naming convention. See Palm OS.
If dest_path field is empty, MLFileTransfer assumes it is downloading a Palm record database (.pdb).
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:
1 if the file was successfully downloaded.
0 if an error occurs. An error occurs if the file is already up-to-date when MLFileTransfer is invoked. In this case, the function returns true rather than false. For the Palm OS, when downloading a record database (.pdb) file, MLFileTransfer always downloads the file, whether the file is up-to-date or not.
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.
ul_true The file was successfully downloaded.
ul_false The file was not downloaded successfully. You can supply Error information in the error field of the ml_file_transfer_info structure. Incomplete file transfers are resumable.
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.
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 syncs 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.