BlackBerry Dynamics for Xamarin Forms  7.0.0.22
Runtime library for Xamarin Forms applications
BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin Interface Reference

This interface represents the application's connection to its embedded BlackBerry Dynamics Runtime instance, and to the wider BlackBerry Dynamics platform infrastructure. More...

Public Member Functions

string GetVersion ()
 Get the BlackBerry Dynamics Runtime library version. More...
 
void ExecuteRemoteLock ()
 Lock the application permanently. More...
 
Task ConfigureUIWithLogoAsync (ImageSource applicationLogo, Color?color)
 
int GetEntitlementVersions (string identifier, BBDGetEntitlementVersionsDelegate requestCallback)
 Checks whether the end user has a particular entitlement. More...
 
List< IBBDServiceProviderGetServiceProvidersFor (string serviceId, string version, BBDServiceTypeEnum serviceType)
 Discovers providers of a specific shared service. More...
 
List< IBBDServiceProviderGetServiceProviders ()
 Gets providers of shared services. More...
 
void ProgrammaticAuthorize (string userId, string accessKey, string nocAddress="", bool showUserInterface=true)
 Initiate programmatic activation. More...
 
bool OpenChangePasswordUI ()
 
bool OpenFingerprintSettingsUI ()
 
Dictionary< string, object > GetApplicationConfig ()
 Gets application configuration and other settings from the enterprise. More...
 
Dictionary< string, object > GetApplicationPolicy ()
 Gets application-specific policy settings from the BlackBerry Control server, as a collection. More...
 
string GetApplicationPolicyString ()
 Get application-specific policy settings from the BlackBerry Control server, as JSON. More...
 
void Authorize ()
 Call this function to initiate BBD authorization processing. More...
 
bool AuthorizeAutonomously ()
 Connect to the BlackBerry Dynamics infrastructure in background. More...
 
