GDiOS Class Reference

BlackBerry Dynamics Runtime object interface, including authorization. More...

#import <BlackBerryDynamic/GD/GDiOS.h>

Description

This class represents the application's connection to its embedded BlackBerry Dynamics runtime instance, and hence to the wider BlackBerry Dynamics platform infrastructure.

The programming interface includes a number of functions that the application must call at particular points in the application execution cycle. The application must also implement a handler for events dispatched from this interface. Calling the functions, and handling the events correctly, ensures compliance with enterprise security policies. This programming interface also includes a number of miscellaneous functions for various purposes, such as setting a custom logo for display in the BlackBerry Dynamics user interface.

The application must initialize the runtime object, using this programming interface, prior to using any other BlackBerry Dynamics interface. Initialization will only succeed if the end user has been set up in the enterprise BlackBerry Dynamics management console, and is entitled to use the application.

The user's entitlement to the application may later be revoked or temporarily withdrawn. For example, temporary withdrawal may take place if the user is inactive for a period of time. In either case, the application will be notified with an event or callback from this interface.

Successful initialization of the BlackBerry Dynamics interface object also makes the BlackBerry Dynamics proxy infrastructure accessible from within the URL Loading System, which includes the native URL session programming interface.

See also

System administration tasks

Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.

Thread support statement

Background Execution

GDURLLoadingSystem for proxy infrastructure usage within the URL Loading System.

NSURLSession Support for proxy infrastructure usage through the native URL session programming interface.

BlackBerry Dynamics Platform Connection

Establishing a connection to the BlackBerry Dynamics platform requires authorization of the end user, and of the application. Both authorizations are initiated by a single call to the authorize function.

The authorize function call is typically made when the application starts, in the application:didFinishLaunchingWithOptions: handler.

Authorization generally includes establishing a data connection to the BlackBerry Dynamics proxy infrastructure, and hence to the enterprise that set up the end user entitlement. In addition, authorization will also include any necessary registration of the device, at the BlackBerry Dynamics Network Operation Center (infrastructure activation), and at the enterprise (enterprise activation). See under Activation, below, for more details.

Authorization may include user interaction, see the documentation of the authorize function, below, for details. All user interaction that is part of authorization takes place in a user interface that is built into the BlackBerry Dynamics runtime library, not part of the application.

The authorization programming interface is state-based and asynchronous. The initiation function generally returns immediately. Success or failure of authorization is then notified to the application code later, as a transition of the authorization state. The application should generally wait to be notified of transition to the "authorized" state before attempting to utilize any other BlackBerry Dynamics interfaces.

Further changes to the authorization state can take place, and are notified to the application in the same way. See under Authorization State, below.

See also

Enterprise Simulation mode for instructions on building an application to run in a special limited mode in which authorization with the enterprise is only simulated.

Network Operation Center server addresses on the application developer portal, for IP address and port number details of the BlackBerry Dynamics Network Operation Center services.

Authorization State

The BlackBerry Dynamics runtime maintains the authorization state of the application. The programming interfaces that can be utilized by the application depend on its current authorization state.

The initial state of the application when it starts is not authorized. In this state the application can utilize the authorization processing initiation interface but cannot utilize any principal interfaces, such as secure store access and secure communication.

After authorization has been initiated and has succeeded, the application enters the authorized state. The principal interfaces can then be utilized.

Authorization of the end user may be temporarily withdrawn, in which case the application enters the locked state. This would happen when, for example, the user doesn't interact with the application for an extended period and the enterprise inactivity time out expires. Note that the authorization of the application itself has not been withdrawn in this state, only the authorization of the end user to access the application's data.
In the locked state, the BlackBerry Dynamics runtime superimposes an unlock screen on the application user interface to prevent the user from interacting with it or viewing its data. Note that the runtime doesn't block the whole device user interface, which means that native notification features and other ancillary mechanisms could still be utilized by the application. The application mustn't cause sensitive enterprise data to be displayed through these features and mechanisms when in the locked state.
The application can continue to utilize the principal BlackBerry Dynamics interfaces, in the background.

After a temporary withdrawal ends, the application returns to the authorized state. This would happen when, for example, the user enters their security password in the unlock screen.

Authorization may also be permanently withdrawn, in which case the application enters the wiped state. This would happen when, for example, the end user's entitlement to the application is removed by the enterprise administrator. In the wiped state, the application cannot utilize the principal BlackBerry Dynamics interfaces.

Transitions of the authorization state are notified as follows.

• A GDAppEvent is dispatched to the GDiOSDelegate instance in the application. The event will have a number of attributes, including a type value that indicates whether the user is now authorized.
• A GDStateChangeNotification is posted to any registered NSNotification observers. See the GDState class reference for how to register.
• The isAuthorized property of the state (GDiOS) object changes value, which can be notified by key-value observing (KVO). See again the GDState class reference for details.

The authorization states and their corresponding event type values are listed in the following table.

State	Description	GDAppEvent type value
Not authorized	Initial state. The application can initiate authorization, but cannot utilize the principal interfaces.
Authorized	Either the user has just been authorized to access the application, following authorization processing, or a condition that caused authorization to be withdrawn has been cleared. The application can utilize the principal interfaces.	GDAppEventAuthorized
Locked	Authorization of the user has been temporarily withdrawn, for example due to inactivity. User interaction is blocked. The application can still utilize the principal interfaces.	GDAppEventNotAuthorized
Wiped	Authorization of the user has been permanently withdrawn, for example due to violation of an enterprise policy for which the enforcement action is to wipe the secure container. The application cannot use any interfaces.	GDAppEventNotAuthorized This is the same event type as the Locked state transition event.

The transitions in the above table are also shown in the Authorization state transition diagram.

The BlackBerry Dynamics runtime user interface includes all the necessary screens and messages to inform the user of the authorization state. The application code needs only to ensure:

• That it doesn't bypass the runtime user interface.
• That it doesn't attempt to access the principal interfaces prior to authorization.
• That it doesn't attempt to access the principal interfaces after the authorization state has changed to wiped.

An authorized application may change an authorization state to 'locked' and prompt the user to reauthenticate by using GDAuthenticationManager .

Programming interface restrictions

The application cannot use any of the principal BlackBerry Dynamics interfaces before authorization has succeeded. If the application attempts to do so, the runtime generates an assertion, which results in the application being terminated. The runtime uses the Foundation NSAssert macro to generate these assertions.

The runtime doesn't generate assertions for transient conditions, but only for apparent programming errors in the application. Consequently, these assertions are only expected when the application is in development, and not when the application is in production. The failure message of the assertion will describe the programming error.

The recommended approach is that the application should be allowed to terminate, so that the failure message can be read on the console. The failure message will describe the programming error, which can then be corrected. For example, a message like the following could be seen in the logs:
My application [7506:40b] *** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Not authorized. Call [GDiOS authorize] first.'

First usage of BlackBerry Dynamics in the execution cycle

