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.

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.

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

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

SUPConnectionProperties* props = app.connectionProperties;
[props setServerName:@"supserver.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
}