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.