blackberry.com
BlackBerry Dynamics
Runtime library for macOS applications
from the application developer portal
Public Types | Public Member Functions | Static Public Member Functions | Properties

GDMac Class Reference

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

#import <GDMac.h>

List of all members.

Public Types

Public Member Functions

Static Public Member Functions

Properties


Detailed 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 for application developers
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 ordinarily facilitated by the application delegate, adopting the GDMacDelegate protocol, taking advantage of automatic initiation of BlackBerry Dynamics authorization. Alternatively, this can be initiated by a single call to the authorize: function passing an instance of an object that adopts the GDMacDelegate protocol.

The authorize: function call is typically made when the application starts, in the applicationDidFinishLaunching: 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:
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 by dispatching a GDAppEvent object to the GDMacDelegate instance in the application. The event will have a number of attributes, including a type value that indicates whether the user is now authorized.

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

StateDescriptionGDAppEvent
type value
Not authorizedInitial state.
The application can initiate authorization, but cannot utilize the principal interfaces.
AuthorizedEither 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
LockedAuthorization 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
WipedAuthorization 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:

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 [GDMac 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 for application developers.

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 entitlment identifier.

Entitlement identifiers are used:

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 for application developers.

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:

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 syntax rules of entitlement version values are as follows.

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

The BlackBerry Dynamics runtime monitors the application user interface in order to enforce a number of enterprise security policies. For example, there may be a policy that the user must always enter their security password when the application makes the transition from background to foreground. There may also be a policy that the user interface must be locked after a period of inactivity.

The application user interface must observe a number of restrictions in order to enable monitoring by the runtime.

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 (GDMac) and getApplicationConfig (GDMac) 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 GDMacDelegate instance when the result would change.

For example, the getApplicationPolicy (GDMac) function returns an NSDictionary collection. When there is a change, 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 an application delegate, adopting the GDMacDelegate protocol, taking advantage of automatic initiation of Good Dynamics authorization.

 @interface AppDelegate () <GDMacDelegate>

 @end

The following snippet shows alternative initiation of Good Dynamics authorization by providing an instance of an object adopting the GDMacDelegate protocol. If the application delegate conforms to GDMacDelegate then do not invoke this function as it will be called automatically by the GD Runtime.

 [[GDMac sharedInstance] authorize:object_adopting_GDMacDelegate];

After initiating Good Dynamics authorization 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 Good 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 GD application ID, and "1.0.0.0" as the GD application version.

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 GD 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.
The initial application window, when the application utilizes a main application Storyboard or XIB, should check this flag before initializing its own UI.
The handler calls the application's own onNotAuthorized function whenever a GDAppEventNotAuthorized event is received.


Member Typedef Documentation

- (typedef void(^ GDGetEntitlementVersionsForBlock)(NSArray *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:
entitlementVersionsNSArray of GDVersion objects representing the versions of the entitlement to which the end user is entitled if the original call succeeded, or nil otherwise.
errorNSError containing a description of the error condition if the original call failed, or nil otherwise.

Member Function Documentation

+ (GDMac*) sharedInstance

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

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

Returns:
Reference that can be used to call, for example, authorize (GDMac).
- (void) authorize: (id< GDMacDelegate >)  aDelegate

Only call this function from the application delegate when the application delegate does not adopt GDMacDelegate. 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 (GDMac) 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 applicationDidFinishLaunching: 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:
aDelegateReference to the delegated event handler.

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

KeyTypeValue
GDApplicationIDString

Good Dynamics Application ID (GD App ID)

GD App ID 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 that entered when the application was registered in the enterprise's Good Control console. (Note that the value need not be the same as the native application identifier.)

For syntax details see under Application Identification, above.

GDApplicationVersionString

Good Dynamics application version number

The version number can be combined with the GD App ID, 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.

- (NSDictionary*) 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

* * * *

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

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: 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.

NSNumber


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 any pasteboard by content-rendering AppKit components.
  • Secure data programmatically written to any pasteboard.
  • Secure drag-drop operations from and to the application.
Secure cut-copy-paste and secure drag-drop operations allow the user to copy and move data via the clipboard only:
  • Within one BlackBerry Dynamics application.
  • Between BlackBerry Dynamics applications 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.

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 for application developers
NSDictionary class reference in the Apple API Reference on the apple.com developer website.
The GD-Secure compliance document.
- (NSDictionary*) 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 isn't 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 TypeDictionary Value Type
nullnil
booleanNSNumber
doubleNSNumber
intNSNumber
objectNSDictionary
arrayNSArray
stringNSString
See also:
getApplicationPolicyString (GDMac)
- (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 (GDMac)
- (NSArray *) 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.

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.

- (NSArray *) getServiceProvidersFor: (NSString *)  serviceId
andVersion: (NSString *)  version
andType: (GDServiceProviderType serviceProviderType 

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 (GDMac) 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:
serviceIdNSString specifying the identifier of the required service.
versionNSString specifying the required version of the service, or nil to leave unspecified.
serviceProviderTypeGDServiceProviderType 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.

- (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:
identifierNSString containing the entitlement identifier.
blockBlock 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.

- (NSString*) getVersion
Returns:
NSString containing the Good Dynamics Runtime library version in major.minor.build format.
- (BOOL) changeApplicationPassword

Call this function to show the Good Dynamics (GD) password change user interface (UI). This is the UI in which the end user changes their security password.

Returns:
YES if the GD preferences UI opened OK.
NO if the preferences UI was already open, or if authorization is delegated to another application.

Property Documentation

- (id<GDMacDelegate>) delegate [read, write, assign]

When authorization processing completes, or a Good 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 GDMacDelegate protocol.

- (GDState*) state [read, assign]

Access this property to check or observe the state of the GD 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: