Skip Headers
Oracle® Database Lite Developer's Guide
10g (10.2.0)
Part No. B15920-01
  Go To Table Of Contents
Contents		 Go To Index
Index
Previous
Previous 		Next
Next 		 

4 Invoking Synchronization APIs from Applications

The following sections describe the APIs available to start synchronization programmatically within your application, whether the application is COM, C, C++, or Java:

4.1 Synchronization API For the COM Interface

You can perform the upload phase of the synchronization process in your application with the COM interface—which uses the mSync_com.dll and ocapi.dll libraries. You can use COM interface languages—such as Visual Basic and VBScript—when implementing your application.

The interface is contained in the msync library. Use MSync.ISync as the interface name.

The COM Interface supports the following synchronization features:

  1. Setup client-side user profiles with data such as user name, password, and server.

  2. Assign table level synchronization options.

  3. Choose the type of transport.

  4. Enable users to start the synchronization process.

  5. Track progress of the synchronization.


Note:

The COM Interface API and samples are installed in the ORACLE_HOME\Mobile\SDK\Examples\mysncCom subdirectory in the mSync_com.dll library:

The following sections discuss how to implement the upload phase of synchronization using the COM Interface:

4.1.1 COM Interface ISyncOption Interface

The ISyncOption interface contains the MSync.SyncOption class, which defines the parameters of the synchronization process. Table 4-1 lists the SyncOption public methods.

Table 4-1 ISyncOption Public Methods

Name Description
void load() Loads the profile of the last synchronization user.
void save() Saves settings to the user profile.
void getPublication (BSTR app_name, BSTR * pub_name) Uses the Web-to-Go application name and returns the publication name.
void setSyncFlag(BSTR pub_name, BSTR tbl_name, short syncFlag) Sets selective sync on table level. You must perform an intial synchronization before you can issue a selective sync.

Passing pub_name, tbl_name=null, syncFlag = 0 turns off syncFlag for every table in that publication.

Passing pub_name, tbl_name, syncFlag = 1 turns on syncFlag for that specific table.


Table 4-2 lists the ISyncOption public properties.

Table 4-2 ISyncOption Public Properties

Name Description
username Name of the user.
password User password.
syncParam A name/value string that designates the synchronization preferences. For information on how to set up the string, see Section 4.1.2, "COM Interface SyncParam Settings".
transportType Type of transport to use. Currently, only HTTP is supported; however, if you set the security to SSL in syncParam, HTTPS is used under the covers.
transportParam A name/value string that designates the transport to the Mobile Server. See Section 4.1.3, "COM Interface TransportParam Parameters" for information on how to set up this string.
BSTR app_name(in) Web-to-Go application name.
BSTR& pub_name(out) Publication name.

The following Visual Basic code demonstrates how to start a synchronization session using default settings.


Note:

On Windows CE, the ISyncOption interface object must be Dim'ed as follows:

Dim syncOpt as MSync.SyncOption 


Set syncOpt = CreateObject("MSync.SyncOption")

' Load last sync info
syncOpt.load

' Change user name to Sam
syncOpt.username = "Sam"

Set sync = CreateObject("MSync.Sync")

' Tell ISync to use this option

sync.setOptionObject (syncOpt)

' Do sync

sync.DoSync

For information on the Sync object used in this example, see Section 4.1.6, "Initiate Synchronization with the ISync Interface".

4.1.2 COM Interface SyncParam Settings

You can set support parameters for the synchronization session by providing a string that consists of name or name/value pairs in the SyncParam object.

The structure of the string with the name/value pairs is as follows: 

"name=value;name2=value2;name3=value3, ...;"

The names are not case sensitive, but the values are. The names that can be used are listed in Table 4-3.

Table 4-3 COM Interface SyncParam Settings

Name Value/Options Description
reset N/A Clears all entries in the environment before applying any remaining settings.
security SSL Choose either SSL encryption or AES stream encryption.
pushonly N/A Upload changes from the client to the server only, as download is not allowed. This is useful when the data transfer is a one way transmission from the client to server.
noapps N/A Do not download any new or updated applications. This is useful when synchronizing over a slow connection or on a slow network.
syncDirection SendOnly

ReceiveOnly

SendOnly is the same as pushonly.

ReceiveOnly allows no changes to be posted to the server.

You must implement your own transport for this setting.

noNewPubs N/A The server will not send any new publications that were created since the last synchronization; only data from current publications are updated.
fullrefresh N/A Forces a complete refresh of all data for all publications.

