Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 10.0.1 » UltraLite - C and C++ Programming » UltraLite C/C++ Common API Reference

Callback function for ULRegisterErrorCallback Next Page

MLFileTransfer function

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.

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.


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 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.