Callback Handler API

The SUPCallbackHandler protocol is invoked when any database event occurs. A default callback handler is provided, which basically does nothing. You should implement a custom CallbackHandler to register important events. The callback is invoked on the thread that is processing the event. A callback handler provides message notifications and success or failure messages related to message-based synchronization. To receive callbacks, register your own handler with a database. You can use SUPDefaultCallbackHandler as the base class. In your handler, override the particular callback you want to use (for example, onReplaySuccess).

Because both the database and entity handler can be registered, your handler may get called twice for a mobile business object import activity. The callback is executed in the thread that is performing the action. For example, onReplaySuccess is always called from a thread other than the main application thread.

When you receive the callback, the particular activity is already complete.

The SUPCallbackHandler protocol consists of these callbacks:

onReplayFailure:(id)entityObject; – invoked when a replay failure is received from the Unwired Server, whenever a particular device sends a create, update, or delete operation and the operation fails (Unwired Server rejects the requested operation).
onReplaySuccess:(id)entityObject; – invoked when a replay success is received from the Unwired Server, whenever a particular device sends a create, update, or delete operation and the operation succeeds (Unwired Server accepts the requested operation). The onReplaySuccess:(id)entityObject is an MBO object instance that contains the data prior to the synchronization. You can use the Change Log API to find records that occur after the synchronization.
onImport:(id)entityObject; – invoked when an import is received. If the Unwired Server accepts a requested change, it sends one or more import messages to the client, containing data for any created, updated, or deleted row that has changed on the Unwired Server as a result of the replay request. This method is for DOE-based applications only.
onLoginFailure; – invoked when a login failure message is received from the Unwired Server.
onLoginSuccess; – called when a login result is received by the client.
onSubscribeFailure; – invoked when a subscribe failure message is received from the Unwired Server, whenever an object in a subscribed entity changes.
onSubscribeSuccess; – invoked when a subscribe success message is received from the Unwired Server, whenever an object in a subscribed entity changes.
- (int32_t)onSynchronize:(SUPObjectList*)syncGroupList withContext:(SUPSynchronizationContext*)context; – invoked when the synchronization status changes. This method is called by the database class synchronize or beginSynchronize methods when the client initiates a synchronization, and is called again when the server responds to the client that synchronization has finished, or that synchronization failed.
The SUPSynchronizationContext object passed into this method has a “status” attribute that contains the current synchronization status. The possible statuses are defined in the SUPSynchronizationStatusType enum, and include:
- SUPSynchronizationStatus_STARTING – passed in when synchronize or beginSynchronize is called.
- SUPSynchronizationStatus_UPLOADING – synchronization status upload in progress.
- SUPSynchronizationStatus_DOWNLOADING – synchronization status download in progress.
- SUPSynchronizationStatus_FINISHING – synchronization completed successfully.
- SUPSynchronizationStatus_ERROR – synchronization failed.
- SUPSynchronizationStatus_ASYNC_REPLAY_UPLOADED – asynchronous replay has been uploaded.
- SUPSynchronizationStatus_ASYNC_REPLAY_COMPLETED – asynchronous replay has been completed.
- SUPSynchronizationStatus_STARTING_ON_NOTIFICATION – change notification has been received from the server.
For DOE-based applications, only the status values of STARTING, FINISHING, and ERROR are passed into this method.
This callback handler returns SUPSynchronizationActionCONTINUE, unless the user cancels synchronization, in which case it returns SUPSynchronizationActionCANCEL. This code example prints out the groups in a synchronization status change:
```
{
     MBOLogInfo(@"Synchronization response");
     MBOLogInfo(@"================================================="); 
     for(id<SUPSynchronizationGroup> sg in syncGroupList) 
     {
          MBOLogInfo(@"group = %@",sg.name);
     }
     MBOLogInfo(@"================================================="); 
     if(context != nil)
     {
          MBOLogInfo(@"context: %ld, %@",context.status,context.userContext);
     } else {
          MBOLogInfo(@"context is null");
     }
     MBOLogInfo(@"================================================="); 
     return SUPSynchronizationActionCONTINUE;
}
```
onSuspendSubscriptionFailure; – invoked when a call to suspend fails.
onSuspendSubscriptionSuccess; – invoked when a suspend call is successful.
onResumeSubscriptionFailure; – invoked when a resume call fails.
onResumeSubscriptionSuccess; – invoked when a resume call is successful.
onUnsubscribeFailure; – invoked when an unsubscribe call fails.
onUnsubscribeSuccess; – invoked when an unsubscribe call is successful.
onImportSuccess; – invoked when onImport succeeds. This method is for DOE-based applications only.
onMessageException:(NSException*e); – invoked when an exception occurs during message processing. Other callbacks in this interface (whose names begin with "on") are invoked inside a database transaction. If the transaction is rolled back due to an unexpected exception, this operation is called with the exception (before the rollback occurs).
onTransactionCommit; – invoked on transaction commit.
onTransactionRollback; – invoked on transaction rollback.
onResetSuccess; – invoked when reset is successful.
onSubscriptionEnd; – invoked on subscription end. OnSubscriptionEnd can occur when the device is registered, unlike OnUnsubscribeSuccess.
- (void)onMessageStart:(int)size withMethod:(NSString*)method withMbo:(NSString*)mbo; – This method is for DOE-based applications only.
This method is called at the beginning of processing a message from the server, before the message transaction starts. Only the callback handler registered with the package database class is invoked. Parameters:
- size – The size of the incoming message content in bytes.
- method – The method string from the message header.
- mbo – If this message is for a specific MBO, the name of the MBO; otherwise null.

This code example shows how to register a handler to receive a callback:

DBCallbackHandler* handler = [DBCallbackHandler newHandler];
[iPhoneSMTestDB registerCallbackHandler:handler];
[handler release];

MBOCallbackHandler* mboHandler = [MBOCallbackHandler newHandler];
[Product registerCallbackHandler:mboHandler];
[mboHandler release];