For example, the following SyncParam string enables SSL security and disables application deployment for the current synchronization session: 

syncOpt.syncParam = "security=SSL; noapps;"

The following string resets all previous settings, then requests a push of the changes: 

syncOpt.syncParam = "reset;pushOnly;"

4.1.3 COM Interface TransportParam Parameters

With the TransportParam object, you can set the host, port, proxy server, and cookie for the Mobile Server. The format of the TransportParam string is used to set specific parameters using a string of a name or name/value pairs.

For example, 

"name=value;name2=value2;name3=value3, ...;"

The names are not case sensitive, but the values are. Table 4-4 lists the TransportParam parameters.

Table 4-4 COM Interface TransportParam Parameters

Name Value Description
reset N/A Clears all entries in the environment before applying the rest of the settings.
server server hostname The hostname or IP address of the Mobile Server.
proxy proxy server hostname The hostname or IP address of the proxy server.
proxyPort port number The port number of the proxy server.
cookie cookie string The cookie to be used for transport.

The following example directs the Mobile Sync engine to use the server at test.oracle.com through the proxy proxy.oracle.com at port 8080. 

syncOpt.TransportParam = 
      "server=test.oracle.com;proxy=proxy.oracle.com;proxyPort=8080;"

4.1.4 Selective Synchronization

The Mobile application can select the way specific tables are synchronized. That is, you can implement selective synchronization at the publication and table level by using the mSync.SyncOption interface to determine which publication and publication items are allowed to synchronize. The list of tables can be changed dynamically during runtime.


Note:

You must perform an intial synchronization before you can issue a selective sync.

Use the setSyncFlag method to designate selective synchronization: 

void setSyncFlag(BSTR pub_name, BSTR  tbl_name, short syncFlag)

Table 4-5 setSyncFlag Parameters

Parameter Description
pub_name The publication name is optional. If set to null, then the value of syncFlag is applied to all publications.
tbl_name The table name (in the form <client database>.<table name>) is optional. If set to null, the parameter means all tables.
syncFlag The synchronization flag is set to 1 to turn ON the syncFlag or to 0 to turn OFF the syncFlag.

The following sample code demonstrates how to turn off synchronization for all but one table. The table name in this sample is ORD_DETAIL. First the synchronization flag is set to 0 to turn off synchronization for all tables and then it is set to 1 to set on synchronization only for the specified table. 

Dim syncOpt As MSYNC.SyncOption
syncOpt = CreateObject("MSync.SyncOption")
'Turn off sync flag for all tables.
syncOpt.setSyncFlag("", "", 0)  
'Turn on sync flag only for the OrdersODB.ORD_DETAIL table.
syncOpt.setSyncFlag("", "OrdersODB.ORD_DETAIL", 1)

4.1.5 ISyncProgressListener Interface

You can track the status of the synchronization with the progress method of the ISyncProgressListener interface, which you create to return updates from the ISync interface. Basically, the ISyncProgressListener interface collects progress updates during synchronization. Table 4-6 lists the progress method and its parameters.

Table 4-6 ISyncProgressListener Abstract Method

Name Description
HRESULT progress( [in] int progressType, int param1, int param2); Called by the synchronization engine when new progress information is available. The progressType is set to one of the progress type constants defined in the ISyncProgressListener Constants table. Current is the current count completed, and total is the maximum. When current value equals the total value, then the stage is completed. The unit for total and current differs depending on the progressType.

The information that the ISyncProgressListener tracks is listed in Table 4-7.

Table 4-7 ISyncProgressListener Constants

Name Progress Type
PT_INIT Reports that the synchronization engine is in the initializing stage. The current and total counts are both set to 0.
PT_PREPARE_SEND Reports that the synchronization engine is preparing local data to be sent to the server. This includes getting locally modified data. For streaming implementations, this is much shorter.
PT_SEND Reports that the synchronization engine is sending data to the network. The total count denotes the number of bytes to be sent, and current is the byte count sent currently.
PT_RECV Reports that the engine is receiving data from the server. The total count denotes the number of bytes to be received, and current is the byte count received currently.
PT_PROCESS_RECV Reports that the engine is applying the newly received data from the server to local data stores.
PT_COMPLETE Reports that the engine has completed the synchronization process.

The following Visual Basic example demonstrates how to report events: 

