Callback Handlers

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, an entity, or both. You can use SUPDefaultCallbackHandler as the base class. In your handler, you override the particular callback that you are interested in (for example, onImport).

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, import). When you receive the callback, the particular activity is already complete.

The SUPCallbackHandler protocol consists of the following callbacks:

onImport:(id)entityObject; – invoked when an import is received.
onReplayFailure:(id)entityObject; – invoked when a replay failure is received from the Unwired Server.
onReplaySuccess:(id)entityObject; – invoked when a replay success is received from the Unwired Server.
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.
onSubscribeSuccess; – invoked when a subscribe success message is received from the Unwired Server.
- (int32_t)onSynchronize:(SUPObjectList*)syncGroupList withContext:(SUPSynchronizationContext*)context; – invoked when the synchronization status changes. This method is called by the database class 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:
- [SUPSynchronizationContextStatus STARTING] – passed in when beginSynchronize is called.
- [SUPSynchronizationStatusContext UPLOADING] – synchronization status upload in progress.
- [SUPSynchronizationStatusContext DOWNLOADING] – synchronization status download in progress.
- [SUPSynchronizationStatusnContext FINISHING] – synchronization completed successfully.
- [SUPSynchronizationStatusContext ERROR] – synchronization failed.
This callback handler returns [SUPSynchronizationAction CONTINUE], unless the user wishes to cancel synchronization, in which case it returns [SUPSynchronizationAction CANCEL]. The following code example prints out the groups in a synchronization status change:
```
- (int32_t)onSynchronize:(SUPObjectList *)syncGroupList withContext :(SUPSynchronizationContext *)context
{
    MBOLogInfo(@"Synchronization response");
    MBOLogInfo(@"=================================================");
    for(id<SUPSynchronizationGroup> sg in syncGroupList)
    {
        MBOLogInfo(@"group = %@",sg.name);
    }
    MBOLogInfo(@"=================================================");
    MBOLogInfo(@"context: %ld, %@",context.status,context.userContext);
    MBOLogInfo(@"=================================================");
    return [SUPSynchronizationAction CONTINUE];
}
```
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; – This method is invoked when an unsubscribe call is successful.
onImportSuccess; – invoked when onImport succeeds.
onTransactionCommit; – invoked on transaction commit.
onTransactionRollback; – invoked on transaction rollback.
onResetSuccess; – invoked when reset is successful.
onSubscriptionEnd; – invoked on subscription end.
onStorageSpaceLow; – invoked when storage space is low.
onStorageSpaceRecovered; – invoked when storage space is recovered.
onConnectionStatusChange:(ConnectionStatus)connStatus:(ConnectionType)connType – the application should call the register callback handler with a database class, and implement the onConnectionStatusChange method in the callback handler. ConnectionStatus and ConnectionType are defined in SUPConnectionUtil.h:

typedef enum {
  WRONG_STATUS_NUM = 0,
  // device connected
  CONNECTED_NUM = 1, 
  // device not connected
  DISCONNECTED_NUM = 2, 
  // device not connected because of flight mode
  DEVICEINFLIGHTMODE_NUM = 3, 
  // device not connected because no network coverage
  DEVICEOUTOFNETWORKCOVERAGE_NUM = 4, 
  // device not connected and waiting to retry a connection
  WAITINGTOCONNECT_NUM = 5,
  // device not connected becauseroaming was set to false 
  // and device is roaming
  DEVICEROAMING_NUM = 6, 
  // device not connected because of low space.
  DEVICELOWSTORAGE_NUM = 7 
} ConnectionStatus;

typedef enum {
  WRONG_TYPE_NUM = 0,
  // iPhone has only one connection type
  ALWAYS_ON_NUM = 1 
} ConnectionType;

The following 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];