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, override the particular callback you want to use (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 these 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 defined in the SUPSynchronizationStatusType enum, and include:
- SUPSynchronizationStatusSTARTING – passed in when beginSynchronize is called.
- SUPSynchronizationStatusUPLOADING – synchronization status upload in progress.
- SUPSynchronizationStatusDOWNLOADING – synchronization status download in progress.
- SUPSynchronizationStatusFINISHING – synchronization completed successfully.
- SUPSynchronizationStatusERROR – synchronization failed.
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.
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.
onStorageSpaceLow; – invoked when storage space is low.
onStorageSpaceRecovered; – invoked when storage space is recovered.
onConnectionStatusChange:(SUPDeviceConnectionStatus)connStatus:(SUPDeviceConnectionType)connType:(int32_t)errCode:(NSString*)errString; – the application should call the register callback handler with a database class, and implement the onConnectionStatusChange method in the callback handler. The API allows the device application to see what the error is in cases where the client cannot connect to the Unwired Server. SUPDeviceConnectionStatus and SUPDeviceConnectionType 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 
} SUPDeviceConnectionStatus;

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

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