' Define the ISync object with eventsDim WithEvents sync As MSync.sync' Create the callback.' The name of the callback is the name of the ISync object (not the class), and ' underscore and then the function name - progressPrivate Sub sync_progress(ByVal progressType As Long, ByVal param1 As Long, ByVal param2 As Long)    Desc = ""    ' Decipher the progressType    Select Case progressType        Case PT_SEND            Desc = "Sending data..."        Case PT_RECV            Desc = "Receiving..."    End SelectEnd Sub

4.1.6 Initiate Synchronization with the ISync Interface

The ISync interface, whose methods are described in Table 4-8, allows the user to initiate the synchronization process.

Table 4-8 ISync Interface Abstract Methods

Name Description
HRESULT doSync() Start the synchronization process. This blocks access until the synchronization process is completed.
void abort() Aborts the current synchronization. This can be called from a progress listener callback.
HRESULT setOption( ISyncOption *syncObj) Sets the pointer to SyncOption to use for the next synchronization. If this function is not called before doSync(), the last saved option will be used. See Section 4.1.1, "COM Interface ISyncOption Interface" for information on SyncOption.

The following Visual Basic example demonstrates how to start a synchronization session using default settings. 

Dim sync As Msync.sync

Set sync = CreateObject("MSync.Sync")

sync.DoSync

If SyncOption is not provided, the interface loads the last saved information to perform synchronization.

4.2 Synchronization APIs For C or C++ Applications

You can initiate and monitor synchronization from a C or C++ client application. The synchronization methods for the C/C++ interface are contained in ocapi.h and ocapi.dll, which are located in the <ORACLE_HOME>\Mobile\bin directory.

A C++ example is provided in the <ORACLE_HOME>\Mobile\Sdk\Samples\sync\msync\src directory. The source code is contained in SimpleSync.cpp. The executable—SimpleSync.exe—is in the <ORACLE_HOME>\Mobile\Sdk\Samples\sync\msync\bin directory.

The functions available for setting up and initiating the synchronization are as follows:

  1. Section 4.2.1, "Initializing the Environment With ocSessionInit"

  2. Section 4.2.2, "Managing the C/C++ Data Structures"

  3. Section 4.2.3, "Retrieving Publication Information With ocGetPublication"

  4. Section 4.2.4, "Managing User Settings With ocSaveUserInfo"

  5. Section 4.2.5, "Manage What Tables Are Synchronized With ocSetTableSyncFlag"

  6. Section 4.2.6, "Start the Synchronization With the ocDoSynchronize Method"

  7. Section 4.2.7, "Clear the Synchronization Environment Using ocSessionTerm"

4.2.1 Initializing the Environment With ocSessionInit

The ocSessionInit function initializes the synchronization environment—which is contained in the ocEnv structure. For a full description of ocEnv, see Section 4.2.2.1, "ocEnv Data Structure".

Syntax

int ocSessionInit( ocEnv env );

Table 4-9 lists the ocSessioninit parameter and its description.

Table 4-9 ocSessionInit Parameters

Name Description
env An ocEnv class, which contains the synchronization environment.

This call initializes the ocEnv structure and restores any user settings that were saved in the last ocSaveUserInfo call (See Section 4.2.4, "Managing User Settings With ocSaveUserInfo"). An ocEnv structure is passed as the input parameter, where the ocEnv should be already created by the caller. If the caller wants to overwrite user preference information after the ocSessionInit() call, it can be done by calling ocSaveUserInfo.

The following example allocates a new ocEnv, which is then passed into the ocSessionInit call. 

env = new ocEnv;
// Reset ocenv
memset(env, 0, sizeof(ocEnv) );
 
// init OCAPI
rc = ocSessionInit(env);

4.2.2 Managing the C/C++ Data Structures

Two data structures—ocEnv Data Structure and ocTransportEnv Data Structure—are used for certain functions in the Mobile Sync API.

4.2.2.1 ocEnv Data Structure

The ocEnv data structure holds internal memory buffers and state information. Before using this structure, the application initializes it by passing it to the ocSessionInit method.

Table 4-10 lists the field name, type, usage, and corresponding description of the ocEnv structure parameters.

Table 4-10 ocEnv Structure Field Parameters

Field Type Usage Description
username char[32] Required. Set before calling ocSessionInit. Name of the user to authenticate.
password char[32] Required. Set before calling ocSessionInit. User password (clear text).
newPassword char[32] Optional. Can set after calling ocSessionInit. If first character of this string is not null—in otherwords (char) 0—this string is sent to the server to change the user password; the password change is effective on the next synchronization session.
savePassword Short Optional. Can set after calling ocSessionInit. If set to 1, the password is saved locally and is loaded the next time ocSessionInit is called.
appRoot char[32] Optional. Can set after calling ocSessionInit. Directory to where the application will be copied. If first character is null, then it uses the default directory.
priority Short Optional. Can set after calling ocSessionInit. 0= OFF (default)

