Callback Handlers

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, onImport 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:

• onImport:(id)entityObject; – invoked when an import is received. If 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.
• 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).
• 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 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. OnSubscriptionEnd can occur when the device is registered, unlike OnUnsubscribeSuccess.
• 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];