Adding synchronization to your UltraLite application

In UltraLite, synchronization begins by opening a specific connection with the MobiLink server over the configured communication stream (also known as a network protocol). In addition to synchronization support for direct network connections, Palm OS devices also support HotSync synchronization, and Windows Mobile devices also support ActiveSync synchronization.

Defining the connection

Each UltraLite remote that synchronizes with a MobiLink server does so over a network protocol. You set the network protocol with the synchronization stream parameter. Supported network protocols include TCP/IP, HTTP, HTTPS, and TLS. For the protocol you choose, you also need to supply stream parameters that define other required connection information like the MobiLink server host and the port.

You must also supply the MobiLink user information and the synchronization script version with the user_name and version parameters.

Defining the synchronization behavior

You can control synchronization behavior by setting various synchronization parameters. The way you set parameters depends on the specific UltraLite interface you are using.

Important behaviors to consider include:

Synchronization direction By default, synchronization is bi-directional. If you require one-way synchronizations only, remember to use the appropriate upload_only or download_only parameter. By performing one-way synchronizations, you minimize the synchronization time required. Also, with download-only synchronization, you do not have to commit all changes to the UltraLite database before synchronization. Uncommitted changes to tables not involved in synchronization are not uploaded, so incomplete transactions do not cause problems.
To use download-only synchronization, you must ensure that rows overlapping with the download are not changed locally. If any data is changed locally, synchronization fails in the UltraLite application with a SQLE_DOWNLOAD_CONFLICT error.
Concurrent changes during synchronization During the upload phase, UltraLite applications can access UltraLite databases in a read-only fashion. During the download phase, read-write access is permitted, but if an application changes a row that the download then attempts to change, the download will fail and roll back. You can disable concurrent access to data during synchronization by setting the disable_concurrency synchronization parameter.

To add synchronization code to your UltraLite application

Supply the necessary synchronization parameters and protocol options you require for the session as fields of a synchronization information structure.

For example, using the C/C++ API, you add synchronization to the UltraLite application by setting appropriate values in the ul_synch_info structure:

ul_synch_info info;       
       // define a sync structure named "info"
        ULEnableTcpipSynchronization( &sqlca );
       // use a TCP/IP stream
       conn->InitSynchInfo( &info );
       // initialize the structure
       info.stream = ULSocketStream();
       // specify the Socket Stream
       info.stream_parms= UL_TEXT( "host=myMLserver;port=2439"  );
       // set the MobiLink host information
       info.version = UL_TEXT( "custdb 11.0" );
       // set the MobiLink version information
       info.user_name = UL_TEXT( "50" );
       // set the MobiLink user name
       info.download_only =ul_true;
       // make the synchronization download-only

Initialize synchronization.

For direct TCP/IP-based synchronization, you would call an API-specific synchronization function. These functions return a boolean indicating success or failure of the synchronization operation. If the synchronization fails, you can examine detailed error status fields in another structure to get additional error information.

For HotSync synchronization, you must use the ULSetSynchInfo function, supplying the ul_synch_info structure as an argument. This attaches the ul_synch_info structure to the current database for use on a subsequent synchronization.

For ActiveSync synchronization, you must catch the synchronization message from the ActiveSync provider and use the DoSync function to call ULSynchronize.
Use an observer callback function if you want to report the progress of the synchronization to the user.

Tip
If you have an environment where DLLs fail either because the DLL is very large or the network connection is unreliable, you may want to implement resumable downloads. See Handling failed downloads and Resuming failed downloads.