registerApplication:timeout

Creates the registration for this application and starts the connection. An ApplicationTimeoutException is thrown if the method does not succeed within the number of seconds specified by the timeout.

If an application identifier has not already been set, a SUPPersistanceException is thrown. If connection properties are not available, a SUPConnectionPropertyException is thrown. If the timeout is greater than 0 and the registration takes longer than the timeout, then a SUPApplicationTimeoutException is thrown, even though the process will continue in the background. If you use this method, do not call startConnection.

If a callback handler is registered and network connectivity is available, the sequence of callbacks as a result of calling registerApplication is:

onRegistrationStatusChanged(RegistrationStatus.REGISTERING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTED, 0, "")
onRegistrationStatusChanged(RegistrationStatus.REGISTERED, 0, "")

When the connectionStatus of CONNECTED has been reached and the application's applicationSettings have been received from the server, the application is now in a suitable state for database subscriptions and/or synchronization. If a callback handler is registered and network connectivity is unavailable, the sequence of callbacks as a result of calling registerApplication is:

onRegistrationStatusChanged(RegistrationStatus.REGISTERING, 0, "")
onRegistrationStatusChanged(RegistrationStatus.REGISTRATION_ERROR, code, message)

In such a case, the registration process has permanently failed and will not continue in the background. If a callback handler is registered and network connectivity is available for the start of registration but becomes unavailable before the connection is established, the sequence of callbacks as a result of calling registerApplication is:

onRegistrationStatusChanged(RegistrationStatus.REGISTERING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTION_ERROR, code, message)

In such a case, the registration process has temporarily failed and will continue in the background when network connectivity is restored.

As a best practice, if a timeout exception occurs in registerApplication or startConnection, the application should wait for the appropriate callback, and optionally add a user message to the application, "please wait" for example, instead of closing the application. This prevents a build up of start up requests by needlessly restarting the application which can adversely affect performance.

Wait for the application callback, such as onConnectionStatusChanged() if ApplicationTimeoutException is encountered when calling registerApplication:timeout , instead of closing the application. This allows the application code to catch ApplicationTimeoutException and does not throw an exception.

Syntax

- (void)registerApplication :(SUPInt)timeout;

Parameters

timeout – Number of seconds to wait until the registration is created. If the the timeout is greater than zero and the registration is not created within the timeout period, an ApplicationTimeoutException is thrown (the operation might still be completing in a background thread). If the timeout value is less than or equal to 0, then this method returns immediately without waiting for the registration to finish (a non-blocking call). If the timeout value is less than or equal to 0, then this method returns immediately without waiting for the registration to finish (a non-blocking call).

Examples

Register an Application – Registers the application with a one minute waiting period.
```
[app registerApplication:60];
```

Usage

You must set up the ConnectionProperties and ApplicationIdentifier before you can invoke registerApplication.

The maximum length of the Application ID is 64 characters. The total length of the Application Connection ID cannot exceeds 128 characters. The Application Connection ID format is deviceId__applicationId. The applicationId separator is two underscores.

SUPApplication* app = [SUPApplication getInstance];
[app setApplicationIdentifier:@"SMP101"];

MyApplicationCallbackHandler *ch = [MyApplicationCallbackHandler getInstance];
[ch retain]; 
[app setApplicationCallback:ch];

SUPConnectionProperties* props = app.connectionProperties;
[props setServerName:@"server.mycompany.com"];
[props setPortNumber:5001];

SUPLoginCredentials* login = [SUPLoginCredentials getInstance];
login.username = @"supAdmin";
login.password = @"supPwd";
props.loginCredentials = login;

if ([app registrationStatus] != SUPRegistrationStatus_REGISTERED && 
[app registrationStatus] != SUPRegistrationStatus_REGISTERING ) 
{
[app registerApplication:120]; // 120 second timeout for registration
}