void ExecuteBlock (string blockId, string title, string 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. More...
 
void ExecuteUnblock (string blockId)
 Call this method 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 method. More...
 

Properties

string BBDAppConfigKeyServers [get]
 Constant key value for application server configuration. More...
 
string BBDAppConfigKeyConfig [get]
 Constant key value for application-specific configuration data. More...
 
string BBDAppConfigKeyPreventDataLeakageOut [get]
 Constant key value for the outbound Data Leakage security policy indicator. More...
 
string BBDAppConfigKeyPreventDataLeakageIn [get]
 Constant key value for the inbound Data Leakage security policy indicator. More...
 
string BBDAppConfigKeyPreventDictation [get]
 Constant key value for allowing or disallowing using dictation. More...
 
string BBDAppConfigKeyDetailedLogsOn [get]
 Constant key value for enabling and disabling detailed diagnostic logging. More...
 
string BBDAppConfigKeyPreventUserDetailedLogs [get]
 Constant key value for allowing and disallowing users from enabling detailed diagnostic logging. More...
 
string BBDAppConfigKeyProtectedByPassword [get]
 Constant key value for whether the application is protected by a BlackBery Dynamics password. More...
 
string BBDAppConfigKeyUserId [get]
 Constant key value for the enterprise user identifier, typically email address. More...
 
string BBDAppConfigKeyUserPrincipalName [get]
 Constant key value for the user's User Principal Name (UPN). More...
 
string BBDAppConfigKeyExtraInfo [get]
 Constant key value for extra information from the management console. More...
 
string BBDAppConfigKeyCommunicationProtocols [get]
 Constant key value for the list of communications protocols allowed by the enterprise. More...
 
string BBDAppConfigKeyInstanceIdentifier [get]
 Constant key value for the unique identifier of the installed application. More...
 
string BBDProtocolsKeyTLSv1_0 [get]
 Constant value for a secure communication protocol: TLS version 1.0. More...
 
string BBDProtocolsKeyTLSv1_1 [get]
 Constant value for a secure communication protocol: TLS version 1.1. More...
 
string BBDProtocolsKeyTLSv1_2 [get]
 Constant value for a secure communication protocol: TLS version 1.2. More...
 
bool CanAuthorizeAutonomously [get]
 Access this property to check whether autonomous authorization is possible. More...
 
bool IsActivated [get]
 Checks whether the application has been activated. More...
 
string Version [get]
 Get the BlackBerry Dynamics Core (iOS/Android BBD SDK) runtime library version in major.minor.build format. More...
 
string XamarinFormsVersion [get]
 Get the BlackBerry Dynamics Xamarin Forms runtime library version in major.minor.build format. More...
 
string XamarinPlatformVersion [get]
 Get the BlackBerry Dynamics Xamarin Platform (iOS/Android BBD SDK Xamarin bindings) runtime library version in major.minor.build format. More...
 
IBBDApplicationState ApplicationState [get]
 Access this property to check or observe the state of the BlackBerry Dynamics Runtime. More...
 

Events

EventHandler< Events.BBDAppEventEventArgsBBDAppEvent
 The callback is invoked whenever a BlackBerry Dynamics Runtime object event occurs. More...
 
EventHandler Authorized
 Callback for authorization granting or unlocking. More...
 
EventHandler< Events.BBDAppEventEventArgsNotAuthorized
 Callback for error during authorization. More...
 
EventHandler Locked
 Callback for user interface locking. More...
 
EventHandler Wiped
 Callback for permanent authorization withdrawal. More...
 
EventHandler< IDictionary< string, object > > UpdateConfig
 Callback for changes to application configuration and other settings from the enterprise. More...
 
EventHandler< IDictionary< string, object > > UpdatePolicy
 Callback for changes to application-specific policy settings. More...
 
EventHandler UpdateServices
 Callback for changes to services-related configuration. More...
 
EventHandler UpdateEntitlements
 Callback for changes to entitlements. More...
 
EventHandler BBDContainerMigrationPending
 Occurs when the end user has been selected for migration between management console instances. More...
 
EventHandler BBDContainerMigrationCompleted
 Occurs when the end user has been migrated between management console instances, see BBDContainerMigrationPending. More...
 

Detailed Description

This interface represents the application's connection to its embedded BlackBerry Dynamics Runtime instance, and 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 management console (UEM or standalone Good Control), 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.

For more information go to BlackBerry Dynamics for iOS and Android.

Member Function Documentation

void BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.Authorize ( )

Call this function to initiate BBD authorization processing.

bool BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.AuthorizeAutonomously ( )

Connect to the BlackBerry Dynamics infrastructure in background.

Access the CanAuthorizeAutonomously property first, to check that a no-password policy applies to the current end user and that autonomous authorization is possible.

Returns
true, if autonomously was authorized, false otherwise.
Task BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.ConfigureUIWithLogoAsync ( ImageSource  applicationLogo,
Color?  color 
)

Call this function to configure the visual appearance of screens in the BlackBerry Dynamics user interface (BBD UI).

The following aspects of the BBD UI's appearance 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 BBD UI as displayed during authorization processing.

Parameters
applicationLogoThe application logo.

iOS:FileImageSource containing the path of the image to show as the logo. If the replacement logo image is not in the mainBundle, the path should start with 'bundleName.bundle/' 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.

Android:ImageSource for the image to show as the logo. The image will be scaled to fit the screen, with aspect ratio preserved.

Parameters
colorColor for the brand color, or null to select the default.
void BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.ExecuteBlock ( string  blockId,
string  title,
string  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 BBDAppEvent with the result code BBDAppResultCodeEnum.BBDErrorBlocked 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 BBDAppResultCodeEnum.BBDErrorBlocked event is received the application should check if any blocks are applied locally and determine if the block can now be removed.

Parameters
blockIdString specifying the block identifier. This identifier is required to subsequently remove the block.
titleString containing the title shown on the block screen.
messageString containing the detailed message to display on the block screen.
void BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.ExecuteRemoteLock ( )

Lock the application permanently.

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.

void BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.ExecuteUnblock ( string  blockId)

Call this method 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 method.

Parameters
blockIdString specifying the block identifier.
Dictionary<string, object> BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetApplicationConfig ( )

Gets application configuration and other settings from the enterprise.

Returns
A collection of application configuration and other settings. The settings will have been made in the enterprise BlackBerry Control (legacy GC) server, and retrieved by the BlackBerry Dynamics Runtime.
Dictionary<string, object> BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetApplicationPolicy ( )

Gets application-specific policy settings from the BlackBerry Control server, as a collection.

Returns
A collection of application-specific policy settings. The settings will have been entered in the BlackBerry Control (legacy GC) console, and retrieved by the BlackBerry Dynamics Runtime.
string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetApplicationPolicyString ( )

Get application-specific policy settings from the BlackBerry Control server, as JSON.

Returns
The application policy string.
int BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetEntitlementVersions ( string  identifier,
BBDGetEntitlementVersionsDelegate  requestCallback 
)

Checks whether the end user has a particular entitlement.

Returns
  • iOS: Zero in case of success.
  • Android: int containing a value that identifies this check and which will later be passed to the results callback.
Parameters
identifierString containing the entitlement identifier.
requestCallbackDelegate to execute when the lookup completes.
List<IBBDServiceProvider> BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetServiceProviders ( )

Gets providers of shared services.

Returns
List of IBBDServiceProvider objects containing all available providers of shared services. The list contains both application-based and server-based service providers.
List<IBBDServiceProvider> BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetServiceProvidersFor ( string  serviceId,
string  version,
BBDServiceTypeEnum  serviceType 
)

Discovers providers of a specific shared service.

Returns
List of IBBDServiceProvider objects containing the list of available service providers. The order of objects in the list is not specified.
Parameters
serviceIdString specifying the ID of the required service.
versionString specifying the required version of the service, or null to leave unspecified.
serviceTypeBBDServiceTypeEnum value specifying the required type of service.
string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.GetVersion ( )

Get the BlackBerry Dynamics Runtime library version.

Deprecated:
This method is deprecated and will be removed in a future release. Use Version property instead.
Returns
string containing the BlackBerry Dynamics Runtime library version in major.minor.build format.
bool BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.OpenChangePasswordUI ( )

Call this method to show the BlackBerry Dynamics (BBD) change password user interface (UI).

This method enables the BBD change password UI to be included in the application's own user interface.

Returns
true, if the BBD change password UI opened OK, or was already open, false if authorization is delegated to another application, authentication mode is set to no password, or if this application is in the Wiped state.
bool BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.OpenFingerprintSettingsUI ( )

Call this method to show the BlackBerry Dynamics (BBD) fingerprint settings user interface (UI).

This method enables the BBD fingerprint settings UI to be included in the application's own user interface. It should only be included if fingerprint authentication is currently available.

Returns
true, if the BBD fingerprint setting UI opened OK, or was already open, false if fingerprint authorization isn't available, or if the UI cannot be opened for another reason, see under OpenChangePasswordUI, above.
void BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.ProgrammaticAuthorize ( string  userId,
string  accessKey,
string  nocAddress = "",
bool  showUserInterface = true 
)

Initiate programmatic activation.

Only call this function after checking that the application is not already activated, by accessing the IsActivated property.

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.

Parameters
userIdString containing the user ID, an enterprise activation credential.
accessKeyString containing the access key, an enterprise activation credential.
nocAddressString containing a NOC server address, or an alias. The URL must always include a scheme, such as https.
showUserInterfaceBool value which if set to false, will prevent the BlackBerry Dynamics Runtime activation UI from being shown during activation.

Property Documentation

IBBDApplicationState BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.ApplicationState
get

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

Returns
string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyCommunicationProtocols
get

Constant key value for the list of communications protocols allowed by the enterprise.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyConfig
get

Constant key value for application-specific configuration data.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyDetailedLogsOn
get

Constant key value for enabling and disabling detailed diagnostic logging.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyExtraInfo
get

Constant key value for extra information from the management console.

Some earlier versions of the management console software don't provide extra information. In that case, this element will be absent from the collection.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyInstanceIdentifier
get

Constant key value for the unique identifier of the installed application.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyPreventDataLeakageIn
get

Constant key value for the inbound Data Leakage security policy indicator.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyPreventDataLeakageOut
get

Constant key value for the outbound Data Leakage security policy indicator.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyPreventDictation
get

Constant key value for allowing or disallowing using dictation.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyPreventUserDetailedLogs
get

Constant key value for allowing and disallowing users from enabling detailed diagnostic logging.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyProtectedByPassword
get

Constant key value for whether the application is protected by a BlackBery Dynamics password.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyServers
get

Constant key value for application server configuration.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyUserId
get

Constant key value for the enterprise user identifier, typically email address.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppConfigKeyUserPrincipalName
get

Constant key value for the user's User Principal Name (UPN).

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDProtocolsKeyTLSv1_0
get

Constant value for a secure communication protocol: TLS version 1.0.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDProtocolsKeyTLSv1_1
get

Constant value for a secure communication protocol: TLS version 1.1.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDProtocolsKeyTLSv1_2
get

Constant value for a secure communication protocol: TLS version 1.2.

bool BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.CanAuthorizeAutonomously
get

Access this property to check whether autonomous authorization is possible.

true if can authorize autonomously; otherwise, false.

bool BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.IsActivated
get

Checks whether the application has been activated.

true if is activated; otherwise, false.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.Version
get

Get the BlackBerry Dynamics Core (iOS/Android BBD SDK) runtime library version in major.minor.build format.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.XamarinFormsVersion
get

Get the BlackBerry Dynamics Xamarin Forms runtime library version in major.minor.build format.

string BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.XamarinPlatformVersion
get

Get the BlackBerry Dynamics Xamarin Platform (iOS/Android BBD SDK Xamarin bindings) runtime library version in major.minor.build format.

Event Documentation

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.Authorized

Callback for authorization granting or unlocking.

EventHandler<Events.BBDAppEventEventArgs> BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDAppEvent

The callback is invoked whenever a BlackBerry Dynamics Runtime object event occurs.

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDContainerMigrationCompleted

Occurs when the end user has been migrated between management console instances, see BBDContainerMigrationPending.

This event enables the application to clear any warnings it may have shown about pending migration.

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.BBDContainerMigrationPending

Occurs when the end user has been selected for migration between management console instances.

Migration between management console instances could occur when end users are moved from a legacy Good Control server to an integrated BlackBerry Unified Endpoint Manager (UEM) server, for example.

Migration has two stages:

  1. The end user is selected, at which point migration is pending and this event occurs.
  2. Migration takes place, after which migration is complete and the BBDContainerMigrationCompleted event occurs.

A pending migration will be finalized the next time the application starts, as part of BlackBerry Dynamics authorization processing. Migration finalization involves processing that is similar to initial activation. Finalization can't be processed when the application is authorized and running. Its connection to the BlackBerry Dynamics infrastructure would be disrupted, so migration waits for the next application start.

This event enables the application to warn the end user that they will be migrated the next time the application starts.

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.Locked

Callback for user interface locking.

EventHandler<Events.BBDAppEventEventArgs> BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.NotAuthorized

Callback for error during authorization.

EventHandler<IDictionary<string, object> > BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.UpdateConfig

Callback for changes to application configuration and other settings from the enterprise.

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.UpdateEntitlements

Callback for changes to entitlements.

EventHandler<IDictionary<string, object> > BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.UpdatePolicy

Callback for changes to application-specific policy settings.

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.UpdateServices

Callback for changes to services-related configuration.

EventHandler BBDXamarinForms.Common.Interfaces.RuntimeObject.IBBDXamarin.Wiped

Callback for permanent authorization withdrawal.