The typical first usage of the BlackBerry Dynamics programming interface in the execution cycle is to initiate authorization, in the application:didFinishLaunchingWithOptions: handler. The first point in the execution cycle at which it is possible to use the BlackBerry Dynamics interface is the invocation of the application:willFinishLaunchingWithOptions: handler. The BlackBerry Dynamics programming interface cannot be used prior to application:willFinishLaunchingWithOptions: invocation. For example, if the application uses a subclass of UIApplication, the BlackBerry Dynamics programming interface cannot be used in its init method.

Activation

In BlackBerry Dynamics, activation refers to a number of registration procedures that must be completed in order to access all platform capabilities. Once a particular activation has been completed, registration credentials are stored on the device. This means that each activation need only be processed once.

Activations are generally transparent to the application. The application will call a BlackBerry Dynamics authorization method, and the runtime will process whichever activations are required.

There are two activations in BlackBerry Dynamics.

Infrastructure activation

Recognition of the application instance as a terminal by the BlackBerry Dynamics central server.

Enterprise activation

Association of the terminal with a provisioned end user at the enterprise. This requires activation credentials, which may be obtained by any of the following means.

• Entered manually into the BlackBerry Dynamics user interface.
• Retrieved progammatically via another BlackBerry Dynamics application, known as Easy Activation. .

See also

System administration tasks.

Enterprise Simulation mode for instructions on building an application to run in a special limited mode in which there is no enterprise activation.

Identification

Every BlackBerry Dynamics application has a unique identifier and version for the purposes of entitlement management, publishing, and service provider registration. The identifier was previously referred to as the Good Dynamics application identifier, or in the abbreviated form GD App ID, but is now referred to as the entitlement identifier.

Entitlement identifiers are used:

• In the application.
• In the BlackBerry Dynamics management console at the enterprise.
• In some administrative user interfaces accessible via the application developer portal.

A BlackBerry Dynamics entitlement identifier is generally accompanied by a separate entitlement version.

In the mobile application, the entitlement identifier and version values are set by the authorization call, as documented in the authorize function reference, below. In the management console, the entitlement identifier and version values are entered as part of application management.

See also

System administration tasks.

Entitlement Identifier Format

Entitlement identifiers are textual and follow a typical naming convention. The reversed Internet domain of the application developer forms the initial part of the identifier. For example, applications developed by BlackBerry can have identifiers that begin "com.blackberry." because BlackBerry owns the blackberry.com Internet domain.

The rest of the identifier is made up of the application's name, possibly preceded by a number of categories and sub-categories. Categories and sub-categories are separated by full stops. For example, the identifier of an example remote database application, made by BlackBerry, could be: "com.blackberry.gd.examples.remotedb". Note that BlackBerry also owns the good.com domain, so could also use "com.good.gd.examples.remotedb".

Formally, the syntax of an entitlement identifer is a string that:

• Contains only the following ASCII characters: hyphen (dash), full stop (period), numeric digit, lower-case letter.
• Conforms to the <subdomain> format initially defined in section 2.3.1 of RFC1035 and subsequently modified in section 2.1 of RFC1123.

Entitlement Version Format

A BlackBerry Dynamics entitlement version is a string made up of a sequence of numbers separated by full stops (periods). The following represents best practice.

• The first release of the application should have "1.0.0.0" as its entitlement version.
• The version string should change in subsequent releases in which one of the following software changes is made:
  • The application starts to provide a new shared service or shared service version.
  • The application stops providing a shared service or shared service version.
  Otherwise, version should not change in the release.

See the GDService class reference for details of shared services.

The syntax rules of entitlement version values are as follows.

• A version string consists of one to four version numbers separated by full stop (period) characters.
• A version number consists of one of the following:
  • A single zero.
  • A sequence of up to three digits with no leading zero.

The syntax can be formally expressed as the following regular expression: (0|[1-9][0-9]{0,2})(.(0|[1-9][0-9]{0,2})){0,3}

Don't use a different entitlement version for an early access or beta software release. Instead, add a suffix to the BlackBerry Dynamics entitlement identifier and native application identifier used for general access. For example, the entitlement identifier "com.example.gdapp.beta" could be used to identify a "com.example.gdapp" beta release.
Using a different native identifier makes it possible for general access and early access software to be installed on the same mobile device, and facilitates use of different signing certificates.

Application user interface restrictions

See the Application User Interface Restrictions page.

Build-Time Configuration

See the Build-Time Configuration page.

Enterprise Configuration Information

There are a number of functions in this class for obtaining enterprise configuration information, including settings that apply to the current end user. The getApplicationPolicy (GDiOS) and getApplicationConfig (GDiOS) functions are examples of this type of function.

All the functions of this type:

• Return their results in a collection of objects.
• Have a corresponding GDAppEvent event type that is dispatched to the application's GDiOSDelegate instance when the result would change.
• Have a corresponding NSNotification that is posted to any registered observers, when the result would change. See the GDState class reference for how to register.

For example, the getApplicationPolicy (GDiOS) function returns an NSDictionary collection. When there is a change, a GDPolicyUpdateNotification is posted, and a GDAppEventPolicyUpdate event is dispatched.

Use these functions as follows.

1. Make a first call to get an initial collection.
2. Retain the collection, and refer to it in any code that utilizes its values.
3. When the update event is received, discard the retained collection and call the function again to get a new collection.

Don't make a subsequent call to the same function until an update event has been received. The BlackBerry Dynamics runtime generates a new collection for each call to one of these functions. If the application code makes multiple calls and retains all the returned collections, then they will all consume memory or other application resources.

Code Snippets

The following code snippets illustrate some common tasks.

Authorization

The following snippet shows initiation of BlackBerry Dynamics authorization.

[GDiOS sharedInstance].delegate = self;
[[GDiOS sharedInstance] authorize];

After executing the above code, the application would wait for its delegate callback to be invoked. The invocation would have an event type of GDAppEventAuthorized if the user was authorized. After that, the application could make full use of all BlackBerry Dynamics capabilities.

The above code relies on the identification parameters being in the Info.plist file, as shown in the following snippet.

<key>GDApplicationID</key>
<string>com.example.browser</string>
<key>GDApplicationVersion</key>
<string>1.0.0.0</string>

The above is an extract from the XML of the application's Info.plist file. The extract sets "com.example.browser" as the BlackBerry Dynamics entitlement identifer, and "1.0.0.0" as the BlackBerry Dynamics entitlement version.

User interface pre-initialization

The following snippet shows some necessary steps that precede initialization of the application's user interface. The recommended place in the code for these steps is as shown in the snippet.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ 
    GDiOS *gdiOS = [GDiOS sharedInstance];
    gdiOS.delegate = self;
    started = NO;
    // Following line will cause the BlackBerry Dynamics user interface to open.
    [gdiOS authorize];
    return YES;
}

The above snippet shows the following sequence of actions.

1. A reference to the GDiOS singleton object is obtained.
2. The current class is set as the delegated event handler.
3. The started flag is set, to control initialization of the application's user interface, which is covered in the following snippet. The flag's declaration (not shown) would be BOOL.
4. The application initiates BlackBerry Dynamics authorization.

