UltraLite User's Guide
  Developing UltraLite Applications
    Adding synchronization to your application

Writing a synchronization callback function

The callback function that you use to monitor synchronization takes a ul_synch_status structure as parameter. The ul_synch_status structure has the following members:

• state    One of the following states:

  • UL_SYNCH_STATE_STARTING    No synchronization actions have yet been taken.

  • UL_SYNCH_STATE_CONNECTING    The synchronization stream has been built, but not yet opened.

  • UL_SYNCH_STATE_SENDING_HEADER    The synchronization stream has been opened, and the header is about to be sent.

  • UL_SYNCH_STATE_SENDING_TABLE    A table is being sent.

  • UL_SYNCH_STATE_SENDING_DATA    Schema information or data is being sent.

  • UL_SYNCH_STATE_FINISHING_UPLOAD    The upload stage is completed and a commit is being carried out.

  • UL_SYNCH_STATE_RECEIVING_UPLOAD_ACK    An acknowledgement that the upload is complete is being received.

  • UL_SYNCH_STATE_RECEIVING_TABLE    A table is being received.

  • UL_SYNCH_STATE_SENDING_DATA    Schema information or data is being received.

  • UL_SYNCH_STATE_COMMITTING_DOWNLOAD    The download stage is completed and a commit is being carried out.

  • UL_SYNCH_STATE_SENDING_DOWNLOAD_ACK    An acknowledgement that download is complete is being sent.

  • UL_SYNCH_STATE_DISCONNECTING    The synchronization stream is about to be closed.

  • UL_SYNCH_STATE_DONE    Synchronization has completed successfully.

  • UL_SYNCH_STATE_ERROR    Synchronization has completed, but with an error.

    For a description of the synchronization process, see The synchronization process.

• tableCount    The total number of tables in the database. This number may be more than the number of tables being synchronized.

• tableIndex    The current table which is being uploaded or downloaded. This number may skip values when not all tables are being synchronized.

• info    A pointer to the ul_synch_info structure.

• received.inserts    The number of inserted rows that have been downloaded so far.

• received.updates    The number of updated rows that have been downloaded so far.

• received.deletes    The number of deleted rows that have been downloaded so far.

• received.bytes    The number of bytes that have been downloaded so far.

• sent.inserts    The number of inserted rows that have been uploaded so far.

• sent.updates    The number of updated rows that have been uploaded so far.

• sent.deletes    The number of deleted rows that have been uploaded so far.

• sent.bytes    The number of bytes that have been uploaded so far.

• stop    Set this member to true to interrupt the synchronization

Example 

The following code illustrates how a very simple observer function could be implemented:

extern void __stdcall ObserverFunc(
    p_ul_synch_status status )
{
    printf( "UL_SYNCH_STATE is %d: ",
            status->state );
    switch( status->state ) {
        case UL_SYNCH_STATE_STARTING:
        printf( "Starting\n");
        break;
    case UL_SYNCH_STATE_CONNECTING:
        printf( "Connecting\n"  );
        break;
    case UL_SYNCH_STATE_SENDING_HEADER:
        printf( "Sending Header\n" );
        break;
    case UL_SYNCH_STATE_SENDING_TABLE:
        printf( "Sending Table %d of %d\n",
                status->tableIndex + 1,
                status->tableCount );
        break;
...

This function produces the following output when synchronizing two tables:

UL_SYNCH_STATE is 0: Starting
UL_SYNCH_STATE is 1: Connecting
UL_SYNCH_STATE is 2: Sending Header
UL_SYNCH_STATE is 3: Sending Table 1 of 2
UL_SYNCH_STATE is 3: Sending Table 2 of 2
UL_SYNCH_STATE is 4: Receiving Upload Ack
UL_SYNCH_STATE is 5: Receiving Table 1 of 2
UL_SYNCH_STATE is 5: Receiving Table 2 of 2
UL_SYNCH_STATE is 6: Sending Download Ack
UL_SYNCH_STATE is 7: Disconnecting
UL_SYNCH_STATE is 8: Done

CustDB example 

An example of an observer function is included in the CustDB sample application. The implementation in CustDB provides a dialog that displays synchronization progress and allows the user to cancel synchronization. The user-interface component makes the observer function platform specific.

The CustDB sample code is in the Samples\UltraLite\CustDB subdirectory of your SQL Anywhere directory. The observer function is contained in the platform-specific subdirectories of the CustDB directory.