Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

SyncEngine API

Synchronize data for the Rhodes model and handle updates between the Rhodes application and the RhoConnect server. Refer to the Rhodes Developer Guide under Synchronization for more discussion.

login

Authenticates the user with the RhoConnect server. Click here for an example in the Rhodes Developer Guide under Synchronization.

SyncEngine.login(login, password, callback_url)
login The login name for the RhoConnect server.
password The password for the RhoConnect server.
callback_url url to the callback method that is called when the login is finished.

logout

Logs out the user from the RhoConnect server.

SyncEngine.logout

logged_in

True if the user is logged into the RhoConnect server, false otherwise.

SyncEngine.logged_in

dosync

Start a synchronization with the RhoConnect server and show an optional sync status popup.

SyncEngine.dosync(show_sync_status, query_params)
show_sync_status True if you want to show a sync status popup, false otherwise.
query_params Query parameters passed to sync server.

dosync_source

Start a synchronization with the RhoConnect server for a given source id or source name and show an optional status popup.

SyncEngine.dosync_source(source_id_or_name, show_sync_status, query_params)
source_id_or_name The source name or ID.
show_sync_status True if you want to show a sync status popup, false otherwise.
query_params Query parameters passed to sync server.

lock_sync_mutex

Blocks the synchronization call to wait for SyncEngine lock (useful for performing batch operations).

SyncEngine.lock_sync_mutex

unlock_sync_mutex

Release the SyncEngine lock started by lock_sync_mutex.

SyncEngine.unlock_sync_mutex

stop_sync

Stops any synchronization operations currently in progress.

SyncEngine.stop_sync

set_notification

Set notification callback for a model. Click here for an example in the Rhodes Developer Guide under Synchronization.

SyncEngine.set_notification(source_id, callback_url, params)
source_id The source id for the RhoConnect server. If -1, set notification for all Rhodes models, and the callback is not removed after the sync process completes.
callback_url path to the callback method called when the sync is complete.
params parameters for the callback method.

Notification Parameters

When set_notification is called, it receives a variable called @params, just like a normal Rhodes controller action. Below are the common parameters for all notifications;

@params["source_id"] The id of the current model that is synchronizing.
@params["source_name"] Name of the model (i.e. "Product").
@params["sync_type"] Type of sync used for this model: "incremental" or "bulk".
@params["status"] Status of the current sync process: "in_progress", "error", "ok", "complete", "schema-changed".

@params[“status”] = “in_progress”: parameters for incremental sync_type

@params["total_count"] Total number of records that exist for this RhoConnect source.
@params["processed_count"] Number of records included in the sync page.
@params["cumulative_count"] Number of records the SyncEngine has processed so far for this source.

@params[“status”] = “in_progress”: parameters for bulk sync_type

@params["bulk_status"] The state of the bulk sync process: "start", "download", "change_db".

@params[“status”] = “error”: parameters for sync error

@params["error_code"] HTTP response code of the RhoConnect server error: 401, 500, 404, etc.
@params["error_message"] Response body for error (if any).
@params["server_errors"] Hash of Type objects of RhoConnect adapter error (if exists): "login-error", "query-error", "create-error", "update-error", "delete-error", "logoff-error"

For “login-error”, “query-error”, “logoff-error”: Type object is a hash containing a ‘message’ from server:

@params["server_errors"]["query-error"]['message']

For “create-error”, “update-error”, “delete-error”: Type object is a hash each containing an “object” as a key (that failed to create) and a corresponding “message” and “attributes”:

@params["server_errors"]["create-error"][object]['message']  
@params["server_errors"]["create-error"][object]['attributes']

clear_notification

Clears the synchronization notification for a given source id.

clear_notification(source_id)
source_id The id of the source on the RhoConnect server.

on_sync_create_error

Perform an action upon a synchronization create error.

SyncEngine.on_sync_create_error(source_name, objects, action)
source_name The name of the source on the RhoConnect server.
objects One or more error objects.
action :delete to remove the object from client, :recreate to push this object to the server again at the next sync.

on_sync_update_error

Perform an action upon a sync update error.

SyncEngine.on_sync_update_error(source_name, objects, action, rollback_objects)
source_name The name of the source on the RhoConnect server.
objects One or more error objects.
action :retry to push the update object operation to server again at next sync, :rollback to write the rollback_objects to client database.
rollback_objects must be specified for :rollback action. Contains the attributes for the objects before a failed update and send by the server.

on_sync_delete_error

Perform action upon a synchronization delete error.

SyncEngine.on_sync_delete_error(src_name, objects, action)
source_name The name of the source on the RhoConnect server.
objects One or more error objects.
action :retry to push delete object operation to server again at next sync.

set_pollinterval

Updates the SyncEngine poll interval.

SyncEngine.set_pollinterval(interval)
interval number of seconds for the poll interval. 0 disables polling-based synchronization (you may still use push-based-synchronization).

set_syncserver

Sets the RhoConnect server address and stores it in rhoconfig.txt.

SyncEngine.set_syncserver(server_url)
server_url The url for the RhoConnect server.

set_objectnotify_url

Set the callback for when the SyncEngine notifies when a specific object on the current page has been modified.

SyncEngine.set_objectnotify_url(callback_url)
callback_url The url for the callback method called upon the SyncEngine notification.

callback_url – the url for the callback.

set_pagesize

Set the synchronization page size for the SyncEngine.

SyncEngine.set_pagesize(size)
size Size of the SyncEngine synchronization page. Default is 2000.

get_pagesize

Returns the current sync page size for the SyncEngine.

SyncEngine.get_pagesize

enable_status_popup

Enable or disable the show status popup.

SyncEngine.enable_status_popup(true_or_false)
true_or_false true to enable the show status popup. Default is false, except for Blackberry where default is true.

set_ssl_verify_peer

Enable or disable verification of RhoConnect ssl certificates.

SyncEngine.set_ssl_verify_peer(true_or_false)
true_or_false true to enable verification of RhoConnect ssl certificates. Default is true.

get_user_name

Returns the current username of the SyncEngine session if logged_in is true; if false, returns the last logged in username.

SyncEngine.get_user_name

search

Call search on the RhoConnect application.

SyncEngine.search(:source_names, :from, :search_params, :offset, max_results, :callback, :callback_param, :progress_step)
:source_names (optional) list of source names for when you wish to search the RhoConnect server over multiple sources.
:from (optional) Sets the RhoConnect path that records will be fetched with. Default is 'search'.
:search_params hash containing key/value search items.
:offset Starting record to be returned.
:max_results Maximum number of records to be returned.
:callback Callback to be executed after search is completed.
:callback_param (optional) Parameters passed to callback.
:progress_step (optional) Define how often the search callback will be executed with 'in_progress' state.
:sync_changes (optional) true or false(default). Define if the client changes the send to server before search.
Back to Top