Authorization processing is asynchronous. On completion, an event will be dispatched to the application's handler. The application completes user interface initialization within its event handler, as shown in the following code snippet.

User interface initialization

The following snippet shows the recommended place in the code to initialize the application's user interface.

-(void)handleEvent:(GDAppEvent*)anEvent
{
    switch (anEvent.type) {
        case GDAppEventAuthorized: {
            if (!started) {
                [self initializeUI];
                started = YES;
            }
            break;
        }
 
        case GDAppEventNotAuthorized: {
            [self onNotAuthorized:anEvent];
            break;
        }
 
        case GDAppEventRemoteSettingsUpdate:
        case GDAppEventServicesUpdate:
        case GDAppEventPolicyUpdate:
        default: {
            // This application ignores other types of event.
            break;
        }
    }
}

The above code shows a simple BlackBerry Dynamics runtime event handler.

The handler calls the application's own initializeUI function when a GDAppEventAuthorized event is received for the first time. The application's started flag is used to control first-time execution. Initialization of this flag is shown in the previous snippet.
The initializeUI function would complete user interface initialization, utilizing a reference to the BlackBerry Dynamics runtime UIWindow. This reference can be obtained using the window property from the main app delegate.

The handler calls the application's own onNotAuthorized function whenever a GDAppEventNotAuthorized event is received.

Public Types
typedef NSString *	ActivationParameter
	String constants used as keys for programmatic activation parameters. More...
typedef void(^	GDGetEntitlementVersionsForBlock) (NSArray< GDVersion * > *_Nullable entitlementVersions, NSError *error)
	Type for getEntitlementsFor block parameter. More...

Instance Methods
(void)	- authorize:
	Connect to the BlackBerry Dynamics infrastructure. More...
(void)	- authorize
	Connect to the BlackBerry Dynamics infrastructure, without specifying a delegate. More...
(BOOL)	- authorizeAutonomously:
	Connect to the BlackBerry Dynamics infrastructure in background. More...
(BOOL)	- authorizeAutonomously
	Connect to the BlackBerry Dynamics infrastructure in background, without specifying a delegate. More...
(GDAuthDelegateInfo *)	- getAuthDelegate
	Get a pointer to the GDAuthDelegateInfo structure. More...
(void)	- programmaticAuthorize:
	Initiate programmatic activation. More...
(void)	- programmaticAuthorize:withAccessKey:
	Initiate programmatic activation (deprecated). More...
(void)	- programmaticAuthorize:withAccessKey:networkOperationCenter:
	Initiate programmatic activation by a specific Network Operation Center (deprecated). More...
(NSDictionary< NSString *, id > *)	- getApplicationConfig
	Get application configuration and other settings from the enterprise. More...
(NSDictionary< NSString *, id > *)	- getApplicationPolicy
	Get application-specific policy settings from the enterprise management console, as a collection. More...
(NSString *)	- getApplicationPolicyString
	Get application-specific policy settings from the enterprise management console, as JSON. More...
(NSArray< GDServiceProvider * > *)	- getServiceProviders
	Get providers of shared services. More...
(NSArray< GDServiceProvider * > *)	- getServiceProvidersFor:andVersion:andServiceType:
	Discover providers of a specific shared service. More...
(void)	- getEntitlementVersionsFor:callbackBlock:
	Check whether the end user has a particular entitlement. More...
(UIWindow *)	- getWindow
	Get the UIWindow for the application (deprecated). More...
(NSString *)	- getVersion
	Get the BlackBerry Dynamics runtime library version. More...
(BOOL)	- showPreferenceUI:
	Open the BlackBerry Dynamics preferences user interface to change password. More...
(void)	- configureUIWithLogo:bundle:color:
	Configure the visual appearance of the BlackBerry Dynamics user interface. More...
(BOOL)	- executeRemoteLock
	Lock the application permanently. More...
(void)	- executeBlock:withTitle:withMessage:
	Blocks application locally with defined blockId. More...
(void)	- executeUnblock:
	Unblocks application locally with defined blockId. More...
(BOOL)	- executePendingConsoleMigration:withUemServerAddress:
	Executes migration of the application to a different management console. More...
(GTLauncherViewController *)	- getManagedLauncherViewController
	Returns the GTLauncherViewController being managed by BlackBerry Dynamics, if any. More...

Class Methods
(instancetype)	+ sharedInstance
	Get a reference to the runtime interface object. More...

Public Attributes
const ActivationParameter	ActivationParameterUserIdentifier
const ActivationParameter	ActivationParameterAccessKey
const ActivationParameter	ActivationParameterNOCAddress
const ActivationParameter	ActivationParameterShowUserInterface
const ActivationParameter	ActivationParameterEnrollmentAddress
const ActivationParameter	ActivationParameterPassword

Properties
BOOL	activationComplete
	Application activation status. More...
id< GDiOSDelegate >	delegate
	Delegated event-handling. More...
BOOL	canAuthorizeAutonomously
	Whether it is possible to authorize autonomously. More...
GDState *	state
	Observable representation of authorization state and user interface state. More...

Member Typedef Documentation

ActivationParameter

- (typedef NSString*) ActivationParameter

Keys used to set the values of the activation parameters required during programmatic activation.

Key Constant	Setting	Type
ActivationParameterUserIdentifier	NSString containing the first enterprise activation credential: the user identifier. This is typically the enterprise email address of the end user.	NSString
ActivationParameterAccessKey	NSString containing the second enterprise activation credential: the access key. Using an Access Key instead of Activation Password is recommend.	NSString *
ActivationParameterPassword	NSString containing the activation password in the case an Access Key cannot be obtained. For example the activation email contains a QR code.	NSString
ActivationParameterNOCAddress	NSURL containing a NOC server address, or an alias. The URL must always include a scheme, such as https.	NSURL
ActivationParameterShowUserInterface	Boolean value which if set to false, will prevent the BlackBerry Dynamics runtime activation UI from being shown during activation.	NSNumber

GDiOS::programmaticAuthorize:

GDGetEntitlementVersionsForBlock

- (typedef void(^ GDGetEntitlementVersionsForBlock(NSArray< GDVersion * > *_Nullable entitlementVersions, NSError *error))

Pass a code block of this type as the block parameter to the getEntitlementVersionsFor: function.

The block receives the following parameters.

Parameters

entitlementVersions	NSArray of GDVersion objects representing the versions of the entitlement to which the end user is entitled if the original call succeeded, or nil otherwise.
error	NSError containing a description of the error condition if the original call failed, or nil otherwise.

Method Documentation

sharedInstance

+ (instancetype) sharedInstance

This function returns a reference to the BlackBerry Dynamics runtime object. This function can be called in the application:didFinishLaunchingWithOptions: handler of the application.

The BlackBerry Dynamics runtime object is a "singleton class".

Returns

Reference that can be used to call, for example,authorize (GDiOS) .

authorize:

- (void) authorize:

(id< GDiOSDelegate > _Nonnull)

delegate

Call this function to initiate BlackBerry Dynamics authorization processing.

Authorization involves a number of exchanges with various servers in the BlackBerry Dynamics proxy infrastructure, and may involve user interaction. The following processing items are the most significant.

Infrastructure activation

The BlackBerry Dynamics runtime registers the application instance as a terminal with the BlackBerry Dynamics Network Operation Center (NOC). The NOC issues registration credentials, which are encrypted and stored locally by the runtime. Infrastructure activation is not processed if registration credentials are already present.

Enterprise activation

Enterprise activation is the completion of the enterprise provisioning process. An access key will have been created by the enterprise management console, and made available to the runtime instance embedded in the application. See under Activation, above, for the methods by which the key can be made available.

During enterprise activation, the runtime sends the key to the NOC. If the key is recognized, the application instance is associated with the enterprise that created the key. Enterprise registration credentials are then issued, and encrypted and stored locally by the runtime.
Enterprise activation is not processed if enterprise registration credentials are already present.
Note that successful enterprise activation has the effect of consuming the access key. This will be the case even if a later stage of authorization processing fails, or if it is found that the user isn't entitled to this application.

Entitlement checking

The enterprise that provisioned the end user can later withdraw the user's entitlement to the application. Withdrawal is flagged in the enterprise's management console. The runtime checks the end user's ongoing entitlement to the application every time authorization is processed. (In addition, withdrawal may be notified to the runtime by the NOC.)
In the management console, entitlement is given to particular versions of particular applications. The entitlement version and identifier values built into the application must match exactly with a version and identifier to which the user has been given entitlement in the management console. If there isn't an exact match, then user entitlement is assumed to have been withdrawn.
If the user is found not to be entitled, then the runtime deletes all locally stored application data and authentication credentials.

Policy update

Policies govern many aspects of the BlackBerry Dynamics user experience. For example, the minimum characteristics of the end user's security password with respect to length and types of character are governed by a policy. So is the need for the end user to set a security password. The runtime checks for and retrieves updated policies every time authorization is processed.

Policy checking

The runtime checks for compliance with the most up-to-date policies every time authorization is processed.

Configuration retrieval

The runtime retrieves a set of application configuration settings from the enterprise management console during authorization processing. These will have been stored in the management console. See under getApplicationConfig (GDiOS) for a list of settings.

Unlock secure store

The BlackBerry Dynamics secure store is unlocked during authorization. If the store is protected by an end-user password, then the user must enter their password for authorization processing to complete. Password entry takes place in a BlackBerry Dynamics user interface, not in the application user interface.

Note that BlackBerry Dynamics user interfaces mentioned in the above, such as Enterprise activation and Password entry, are opened and closed as needed, without reference to the application.

This function can be called in the application:didFinishLaunchingWithOptions: handler of the application.

This function must be called before any of the principal BlackBerry Dynamics functions.

Data communication during authorization processing doesn't go via the proxy specified in the device's native settings, if any.

Parameters

delegate

Reference to the delegated event handler, typically self.

Application identification parameters will be read from the following properties in the application Info.plist file:

Key	Type	Value
GDApplicationID	String	BlackBerry Dynamics entitlement identifier. (This identifier was previously referred to as the Good Dynamics application identifier, or in the abbreviated form GD App ID.) This identifier is used to control access to the application by end users, and to configure its application server connections. The value passed must be the same as the value present in the enterprise management console. (Note that the value needn't be the same as the native application identifier.) For syntax details see under Entitlement Identifier Format, above.
GDApplicationVersion	String	BlackBerry Dynamics entitlement version number The version number can be combined with the entitlement identifier, above, to control access to particular versions of the application.

(In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The settings should appear there.)

Authorization is asynchronous. When authorization processing completes:

• The delegate handleEvent callback is invoked.
• The GDState singleton object is updated, and any observers of that object are sent notifications.

See also

System administration tasks

Enterprise Simulation mode.

authorize

- (void) authorize

Call this function to initiate BlackBerry Dynamics authorization processing without specifying a delegated event handler. This style of call can be used in the following cases.

• The delegate property has already been set directly, to a GDiOSDelegate implementation.
• The application uses the GDState interface to monitor authorization state, doesn't implement GDiOSDelegate, and has switched off the event receiver check. (Instructions for switching off are on the Build-Time Configuration page, under the Event Receiver Check heading.)

Calling this function is otherwise equivalent to calling the authorize: function, above. See authorize (GDiOS) for details.

authorizeAutonomously:

- (BOOL) authorizeAutonomously:

(id< GDiOSDelegate > _Nonnull)

delegate

Call this function to initiate BlackBerry Dynamics authorization processing in background.

This function should be called when the application is launched in background. This could happen if any of the following are in use.

• Apple Push Notification Service (APNS).
• Background fetch.

Authorization processing can complete in background, if all the following conditions are met:

• Activation has completed. The application must have run in foreground and completed BlackBerry Dynamics authorization processing at least once for this to be the case.
• Authorization can complete autonomously, without user interaction, i.e. a no-password enterprise policy is in effect for the current end user.
• The application is currently in background.

Call this function from any callback that handles background launch, for example the application didReceiveRemoteNotification: or performFetchWithCompletionHandler: function. Access the canAuthorizeAutonomously (GDiOS) property first, to check that a no-password policy applies to the current end user and that autonomous authorization is possible.

If authorization can complete autonomously, calling this function results in the same processing and notification as if authorize (GDiOS) had been called. Application identification parameters will be read from the Info.plist file.

Parameters

delegate

Reference to the delegated event handler, typically self.

Returns

YES if authorization can complete autonomously. The application will be notified when authorization completes, or if it fails for some reason.

NO if authorization cannot complete autonomously. No further notification will be dispatched.

authorizeAutonomously

- (BOOL) authorizeAutonomously

Call this function to initiate autonomous BlackBerry Dynamics authorization processing without specifying a delegated event handler. This style of call can be used in the same cases as the authorize (GDiOS) function that takes no parameters, see above.

Calling this function is otherwise equivalent to calling the authorizeAutonomously: function, above.

See authorizeAutonomously: (GDiOS) for details.

getAuthDelegate

- (GDAuthDelegateInfo*) getAuthDelegate

Get a pointer to the GDAuthDelegateInfo structure. Non-Null. If there is no auth delegate application, isAuthenticationDelegated within structure will be NO.

programmaticAuthorize:

- (void) programmaticAuthorize:

(NSDictionary< ActivationParameter, id > *)

activationParameters

Call this function to initiate programmatic activation. Programmatic activation can only be utilized by applications that can obtain credentials for enterprise activation on behalf of the end user. The credentials are passed as parameters to this function. The credentials must already have been generated, by an enterprise BlackBerry Dynamics management console, prior to this function being called.

Activation requires processing on the BlackBerry Dynamics Network Operation Center (NOC). From an architectural point-of-view, there is a single NOC for all BlackBerry Dynamics enterprises and users. For practical reasons, however, there may actually be a number of NOC deployments. For example, there may be separate production and development deployments. The application can specify which NOC is to process programmatic activation, in the nocAddress parameter to this function.

Calling this function also initiates authorization processing, as if the authorize (GDiOS) function had been called.

Only call this function after checking that the application is not already activated, by accessing the activationComplete (GDiOS) property.

Parameters

activationParameters

NSDictionary object containing configuration values. Use the ActivationParameter string constants as keys.

programmaticAuthorize:withAccessKey:

- (void) programmaticAuthorize:		(NSString *)	userID
withAccessKey:		(NSString *)	accessKey

Deprecated:

This function is deprecated and will be removed in a future release. Use GDiOS::programmaticAuthorize: instead.

Calling this function is equivalent to calling the form with an additional URL parameter, see below, and specifying the URL of the default production Network Operation Center.

programmaticAuthorize:withAccessKey:networkOperationCenter:

- (void) programmaticAuthorize:		(NSString *)	userID
withAccessKey:		(NSString *)	accessKey
networkOperationCenter:		(NSURL *)	nocAddress

Deprecated:

This function is deprecated and will be removed in a future release. Use GDiOS::programmaticAuthorize: instead.

Call this function to initiate programmatic activation. Programmatic activation can only be utilized by applications that can obtain credentials for enterprise activation on behalf of the end user. The credentials are passed as parameters to this function. The credentials must already have been generated, by an enterprise BlackBerry Dynamics management console, prior to this function being called.

Activation requires processing on the BlackBerry Dynamics Network Operation Center (NOC). From an architectural point-of-view, there is a single NOC for all BlackBerry Dynamics enterprises and users. For practical reasons, however, there may actually be a number of NOC deployments. For example, there may be separate production and development deployments. The application can specify which NOC is to process programmatic activation, in the nocAddress parameter to this function.

Calling this function also initiates authorization processing, as if the authorize (GDiOS) function had been called.

Only call this function after checking that the application is not already activated, by accessing the activationComplete (GDiOS) property.

Parameters

userID	NSString containing the first enterprise activation credential: the user identifier. This is typically the enterprise email address of the end user.
accessKey	NSString containing the second enterprise activation credential: the access key.
nocAddress	NSURL containing a NOC server address, or an alias. The URL must always include a scheme, such as https.

getApplicationConfig

- (NSDictionary<NSString *, id> *) getApplicationConfig

This function returns a collection of application configuration and other settings. The settings will have been made in the enterprise management console, and retrieved by the BlackBerry Dynamics runtime.

Retrieval of configuration settings may happen during authorization processing, or whenever settings are changed. When changed settings have been retrieved by the runtime, a GDAppEventRemoteSettingsUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Note that retrieval isn't as such triggered by calling this function.

Returns

NSDictionary object containing configuration values. Use the GDAppConfigKey constant strings as keys.

Any of the following configuration settings may be present.

Key Constant	Setting	Type
GDAppConfigKeyServers	Application server configuration. A number of servers can be configured for an application, in the management console. See the GDAppServer class reference for documentation of the details that are returned for each configured server.	NSArray of GDAppServer
GDAppConfigKeyConfig	Application-specific configuration data. As well as the application server details, above, a free text can also be entered in the management console. Whatever was entered is passed through by the runtime and made available to the application code here.	NSString
GDAppConfigKeyPreventDataLeakageOut	Outbound Data Leakage policy indicator. 1 means that enterprise security policies require that the end user must be prevented from taking any action that is classified as data loss or data leakage in the BlackBerry Dynamics Security Compliance Requirements document. 0 means that the above policy isn't in effect, so the user is permitted to take those actions.	NSNumber
GDAppConfigKeyPreventDataLeakageIn	Inbound Data Leakage policy indicator. 1 means that enterprise security policies require that the end user must be prevented from copying into the application data that originates from elsewhere than another BlackBerry Dynamics application activated by the same end user on the same device or computer. 0 means that the above policy isn't in effect, so the user is permitted to copy in data from any other application.	NSNumber
GDAppConfigKeyPreventDictation	Dictation Prevention policy indicator. 1 means that enterprise security policies require that the end user must be prevented from using dictation as a form of input. 0 means that the above policy isn't in effect, so the user is permitted to use dictation. This setting is included for completeness. The policy is generally enforced by the BlackBerry Dynamics runtime without reference to the application code.	NSNumber *
GDAppConfigKeyPreventScreenRecording	Screen Recording policy indicator. 1 means that enterprise security policies require that the end user must be prevented from recording or sharing their screen. 0 means that the above policy isn't in effect, so the user is permitted to record or share their screen. This setting is included for completeness. The policy is generally enforced by the BlackBerry Dynamics runtime without reference to the application code.	NSNumber
GDAppConfigKeyPreventCustomKeyboards	Custom Keyboard Prevention policy indicator. 1 means that enterprise security policies require that the end user must be prevented from using custom keyboards. 0 means that the above policy isn't in effect, so the user is permitted to use custom keyboards. This setting is included for completeness. The policy is generally enforced by the BlackBerry Dynamics runtime without reference to the application code.	NSNumber
GDAppConfigKeyDetailedLogsOn	Logging level. 0 means that the logging level is low, and only minimal logs should be written. 1 means that the logging level is high, and detailed logs should be written. Detailed logs facilitate debugging of issues encountered at run time. The BlackBerry Dynamics runtime will automatically adjust its logging according to the configured setting. The setting is present in the programming interface so that the application can adjust its logging consistently with the runtime.	NSNumber
GDAppConfigKeyPreventUserDetailedLogs	User detailed logging block indicator. 1 if the end user is blocked from switching on detailed logging, 0 otherwise. Use this configuration key to determine whether to offer the end user an option to switch on detailed logging. Only offer the end user an option to switch on detailed logging if it isn't blocked by policy. See GDLogManager for how to switch on detailed logging from the application code.	NSNumber
GDAppConfigKeyUserId	Enterprise user identifier, typically email address. An enterprise identifier for the end user is one of the credentials required for activation of BlackBerry Dynamics application. This could be the email address entered in the activation user interface when the application was run for the first time, for example. The value obtained for this setting will initially be the enterprise email address, or other identifier, used for activation. If the enterprise email address of the end user changes after activation then the value of this setting will also change, next time it is obtained.	NSString
GDAppConfigKeyUserPrincipalName	User Principal Name. The User Principal Name (UPN) will have been retrieved from the enterprise Active Directory (AD) service by the enterprise management console, and then sent to the runtime, initially at activation time. This value will only be present if the current end user corresponds to an AD entry. The value may or may not be the same as the GDAppConfigKeyUserId value, depending on enterprise domain configuration. The value will be in username@fully.qualified.domain.name format. If the UPN of the end user changes after activation then the value of this setting will also change, next time it is obtained.	NSString
GDAppConfigKeyInstanceIdentifier	Application instance identifier. The BlackBerry Dynamics runtime generates a unique identifier for the installed application when it is activated. This identifier doesn't change during upgrade of the application. It can be matched with a value on the management console, for tracking and analysis. This identifier will be different: For the same application installed on different devices, even if installed for the same end user in the same deployment. For different applications installed on the same device. If the application is uninstalled and reinstalled. The identifier will change value if the end user is migrated from one management console instance to another. See also the GDContainerMigrationPendingNotification migration pending NSNotification name reference documentation.	NSString
GDAppConfigKeyCommunicationProtocols	Communication protocols allowed by the enterprise. A list of allowed and disallowed communication protocols can be set in the enterprise management console. The runtime will have retrieved the list, initially at activation time. The list is represented as an NSDictionary collection with the following keys: GDProtocolsKeyTLSv1_0 (GDiOS) GDProtocolsKeyTLSv1_1 (GDiOS) GDProtocolsKeyTLSv1_2 (GDiOS) The value in the collection for a particular key will be YES if the corresponding protocol is allowed, and NO otherwise. Some earlier versions of the management console software don't support this feature, and don't provide a list of allowed and disallowed protocols to the runtime. In that case, this element will be nil instead of a collection.	NSDictionary
GDAppConfigKeyProtectedByPassword	BlackBerry Dynamics password enforcement. 1 if a password or other interactive authentication is enforced by BlackBerry Dynamics, 0 otherwise. See canAuthorizeAutonomously (GDiOS) for discussion.	NSNumber
GDAppConfigKeyExtraInfo	Extra information sent by the management console. The management console can send extra information that isn't required for the operation of the BlackBerry Dynamics runtime but which might be of use to the application. For example, one or more additional identifiers for the end user could be included as extra information. The values will be encapsulated in a single JavaScript Object Notation (JSON) string. Some earlier versions of the management console software don't provide extra information. In that case, this element will be absent from the collection.	NSString

Data Leakage Policy Enforcement

Security policies other than the Data Leakage policy (DLP) mentioned in the above are enforced by the BlackBerry Dynamics runtime, without reference to the application. DLP must generally be enforced by the application, with some exceptions.
If DLP is switched on, the BlackBerry Dynamics runtime will:

• Secure general cut-copy-paste operations by the user.
• Secure data written to the general pasteboard by content-rendering UIKit components.

Secure cut-copy-paste operations allow the user to copy and move data via the clipboard only:

• Within one BlackBerry Dynamics application.
• Between BlackBerry Dynamics applications, on the same device, that were activated for the same end user from the same enterprise management console.
• Between BlackBerry Dynamics applications, on multiple iOS and macOS devices conforming to Apple Continuity system requirements, that were activated for the same end user from the same enterprise management console.

Other aspects of data leakage must be enforced by the application.
Note that pasteboards other than the general pasteboard, i.e. programmatically created UIPasteboard instances, are never secured by the BlackBerry Dynamics runtime.

See also

Universal Clipboard on the apple.com support website.

Application Server Selection

The GDAppConfigKeyServers value will contain a list of the servers that have been configured for the application in the enterprise management console. In the case that more than one server has been configured, the recommended selection algorithm is as follows:

1. For each priority value in the list, starting with the highest:
2. Select a server that has that priority, at random.
3. Attempt to connect to the server.
4. If connection succeeds, use that server.
5. If connection fails, try another server at the same priority, at random.
6. If there are no more untried servers at that priority, try the servers at the next lower priority.

See also

System administration tasks

NSDictionary class reference in the Apple API Reference on the apple.com developer website.

The GD-Secure compliance document.

getApplicationPolicy

- (NSDictionary<NSString *, id> *) getApplicationPolicy

This function returns a collection of application-specific policy settings. The settings will have been made in the management console, and retrieved by the BlackBerry Dynamics runtime.

For more documentation of the feature and how application policies are defined, see the Application Policies Definition documentation.

Retrieval of policy settings may happen during authorization processing, or whenever settings are changed. When changed settings have been retrieved by the runtime, a GDAppEventPolicyUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Note that retrieval of that latest policy from the management server is not triggered by calling this function.

Returns

NSDictionary containing policy settings.

The keys will be the same as the settings identifiers in the policy definition. The values will be the particular values that apply to the end user. The value types are mapped from the definition as follows.

Definition Type	Dictionary Value Type
null	nil
boolean	NSNumber
double	NSNumber
int	NSNumber
object	NSDictionary
array	NSArray
string	NSString

See also

getApplicationPolicyString (GDiOS)

getApplicationPolicyString

- (NSString*) getApplicationPolicyString

This function returns application-specific policy settings in a JavaScript Object Notation (JSON) string. The settings will have been made in the management console, and retrieved by the BlackBerry Dynamics runtime.

For more documentation of the feature and how application policies are defined, see the Application Policies Definition documentation.

Retrieval of policy settings may happen during authorization processing, or whenever settings are changed. When changed settings have been retrieved by the runtime, a GDAppEventPolicyUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Note that retrieval isn't as such triggered by calling this function.

Returns

NSString containing policy settings in a JSON string. The string will evaluate to an object with an attribute for each application-specific setting. The names of the attributes will be the same as the settings identifiers in the policy definition. The attribute values will be the particular values that apply to the end user.

See also

getApplicationPolicy (GDiOS)

getServiceProviders

- (NSArray<GDServiceProvider *> *) getServiceProviders

This function returns a list of all available providers of shared services. The list contains both application-based and server-based service providers.

The returned list is based on the BlackBerry Dynamics entitlement configuration in the enterprise management console and in the central BlackBerry Dynamics Catalog. An entitlement can correspond to an application, or can be a placeholder for something more abstract such as access to a feature or resource. In any case, entitlements have unique identifiers and versions.

The list includes an entry for each entitlement version that meets all the following conditions.

• The entitlement version is registered as the provider of one or more shared services, see notes on service provider registrations, below.
• The end user that activated the running application has been granted the entitlement version, i.e. they are entitled to the service provider.
• For entitlements that represent application-based service providers: the corresponding application has been installed and activated for the same end user, and on the same device or computer, as the current application.

On devices running iOS version 9 or later, the list could include providers of application-based services that were installed and activated as above, but then uninstalled. An attempt to send a service request to an application that is not currently installed results in a GDServicesErrorApplicationNotFound error.

Service provider registrations are stored within the BlackBerry Dynamics infrastructure, on a server known as the Catalog. Registrations are stored as relationships between entitlement versions and service identifiers. The user interface for registration administration is either the enterprise management console, or a website that can be reached via the application developer portal. The same user interfaces are used for the creation and administration of individual shared service definitions.

The runtime retrieves the information used to generate the list of service providers from the Catalog, and from the enterprise management console. Retrieval can take place when the application is authorized, or when another application activates on the same device, or when the configuration is changed in the enterprise management console. Note that retrieval isn't as such triggered by calling this function.

For each entitlement version that satisfies the above conditions, this function returns a GDServiceProvider object.

The returned details for an application-based provider can be used to send a service request to the service provider using BlackBerry Dynamics AppKinetics. See the GDService class reference for details of the programming interface. See under Service Provider Requirements on that page for information on service provider registration, which is a prerequisite for an application to be on the list returned by this function.

The returned details for a server-based provider can be used to establish HTTP or TCP socket communications with a server instance.

Returns

NSArray of GDServiceProvider objects containing the list of available service providers. The order of objects in the list is unspecified.

A single service could have multiple providers. A single provider could provide multiple services, and multiple versions of services.

When changed details have been retrieved by the runtime, a GDAppEventServicesUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Icon images

The objects returned by this function can include icon images for service provider applications. Utilization of icon images is optional. If the application does utilize icon images, then make a setting in the application's Info.plist file* as follows.

• Key: GDFetchResources
• Type: Boolean
• Value: YES

(*In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The setting just made should appear there.)

If the setting is missing or the value is NO, this indicates that the application doesn't utilize icon images.

The data for icon images would be retrieved by the BlackBerry Dynamics runtime, from a BlackBerry Dynamics Catalog service. BlackBerry may switch off the icon image service at the Catalog from time to time, for operational reasons. If the icon image service is switched off then all icon images in the returned objects will be nil.

getServiceProvidersFor:andVersion:andServiceType:

- (NSArray<GDServiceProvider *> *) getServiceProvidersFor:		(NSString *)	serviceId
andVersion:		(nullable NSString *)	version
andServiceType:		(GDServiceType)	serviceType

This function returns a list of the available providers of a specified service.

The returned list is based on the BlackBerry Dynamics entitlement configuration in the enterprise management console and in the central BlackBerry Dynamics Catalog. The list includes an entry for each entitlement version that meets all the following conditions.

• The entitlement version would be on the list of service providers returned by the getServiceProviders (GDiOS) function, see above.
• The entitlement version is registered as a provider of the specified service.
• The entitlement version is registered as a provider of the specified service type, either server-based or application-based.
• The entitlement version is registered as a provider of the service version, if specified.

Parameters

serviceId	NSString specifying the identifier of the required service.
version	NSString specifying the required version of the service, or nil to leave unspecified.
serviceType	GDServiceType value specifying the required type of service.

Returns

NSArray of GDServiceProvider objects containing the list of available service providers. The order of objects in the list is unspecified.

See also the note on Icon images in the getServiceProviders function documentation, above.

getEntitlementVersionsFor:callbackBlock:

- (void) getEntitlementVersionsFor:		(NSString *)	identifier
callbackBlock:		(GDGetEntitlementVersionsForBlock)	block

Call this function to check whether the current end user has a specific BlackBerry Dynamics entitlement. The return value is a list of entitlement versions, which might be empty.

This function can be used to check for entitlement to:

• A specific BlackBerry Dynamics mobile or desktop application, identified by a BlackBerry Dynamics entitlement identifier.
• A more abstract entitlement, such as a feature, also identified by an entitlement identifier.

Note that there is a single namespace and format for entitlement identifiers, whether used for applications or for more abstract entitlements. All entitlements have versions, as well as identifiers. The syntax for entitlement identifiers and versions is detailed above, under the headings Entitlement Identifier Format and Entitlement Version Format. The syntax applies to all types of entitlement.

Specify the entitlement to be checked by passing its identifier as a parameter. The return value will be a list:

• If the end user doesn't have the specified entitlement, the list will have zero elements.
• Otherwise, the list will have one element for each version to which the end user is entitled. Each element will be a GDVersion object.

This function is asynchronous.

The result list is returned by execution of a code block. Specify the code block as a parameter to this function. The result list will be passed as a block parameter to the execution. If an error occurs and the entitlement cannot be checked, nil will be passed instead of the list, and an NSError object will be passed as a second block parameter.

Calling this function can result in data communication with the BlackBerry Dynamics infrastructure.

Parameters

identifier

NSString containing the entitlement identifier.

block

Block to execute when the lookup completes. The block receives two parameters: NSArray of GDVersion objects representing the versions to which the end user is entitled if the original call succeeds, or nil otherwise. NSError object containing a numeric code for the error condition if the original call fails, or nil otherwise. The numeric code will be in one of the following ranges, depending on the type of error condition encountered: 400 to 599: One or more servers involved in the check encountered an error and the check could not be completed. -1 to -50: A general error occurred.

The entitlements of the end user can change, for example if the user's group membership is changed at the enterprise management console. The BlackBerry Dynamics runtime is notified of these changes by the BlackBerry Dynamics infrastructure, and dispatches a GDAppEventEntitlementsUpdate event to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

getWindow

- (UIWindow*) getWindow

Deprecated:

This function is deprecated and will be removed in a future release. Use the window property from the main app delegate instance.

This function returns a reference to the UIWindow that contains the core logic of the BlackBerry Dynamics runtime. Always use this function instead of creating a new UIWindow in the application.

The BlackBerry Dynamics runtime creates its own UIWindow in order to show its user interface elements, and to track for user inactivity. The runtime doesn't add any persistent subviews, so the application is free to add and remove its own subviews on the BlackBerry Dynamics UIWindow. For example, after authorization, the application could call setRootViewController to add its own UIViewController or UINavigationController.

The runtime calls makeKeyAndVisible on its UIWindow during authorization processing, so the application needn't do this. The application mustn't make a different UIWindow the key window. The application also mustn't release the runtime's UIWindow object.

Returns

Reference to the BlackBerry Dynamics UIWindow, which must be used as the application's key window.

See also

UIWindow class reference in the Apple API Reference on the apple.com developer website.

getVersion

- (NSString*) getVersion

Returns

NSString containing the BlackBerry Dynamics runtime library version in major.minor.build format.

showPreferenceUI:

- (BOOL) showPreferenceUI:

(nullable UIViewController *)

baseViewController

Call this function to show the BlackBerry Dynamics interface to enable the user to change their unlock password.

This function enables a BlackBerry Dynamics user interface element to be included in the application's own user interface.

If authorization is delegated to another application, then that application will be opened and its Change Password user interface will be shown.

Parameters

baseViewController

Reference to the navigation controller within which the BlackBerry Dynamics user interface element is to open as a view controller. Pass a null pointer to open the the user interface as a modal view controller, for example when no navigation controller is available.

Returns

YES if the user interface element opened OK.

NO if the user interface element was already open, or if enterprise policy doesn't require a password to unlock the application, or if the application has been wiped.

configureUIWithLogo:bundle:color:

- (void) configureUIWithLogo:		(NSString *)	imagePath
bundle:		(nullable NSBundle *)	bundle
color:		(nullable UIColor *)	color

Call this function to configure the visual appearance of the built-in BlackBerry Dynamics user interface. The following aspects can be configured:

• Logo image.
• Brand color, used for the key line and interactive elements.

This function can be called prior to authorize, in order to configure the user interface as displayed during authorization processing.

Parameters

imagePath	NSString containing the path of the image to show as the logo. The image must be in PNG format. The maximum supported image size is 528 by 140 pixels. If the specified image is larger than the maximum, the image will be adjusted using UIViewContentModeScaleAspectFit mode.
bundle	NSBundle for the resource bundle that contains the replacement logo image, or nil to specify mainBundle.
color	UIColor for the brand color, or nil to select the default.

See also

authorize (GDiOS) for details of which BlackBerry Dynamics user interface elements may be shown during authorization processing.

UIViewContentMode documentation in the Apple API Reference on the apple.com developer website, for definitions of image adjustment modes

executeRemoteLock

- (BOOL) executeRemoteLock

Call this function to lock the application permanently, as though a remote lock-out had been received from the enterprise management console. The application data will become inaccessible but won't be erased.

A remote lock-out is, in effect, a withdrawal of the end user's authorization to utilise the application. The user cannot unlock the application in the normal way, for example they cannot enter their BlackBerry Dynamics password, if a remote lock-out is in place. Instead, a special unlock code must be obtained from the management console, and entered in the remote unlock BlackBerry Dynamics user interface.

See also

GDAppEvent class reference, which mentions the GDErrorRemoteLockout result code. An event with that result code would be dispatched if a remote lock-out command was received from the management console.

executeBlock:withTitle:withMessage:

- (void) executeBlock:		(NSString *)	blockId
withTitle:		(NSString *)	title
withMessage:		(NSString *)	message

Call this function to block use of the application, as though a remote block had been received from the enterprise management console. Include a title and description to inform the user what threat or action has triggered the block. If several blocks have been applied then it is the most recent block which will be displayed to the user in the block screen.

While blocked, the application can utilize the principal Dynamics APIs like secure storage and secure communications.

Blocks are persisted which means that after an application is restarted and the user is authenticated the block screen will be displayed. In addition a GDAppEvent with the result code GDErrorBlocked would be dispatched. This event would be received for blocks applied locally with this function and those applied from the management console.

The application should persist in secure storage the blockId called in this function. When a GDErrorBlocked event is received the application should check if any blocks are applied locally and determine if the block can now be removed.

Parameters

blockId	NSString specifying the block identifier. This identifier is required to subsequently remove the block.
title	NSString containing the title shown on the block screen.
message	NSString containing the detailed message to display on the block screen.

executeUnblock:

- (void) executeUnblock:

(NSString *)

blockId

Call this function to remove a block screen with associated blockId. Other local or remote blocks will still leave the application blocked. Blocks applied by the management console cannot be unblocked using this function.

Parameters

blockId

NSString specifying the block identifier.

executePendingConsoleMigration:withUemServerAddress:

- (BOOL) executePendingConsoleMigration:		(NSString *)	destinationTenantID
withUemServerAddress:		(NSString *)	uemServerAddress

Returns

YES if destinationTenantID is provided

NO if destinationTenantID is empty

Call this function to execute a migration of the application to the specified management console. This should only be called by an application that has been informed by the management console that a migration request is pending. If a migration request is not pending calling this method may result in the container being wiped.

Parameters

destinationTenantID	NSString specifying the tenant identifier of the UEM management console.
uemServerAddress	NSString containing the URL for UEM enrollment service.

getManagedLauncherViewController

- (GTLauncherViewController *) getManagedLauncherViewController

Call this method to access the GTLauncherViewController instance currently being displayed and managed by BlackBerry Dynamics. If BlackBerry Dynamics is not managing the GTLauncherViewController, this method will return nil.

BlackBerry Dynamics will attempt to manage the GTLauncherViewController by default, providing this functionality to all apps. If this is not desired, disable this behavior by creating an entry in the Info.plist file, as shown:

<key>GDDisableAutomaticLauncherManagement</key>
<true/>

Additionally, if BlackBerry Dynamics is managing the GTLauncherViewController, then it is illegal for an application to call [UIWindow setRootViewController] with an argument of GTLauncherViewController, and this will result in an NSInvalidArgumentException being raised.

Should the application need to manage an instance of GTLauncherViewController, set the Info.plist entry as described above.

Returns

GTLauncherViewController instance managed by BlackBerry Dynamics, or nil

Member Data Documentation

ActivationParameterUserIdentifier

- (const ActivationParameter) ActivationParameterUserIdentifier

ActivationParameterAccessKey

- (const ActivationParameter) ActivationParameterAccessKey

ActivationParameterNOCAddress

- (const ActivationParameter) ActivationParameterNOCAddress

ActivationParameterShowUserInterface

- (const ActivationParameter) ActivationParameterShowUserInterface

ActivationParameterEnrollmentAddress

- (const ActivationParameter) ActivationParameterEnrollmentAddress

ActivationParameterPassword

- (const ActivationParameter) ActivationParameterPassword

Property Documentation

activationComplete

- (BOOL) activationComplete

readnonatomicassign

Read the value of this property, using the isActivated accessor, to check whether the application has already been activated. It is necessary to check whether the application has been activated before initiating programmatic activation.

This property has the value:

• YES if the application has been activated.
• NO otherwise.

delegate

- (id<GDiOSDelegate>) delegate

readwritenonatomicweak

When authorization processing completes, or a BlackBerry Dynamics runtime object event occurs, an event is generated by the runtime, and passed to a callback function in the application code.

Set this property to an instance of a class in the application that contains the code for the required callback function, i.e. a class that implements the GDiOSDelegate protocol.

See also

GDState for an alternative mechanism.

canAuthorizeAutonomously

- (BOOL) canAuthorizeAutonomously

readnonatomicassign

Access this property to check whether autonomous authorization is possible. Autonomous authorization won't be possible if the application is protected by a BlackBerry Dynamics password. This means a password or other interactive authentication that is enforced by the BlackBerry Dynamics runtime.

Interactive authentication will be enforced by BlackBerry Dynamics unless a no-password policy applies to the current end user. A no-password policy would typically be put in place only in the case that interactive authentication is enforced by some other means. For example, enterprise mobile device management (MDM) can be used to force users to set a device password or lock pattern. In that case, the enterprise might choose to set a no-password policy for BlackBerry Dynamics, so that end users don't have to enter two passwords.

If interactive authentication isn't enforced by BlackBerry Dynamics, then it is possible for authorization processing to complete autonomously, because interaction with the user isn't required.

The intended use of this property is to check whether it is possible for authorization processing to complete autonomously, before calling the authorizeAutonomously: (GDiOS) function.

Note that it won't be possible to authorize autonomously if enterprise policy specifies that the application delegates authentication to another application. This would only happen if the current end user somehow had both policies in place: authentication delegation, and no-password. This combination isn't recommended. There would seem to be no point in delegating authentication to another application if that other application is going to authenticate the end user without interaction.

This property can be accessed before authorization processing is complete.

This property has the value:

• YES if autonomous authorization is possible.
• NO if a password is enforced by BlackBerry Dynamics, or if autonomous authorization isn't possible for some other reason.

state

- (GDState*) state

readnonatomicstrong

Access this property to check or observe the state of the BlackBerry Dynamics runtime.

A number of aspects of run-time state are represented in this property, including authorization state and user interface state. The representation is compatible with key-value observing (KVO). See the GDState class reference for details.

Returns

GDState instance representing the current state.

---

The documentation for this class was generated from the following file:

• GDiOS.h