1= ON; Only high priority table or rows are synchronized when turned on.

secure Short Optional. Can set after calling ocSessionInit. If set to 0, then AES is used on the transport. If set to OC_SSL_ENCRYPTION, use SSL synchronization (SSL-enabled device only).
syncDirection Enum Optional. Can set after calling ocSessionInit. If set to 0 (OC_SENDRECEIVE), then sync is bi-directional (default).If set to OC_SENDONLY, then push changes only to the server. This stops the sync after the local changes are collected and sent. User must write own transport method (like floppy bases) when using this method.If set to OC_RECEIVEONLY, then send no changes and only receive update from server. This only performs the receive and allow changes function to local database stages.
trType Enum Required. Set before calling ocSessionInit. If set to 0 (OC_BUILDIN_HTTP), then use HTTP built-in transport driver. If set to OC_USER_METHOD, then use user provided transport functions.
exError ocError Read-only information updated by OCAPI. Extended error code - either OS or OKAPI error code.
transportEnv ocTransportEnv
Transport buffer. See Section 4.2.2.2, "ocTransportEnv Data Structure".
progressProc fnProgress Optional. Can set after calling ocSessionInit. If not null, points to the callback for progress listening.
totalSendDataLen Long
Reserved
totalRecieveDataLen Long
Reserved
userContext Void* Optional. Can set after calling ocSessionInit. Can be set to anything by the caller for context information (such as progress dialog handle, renderer object pointer, and so on.
ocContext Void*
Reserved.
logged Short
Reserved.
bufferSize Long
Reserved (for Wireless/Nettech only).
pushOnly Short Optional. Can set after calling ocSessionInit. If set to 1, then only push changes to the server.
syncApps Short Optional. Can set after calling ocSessionInit. Set to 1 (by default), performs application deployment. If set to 0, then no applications will be received from the server.
syncNewPublications Short Optional. Can set after calling ocSessionInit. If set to 1 (default), receives any new publication created from the server since last synchronization. If set to 0, only synchronizes existing publications (useful for slow transports like wireless).
clientDbMode Enum Optional. Can set after calling ocSessionInit. If set to OC_DBMODE_EMBEDDED (default), it uses local Oracle Database Lite ODBC driver. If set to OC_DBMODE_CLIENT, it uses the Branch Office driver.
syncTimeLog Short Optional. Can set after calling ocSessionInit. If set to 1, log sync start time is recorded in the conscli.odb file.
updateLog Short Optional. Can set after calling ocSessionInit. Debug only. If set to 1, logs server-side insert and update row information to the publication odb.
options Short Optional. Can set after calling ocSessionInit. Debug only. A bitset of the following flags:

  • OCAPI_OPT_SENDMETADATA

    Sends meta-info to the server.

  • or OCAPI_OPT_DEBUG

    Enables debugging messages.

  • OCAPI_OPT_DEBUG_F

    Saves all bytes sent and received for debugging.

  • OCAPI_OPT_NOCOMP

    Disables compression.

  • If set, OCAPI will try to abort the current sync session.

  • OCAPI_OPT_FULLREFRESH

    Forces OCAPI to purge all existing data and do a full refresh.

cancel Short Caller can set to 1 on next operation. ocDoSyncrhonize returns with -9032.

The environment structure contains fields that the caller can update to change the way Mobile Sync module works. The following example demonstrates how to set the fields within the ocEnv structure. 

typedef struct ocEnv_s {
 // User info

char username[MAX_USERNAME];    // Mobile Sync Client id 

char password[MAX_USERNAME];    // Mobile Sync Client password for 

                                // authentication during sync 

char newPassword[MAX_USERNAME]; // resetting Mobile Sync Client password 

                                   // on server side if this field is not blank 
short savePassword;           // if set to 1, save password 

char appRoot[MAX_PATHNAME];     // dir path on client device for deploying files

short priority;              // High priority table only or not

short secure;            // if set to 1, data encrypted over the wire 

enum {

OC_SENDRECEIVE = 0,     // full step of synchronize

OC_SENDONLY,     // send phase only

OC_RECEIVEONLY,     // receive phase only


                       // For Palm Only

OC_SENDTOFILE,     // send into local file | pdb

OC_RECEIVEFROMFILE     // receive from local file | pdb

}syncDirection;     // synchronize direction


enum {

OC_BUILDIN_HTTP = 0,     // Use build-in Http transport method

OC_USER_METHOD     // Use user defined transport method

}trType;           // type of transport


ocError exError;     // extra error code


ocTransportEnv transportEnv;     // transport control information 


                       // GUI related function entry

progressProc fnProgress;     // callback to track progress; this is optional


                 // Values used for Progress Bar. If 0, progress bar won't show.
long totalSendDataLen; // set by Mobile Sync API informing transport total number 
                     // of bytes to send; set before the first fnSend() is called

long totalReceiveDataLen;     // to be set by transport informing Mobile Sync API 

                       // total number of bytes to receive; 

                       // should be set at first fnReceive() call. 

void* userContext;     // user defined context
void* ocContext;       // internal use only
short logged;          // internal use only
long bufferSize;       // send/receive buffer size, default is 0
short pushOnly;        // Push only flag
short syncApps;        // Application deployment flag
short cancel;          // cancel   

} ocEnv;

4.2.2.2 ocTransportEnv Data Structure

You can configure the HTTP URL, proxy, proxy port number and other HTTP-specific transport definitions in the ocTrHttp structure. This structure is an HTTP public structure defined in octrhttp.h.

You access the ocTrHttp structure from within the ocTransportEnv data structure, which is provided as part of the ocEnv data structure. The following demonstrates the fields within the ocTransportEnv structure: 

typedef struct ocTransportEnv_s {

void* ocTrInfo;            // transport internal context

The ocTrInfo is a pointer that points to the HTTP parameters in the ocTrHttp structure. The following code example retrieves the ocTrInfo pointer to the HTTP parameters and then modifies the URL, proxy, and proxy port number to the input arguments: 

ocTrHttp* http_params = (ocTrHttp*)(env->transportEnv.ocTrInfo);
// set server_name
strcpy(http_params->url, argv[3]); 
// set proxy
strcpy(http_params->proxy, argv[4]); 
// set proxy port
http_params->proxyPort = atoi(argv[5])

4.2.3 Retrieving Publication Information With ocGetPublication

This function gets the publication name on the client from the Web-to-Go application name. The Web-to-Go user knows only the application name, which happens when the Packaging Wizard is used to package an application before publishing it.

Syntax

ocError ocGetPublication(ocEnv* env, const char* application_name, 

char* buf, int buf_len);

The parameters for the ocGetPublication function are listed in Table 4-11 below. The table lists the name of the ocGetPublication parameter and provides a description of it.

Table 4-11 ocGetPublication Parameters

Name Description
ocEnv* env Pointer to an ocEnv structure buffer to hold the return synchronization environment.
const char* application_name(in) This is the name of the application.
char* buf(out) The buffer where the publication name will be stored.
int buf_len(in) The buffer length. It must be at least 32 bytes.

Return value of 0 indicates that the function has been executed successfully. Any other value is an error code.

This function gets the publication name from the Web-to-Go application name and stores it in the buffer.

The following code example demonstrates how to get the publication name. 

void sync()

{

         ocEnv env;

         int rc;


         // Clean up ocenv

         memset(&env 0, sizeof(env) );

         

         // init OCAPI

         rc = ocSessionInit(&env);


         strcpy(env.username, "john");

         strcpy(env.password, "john");


         // We use transportEnv as HTTP paramters

         ocTrHttp* http_params = (ocTrHttp*)(env.transportEnv.ocTrInfo);

         strcpy(http_params->url, "your_host");


         // Do not sync webtogo applicaton "Sample3"
         char buf[32];

         rc = ocGetPublication(&env, "Sample3", buf, sizeof(buf));

         rc = ocSetTableSyncFlag(&env, buf, NULL, 0);


         // call sync

         rc = ocDoSynchronize(&env);

         if (rc < 0)

                fprintf(stderr, "ocDoSynchronize failed with %d:%d\n",                      rc, env.exError);

         else

                printf("Sync compeleted\n");

         

         // close OCAPI session

         rc = ocSessionTerm(&env);

         return 0;

}

4.2.4 Managing User Settings With ocSaveUserInfo

Saves user settings to the conscli.odb database file.

Syntax

int ocSaveUserInfo( ocEnv *env );

The parameter for ocSaveUserInfo function is listed in a table below.

Table 4-12 lists the ocSaveUserInfo parameter and its description.

Table 4-12 ocSaveUserInfo Parameters

Name Description
env Pointer to the synchronization environment.

This saves or overwrites the user settings into a file or database on the client side. The following information provided in the environment structure is saved.

  • Username

  • Password

  • SavePassword

  • URL

  • UseProxy

  • ProxyServer

  • ProxyPort

  • Secure

For more information on how to use these fields, see Section 4.2.2, "Managing the C/C++ Data Structures".

4.2.5 Manage What Tables Are Synchronized With ocSetTableSyncFlag

Update the table flags for selective sync. Call this for each table to specify whether it should be synchronized(1) or not (0) for the next session. Selective sync only works if you have first performed at least one synchronization for the client. Then, set the flag so that on the next synchronize—that is, before the next invocation of the ocDoSynchronize method—a selective sync occurs.

The default sync_flag setting for ocSetTableSyncFlag is TRUE (1) for all the tables; that is, all tables are flagged to be synchronized. If you want to selectively synchronize specific tables, you must first disable the default setting for all tables and then enable the synchronization for only the specific tables that you want to synchronize.

Syntax

ocSetTableSyncFlag(ocEnv *env, const char* publication_name, 

const char* table_name, short sync_flag)

Table 4-13 lists the name and description of parameters for the ocSetTableSyncFlag function.

Table 4-13 ocSetTableSyncFlag Parameters

Name Description
env Pointer to the synchronization environment.
publication_name The name of the publication which is being synchronized. If the value for the publication_name is NULL, it means all publications in the database. This string is the same as the client_name_template parameter of the Consolidator Manager CreatePublication method. In most cases, you will use NULL for this parameter. For more information, see Section 3.5.4, "Creating Publications" in Chapter 3, "Synchronization".
table_name This is the name of the snapshot. It is the same as the name of the store, the third parameter of CreatePublicationItem(). For more information, see Section 3.5.5, "Creating Publication Items" in Chapter 3, "Synchronization".
sync_flag If the sync_flag is set to 1, you must synchronize the publication. If the sync_flag is set to 0, then do not synchronize. The value for the sync_flag is not stored persistently. Each time before ocDoSynchronize(), you must call ocSetTableSyncFlag().

This function allows client applications to select the way specific tables are synchronized.

Set sync_flag for each table or each publication. If sync_flag = 0, the table is not synchronized.

To synchronize specific tables only, you must perform the following steps:

  1. Disable the default setting, which is set to 1 (TRUE) for all the tables.

    Example: 

    ocSetTableSyncFlag(&env, <publication_name>,null,0)

    Where <publication_name> must be replaced by the actual name of your publication, and where the value null is specified to mean all the tables for that publication without exception.

  2. Enable the selective synchronization of specific tables.

    Example: 

    ocSetTableSyncFlag(&env, <publication_name>,<table_name>,1)

4.2.6 Start the Synchronization With the ocDoSynchronize Method

Starts the synchronization process.

Syntax

int ocDoSynchronize( ocEnv *env );

The parameter for the ocDoSynchronize method is listed in a table below.

Table 4-14 lists the name and description of the ocDoSynchronize parameter.

Table 4-14 ocDoSynchronize Parameters

Name Description
env Pointer to the synchronization environment.

This starts the synchronization cycle. A round trip synchronization is activated if syncDirection is OC_SENDRECEIVE (default). If syncDirection is OC_SENDONLY or OC_RECEIVEONLY, then the developer must implement a custom transport. If the developer wishes to upload only changes, then set pushonly=1. You cannot only download changes under the existing synchronization architecture.

A return value of 0 indicates that the function has been executed successfully. Otherwise, the value is an error code.

4.2.7 Clear the Synchronization Environment Using ocSessionTerm

Clears and performs a cleanup of the synchronization environment.

Syntax

int ocSessionTerm( ocEnv *env );

The parameter for ocSessionTerm function is listed in a table below.

Table 4-15 lists the ocSessionTerm parameter and its description.

Table 4-15 ocSessionTerm Parameters

Name Description
env Pointer to the environment structure returned by ocSessionInit.

De-initializes all the structures and memory created by the ocSessionInit() call. Users must ensure that they are always called in pairs.

4.3 Synchronization API for Java Applications

The following sections describe how you can use Java on a Pocket PC device to build your own client synchronization initiation:

4.3.1 Overview

Using the Java interface for Mobile Sync client-side synchronization tasks, programs written in Java can use the functionality provided by the OCAPI library. The Java interface resides in the oracle.lite.msync package.

The Java interface provides for the following functions:

  • Setting client side user profiles containing data such as user name, password, and server

  • Starting the synchronization process

  • Tracking the progress of the synchronization process

The Java interface consists of two files, mSync.jar and msync_java.dll. To use the Java interface, the mSync.jar file must be included in the classpath. The mSync.jar file is located in the following directory.

<ORACLE_HOME>\Mobile\classes

The msync_java.dll file is located in the following directory.

<ORACLE_HOME>\Mobile\bin

There are four parts to the Java interface. They are:

  • Sync Class

  • SyncException Class

  • SyncOption Class

  • SyncProgressListener Interface

The following sections describe the Java interface.

4.3.2 Sync Class

This class initiates synchronization by using the provided synchronization options. The parameters for the constructor are listed in Table 4-16.

Constructors

Sync(SyncOption option)

Table 4-16 Sync Class Constructor

Parameter Description
option Instance of the SyncOption Class. This contains all the parameters needed to perform synchronization.

Public Methods

To monitor the progress of the synchronization process, the public method SyncProgressListener adds a progress listener to the object.

SyncProgressListener add(ProgressListener listener)

The parameters for the SyncProgressListener method are described in Table 4-17.

Table 4-17 Sync Class Public Method

Parameter Description
listener An object that implements the ProgressListener interface. The synchronization object calls the progress() function of this object to notify it of the synchronization progress.
void doSync () Starts a synchronization session and blocks that thread until synchronization is complete.
void abort () Aborts the synchronization session.

The following code demonstrates how to start a session using the default settings. 

try
{
  Sync mySync = new Sync( new SyncOption());
  mySync.doSync();
}
catch ( SyncException e)
{
  System.err.println( "Sync Error:"+e.getMessage());
}

4.3.3 SyncException Class

This class signals a non-recoverable error during the synchronization process. The SyncException() class constructs a clear object. The parameters for the constructor are listed inTable 4-18:

Constructors

SyncException()

SyncException(int errorCode, string errorMessage)

Table 4-18 syncException Constructor Parameter Description

Parameter Description
errorCode The error. Refer the Oracle Database Lite Message Reference.
errorMessage A readable text message that provides extra information.

Public Methods

The methods for the SyncException are listed in Table 4-19.

Table 4-19 SyncExceptionClass Public Methods

Parameters Description
int getErrorCode() Gets the error code.
String getErrorMessage Gets the error message.

4.3.4 SyncOption Class

The SyncOption class is used to define the parameters for the synchronization process. It can either be constructed manually, or can save or load data from the user profile.

Constructors

SyncOption()
 
SyncOption
   ( String user,
     String password,
     String syncParam,
     String transportDriver,
     String transportParam)

The parameters for the SyncOption constructor are listed in Table 4-20:

Table 4-20 SyncOption Constructors

Parameter Description
user A string containing the name used for authentication by the Mobile Server.
password A string containing the user password.
syncParam A string which defines an optional list of parameters for the synchronization session. See Section 4.3.5, "Java Interface SyncParam Settings" for more information.
transportDriver A string containing the name of the transport driver. Currently, only "HTTP" is supported.
transportParam A string containing all the parameters needed for the specified driver to operate. See Section 4.3.6, "Java Interface TransportParam Parameters" for more information.
priority A boolean value which limits synchronization to server tables flagged as high priority, otherwise all tables are synchronized.
pushOnly A boolean value which makes synchronization push only.

Public Methods

These methods load and save the user profile. The parameters of the public methods are listed in Table 4-21:

Table 4-21 Sync Option Public Method Parameters

Parameter Description
void load(String username) This loads the profile for the specified user name. If the user name is left null, the profile is loaded for the last user to synchronize.
void save() This saves the settings to the profile for the active user.
void setUser(String username) This is used to set and get the current user.
String getuser()
void setPassword(String password)String getPassword() This is used to set and get the password.
void setSyncParam(String syncParam) string getSyncParam() This is used to set and get the synchronization parameters.
void setTransportDriver(String driverName) String getTransportDriver() This is used to set and get the driver name. Release 5.0.2 supports the "HTTP" driver.
void setTransportParam(String transportParam) String getTransportParam() Set and get the transport parameters.

Example

The following code example demonstrates how to start a synchronization session using the default settings: 

SyncOption opt = new SyncOption
 
("sam","lion","pushonly","HTTP","server=server1;proxy=www-proxy.us.oracle.com;proxyPort=80");
 
opt.save();

4.3.5 Java Interface SyncParam Settings

The syncParam is a string that can be passed when creating the SyncOption object. It allows support parameters to be specified to the synchronization session. The string is constructed of name-and-value pairs. For example: 

"name=value;name2=value2;name3=value3, ...;"

The names are not case sensitive, but the values are. The field names which can be used are listed in Table 4-22.

Table 4-22 Java Interface SyncParamSettings

Name Value/Options Description
"reset" N/A Clear all entries in the environment before applying any remaining settings.
"security" SSL or AES Use the appropriate selection to choose either SSL or AES stream encryption.
"push only" N/A Use this setting to upload changes from the client to the server only, do not download. This is useful when data transfer is one way, client to server.
"noapps" N/A Do not download any new or updated applications. This is useful when synchronizing over slow connection or on a slow network.
"syncDirection" "sendonly" "receiveonly" "SendOnly" is the same as "pushonly".

"ReceiveOnly" allows no changes to be posted to the server.

"noNewPubs" N/A This setting prevents any new publications created since the last synchronization from being sent, and only synchronizes data from the current publications.
"tableFlag" "enable" The "enable" setting allows [Publication.Item] to be synchronized, "disable" prevents synchronization.
[Publication.Item] "disable"
"fullrefresh" N/A Forces a complete refresh.
"clientDBMode" "EMBEDDED" or "CLIENT" If set to "EMBEDDED", access to the database is by conventional ODBC, if set to "CLIENT" access is by multi-client ODBC.

Example 1

The first example enables SSL security and disables application deployment for the current synchronization session: 

"security=SSL; noapps;"

Example 2

The second example resets all previous settings, activates upload for the "Dept" table only: 

"reset;pushOnly;tableFlag[TestApp.Emp]=disable;tableFlag[TestApp.Dept]=enable;"

4.3.6 Java Interface TransportParam Parameters

The format of the TransportParam string is used to set specific parameters using a string of name-and-value pairs, for example: 

"name=value;name2=value2;name3=value3, ...;"

The names are not case sensitive, but the values are. The field names which can be used are listed in Table 4-23.

Table 4-23 TransportParam Parameters

Name Value Description
"reset" N/A Clear all entries in the environment before applying the rest of the settings.
"server" server hostname The hostname or IP address of the Mobile Server.
"proxy" proxy server hostname The hostname or IP address of the proxy server.
"proxyPort" port number The port number of the proxy server.
"cookie" cookie string The cookie to be used for transport.

Example

The example directs the Mobile Sync engine to use the server at "test.oracle.com" through the proxy "proxy.oracle.com" at port 8080: 

"server=test.oracle.com;proxy=proxy.oracle.com;proxyPort=8080;"

4.3.7 SyncProgress Listener Service

The SyncProgressListener is an interface that allows progress updates to be trapped during synchronization.

This class initiates synchronization by using the provided synchronization options. The parameters for the method are listed in Table 4-24:

Method

void progress
 
   (int progressType,
 
    int completed);

Table 4-24 SyncProgressListener Abstract Method

Parameter Description
progressType This is set to one of the constants listed in Table 4-25.
completed This is the percentage of completion for specific progressType.

The names of the constants which report the synchronization progress are listed in Table 4-25.

Table 4-25 SyncProgressListener Interface Constants

Constant Name Progress Type
PT_INT States that the synchronization engine is in the initializing stage. The current and total counts are set to 0.
PT_PREPARE_SEND States that the synchronization engine is preparing local data to be sent to the server. This includes getting locally modified data. For streaming implementations this takes a shorter amount of time.
PT_SEND States that the synchronization engine is sending data to the network.

The total count equals the number of bytes to be sent, and the current count equals the byte count being sent currently.

PT_RECV States that the synchronization engine is receiving data from the server.

The total count equals the number of bytes to be received, and the current count equals the byte count being received currently.

PT_PROCESS_RECV States that the synchronization engine is applying the newly received data from the server to the local data stores.
PT_COMPLETE States that the synchronization engine has completed the synchronization process.

Example

This simple class implements the SyncProgressListener. 

class myProgressTracker implements SyncProgress Listener;
 {
  public void progress
     (int progressType, 
     int completed)
    {
      System.out.println( "Status: "+progressType+"="+ completed+"%" );
     } //progress
 }

4.4 msync/OCAPIs/mSyncCom

For more information, refer to the Oracle Database Lite API Specification.

  Previous
Previous 		Next
Next
  Go To Table Of Contents
Contents		 Go To Index
Index