• BlackBerry Dynamics
  • Runtime library for Android applications
  • 12.0.1.79
Package com.good.gd.icc

AppKinetics secure inter-application data exchange. More...

Description

This package contains the AppKinetics programming interface. AppKinetics is a means of exchanging data and commands securely between two BlackBerry Dynamics applications running on the same mobile device or computer. The security of data isn't compromised during exchange.

AppKinetics interactions follow a service consumer-provider model. One application initiates communication by sending a service request to another. The initiating application is the service consumer. The application that receives the request is the service provider.

After receiving the service request, the provider executes the necessary processing and could then send a service response back to the consumer. Both the service request and the service response, if any, can contain a number of parameters and file attachments. See under Service Parameters and File Attachments, below.

The sequence of programming interfaces used in a typical AppKinetics interaction is as follows.

  1. The consumer application executes a service discovery query, by calling GDAndroid.getServiceProvidersFor.
  2. The consumer application calls sendTo (GDServiceClient) .
  3. The GDServiceListener.onReceiveMessage callback in the provider application is invoked by the AppKinetics system.
  4. The provider application executes any required processing and then calls replyTo (GDService) .
  5. The GDServiceClientListener.onReceiveMessage callback in the consumer is invoked by the AppKinetics system.

Note that an AppKinetics interaction can be initiated with any BlackBerry Dynamics application whose native application identifier is known in the service consumer. The identifier could be known by being present in the application code or, as shown in the above, could be obtained at run time by using BlackBerry Dynamics service discovery.

Note that the service provider does not necessarily send a response, i.e. the call to replyTo and subsequent invocation of the callback in the consumer do not necessarily take place. The service definition specifies when and whether the provider sends a response, see under Service Definition, below.

The data for requests and responses is sent across a secure connection. The connection is established and maintained as necessary by the BlackBerry Dynamics runtime. This is transparent to the applications, although not always to the end user because the user interface may sometimes "flip" between applications during AppKinetics interaction. See also the Foreground Execution section, below.

AppKinetics cannot be used in Enterprise Simulation mode.

Service Definition

A service provided by an application may conform to a declared service definition. The declaration, if there is one, will specify the following.

  • Identifier and version of the service, conventionally a reversed Internet domain followed by a number of sub-domains separated by full stops (periods). Formally, service identifiers conform to the <subdomain> format defined in section 2.3.1 of RFC1035.
  • Methods that comprise the service.
  • Expected parameters to service requests, per method.
  • Expected file attachments to service requests, per method.
  • Whether and in what circumstances service responses will be issued, per method.
  • What types of service response will be issued, per method.
  • Expected parameters to service responses, per method and per type.
  • Expected file attachments to service responses, per method and per type.
  • Error conditions that are specific to the service.

An application that registers as providing a service for which there is a definition must adhere to the definition. Similarly, an application that consumes a service that is based on a declared definition should only send requests that conform to the definition.

The service definition for a public service may be published to the BlackBerry Dynamics application developer portal. The published definition may include a link to additional reference documentation for the service. In any case, the reference documentation may be obtained from the developer of a service provider application, or from the creator of the service definition.

See also
Application-Based Service Definition for a description of BlackBerry Dynamics service definition.

Service Parameters

An AppKinetics service request can include a number of parameters, sent by the consumer. Service responses can also include parameters, sent by the provider to convey detailed results to the consumer. The parameters in a request or response are always provided to the application as a single object. AppKinetics supports a number of types of service parameter object.

BlackBerry Dynamics service definitions declare the expected types of parameter object for requests and responses for each method in a service. The BlackBerry Dynamics service definition language uses platform-independent terms for the declaration. The terms, and the native types that would be used to represent a parameter of that type, are listed in the following table.

Service Definition Native
string

java.lang.String

number

java.lang.Double

integer

java.lang.Integer

boolean

java.lang.Boolean

null

null

UInt8Array

byte[]

array

java.util.ArrayList of any of the simple types listed above.

object

java.util.Map of key-value pairs, with any of the above types as values.

Note that the service identifier, version, and method name are not service parameters as such and are not included in the parameters object.

Error responses can include additional details of the error condition. For example, if a parameter exceeds a maximum value, then the additional details could include the value of the maximum. Additional details are specified in the service definition, per condition, in the same way as service parameters. Additional detail values are handled as attributes of an Object property, in a specific class used for service errors, GDServiceError .

File Attachments

An AppKinetics service request can include a number of file attachments specified by the consumer. Service responses can also include file attachments, if these are sent by the provider as results.

File attachments are sent from the secure store of one application, and copied to the secure store of the other application. Deletion of the recipient's copy of the file is the responsibility of the recipient application. The AppKinetics system doesn't delete copies of files that were attached to a request or response.

In the programming interface, the sending application specifies file attachments as paths in its secure store. The AppKinetics system copies the files to the receiving application's secure store, and then invokes a callback in the receiving application. The callback is passed the paths of the copies, which it can then open in the usual manner.

The AppKinetics system uses the following naming convention to construct the paths of the receiving application's copies.
Inbox Directory/ Sender/ Reference time/ Original Path
Where:
Sender is the native application identifier of the sending application.
Reference time is the date and time at which the AppKinetics system started handling the file attachments, down to a millisecond resolution.

Note that all the files attached to a particular service request or response will be placed under one directory. This means that the receiving application can delete all these files in a single operation, by deleting the directory.

The AppKinetics system supports the sending of empty files in the current release, but did not in some earlier releases.

See also
BlackBerry Dynamics File I/O Package for the secure file system programming interface.

Foreground Execution

An AppKinetics service request can specify a preference that the application that provides the service executes in foreground in order to process the request. This could be used when request processing always requires user interaction, for example if the service is a special web browser or document editor. See the option parameter of the sendTo (GDServiceClient) method.

Similarly, an AppKinetics service response can specify a preference that the service consumer application executes in foreground in order to process the response. This might be used to return the original application to the foreground. See the option parameter of the replyTo (GDService) method.

It is also possible that a service provider itself determines its need to execute in foreground in order to process a particular request, after the request has been received. This is supported in AppKinetics by use of the front request programming interface.

The front request interface has two parts: send and receive. In principle, any BlackBerry Dynamics application can send a front request to any other BlackBerry Dynamics application, and any BlackBerry Dynamics application could receive a front request from any other BlackBerry Dynamics application. In practice, a front request is only sent to the consumer of a service by the provider of the service.

The following scenario illustrates the typical sequence of events in which front request is utilized.

  1. Service consumer application sends a request that is to be executed in background.
  2. Service provider application receives the request but determines that processing can only take place in foreground.
  3. Service provider sends a front request to the service consumer. See under Front Request Programming Interface, below, for details.
  4. Service consumer receives the front request. See under Front Request Programming Interface, below, for details.
  5. Service consumer brings the provider to the foreground, by calling the bringToFront method.
  6. Service provider completes processing of the original request.

Note that the service consumer could also leave the provider in background, in which case the service request would be expected to fail in some way.

A service provider might need to process a service request in foreground because:

  • User interaction is necessary, and this wasn't predicted in the service consumer before the service request was sent.
  • The time needed to process the request exceeds the time that is likely to be allowed to the provider to run in background.

In general, only the application that is currently running in foreground can bring another application to the foreground. In the scenario that neither the service consumer nor provider are in foreground, for example because the user chose to take a call or started a third application, then neither application can be brought to foreground by the other.

Front Request Programming Interface

The programming interface for front request is defined as a BlackBerry Dynamics service within AppKinetics.

The formal service definition of front request is as follows.

{
"service-id": "com.good.gd.icc",
"version": "1.0.0.0",
"title": "ICC Service ",
"description": "ICC is a special Good Dynamics service created by Good
Technology. This service is for control of the Inter-Container Communication
channel.",
"methods": {
"FRONT_REQ": {
"description": "The service consumer calls this method to request
that the service provider places the service consumer in foreground."
}
}
}

To send a front request, then, an application calls the sendTo method, with the following parameter values.

  • application the native application identifier of the other application, which typically will have been supplied in a onReceiveMessage invocation resulting from the original service request.
  • service the GDFrontRequestService constant, which always has the service-id value in the above.
  • version "1.0.0.0"
  • method "FRONT_REQ".
  • params null.
  • attachments null.
  • option GDICCForegroundOptions.NoForegroundPreference.

This causes a front request to be sent through the AppKinetics system.

The AppKinetics system will deliver the front request in the same way as any other service request, by invoking a callback in the provider application to which the request is addressed. Note that, in the typical case, the service provider here will actually be the application that was originally the service consumer. This means that any application that consumes a service whose provider might send back a front request must itself be a provider of the Front Request service. This includes meeting the generic requirements for all service provider applications, which are detailed under Service Provider Requirements, below.

The invoked callback's application code for handling a front request service request should be restricted to:

  • Identifying the received service request as a front request.
  • Any checks that are required to determine whether the application should yield foreground execution to the application that sent the front request.
  • A call to the bringToFront method, to be executed if all checks pass.

A minimal handler would identify a front request, make no checks, and then always call the bringToFront method.

Note that the front request service definition doesn't contain any service responses nor errors so the application mustn't send any. If the application code checks don't pass and foreground execution isn't to be yielded, then the application need take no action.

The following code snippet gives a simple utility function that could be utilized in a callback as outlined above.

private boolean consumeFrontRequestService(String serviceID, String application, String method, String version)
{
if(serviceID.equals(GDService.GDFrontRequestService) && version.equals("1.0.0.0")){
if(method.equals(GDService.GDFrontRequestMethod)){
try {
GDService.bringToFront(application);
} catch (GDServiceException e) {
// do something with error
}
return true;
}
}
return false;
}

Service Provider Requirements

The following requirements apply to BlackBerry Dynamics applications that are service providers.

Function as a service provider

To function as an AppKinetics service provider, a BlackBerry Dynamics application must:

  • Set the GDService listener to an object of a class that implements the GDServiceListener interface, typically this.
  • Register the AppKinetics activity and service on the device. This will normally be achieved by utilizing the mandatory BlackBerry Dynamics build-time configuration, as detailed in the GDAndroid class reference.

Note that an application that provides multiple services still instantiates only a single object of this class. The delegate of the object handles requests for all the services that the application provides.

Returned by service discovery query

To be on the list returned by a service discovery query, an application must be registered as a service provider. Register the application as a service provider:

  • In the enterprise management console, if an in-house application.
  • Via the application developer portal, if a partner application.

In either user interface, enter the full name of the Android package, for example "com.example.application.name".

Version returned by service discovery query

To have its version returned by a service discovery query, an application must also include its BlackBerry Dynamics entitlement version in its manifest. In the AndroidManifest.xml file, in the application configuration, set the value into a meta-data tag with the name GDApplicationVersion, as shown in the following snippet.

<meta-data android:name="GDApplicationVersion" android:value="1.0.0.0" />

The value of the GDApplicationVersion meta-data tag must be the same as the GDApplicationVersion attribute in the settings.json file in the assets/ folder of the application. If the values are not the same then the BlackBerry Dynamics runtime throws a GDInitializationError when the application starts.

Earlier releases requiring the AppKinetics receiving activity name

Applications built with some earlier releases of the BlackBerry Dynamics Software Development Kit for Android required that the full name of the AppKinetics receiving activity was entered instead of the package name. In some cases it won't be convenient to change the registered identifier. In those cases:

  • The application can continue to be registered with the full name of the AppKinetics receiving activity including package, for example "com.example.application.name.IccReceivingActivity".
  • The application code must have an explicit AppKinetics receiving activity, in the AndroidManifest.xml file and in its source code. See the GDIccReceivingActivity Class Reference for details.
See also
GDAndroid.getServiceProvidersFor for details of the service discovery programming interface.

Classes

enum  GDICCForegroundOptions
 Constants for specifying foreground execution preference. More...
 
class  GDService
 AppKinetics service provider. More...
 
class  GDServiceClient
 AppKinetics service consumer. More...
 
interface  GDServiceClientListener
 Handler for AppKinetics consumer events. More...
 
class  GDServiceError
 AppKinetics Error. More...
 
enum  GDServiceErrorCode
 AppKinetics system error codes. More...
 
class  GDServiceException
 AppKinetics Exception. More...
 
class  GDServiceHelper
 AppKinetics send Intent helper. More...
 
interface  GDServiceListener
 AppKinetics service provider implementation. More...
 
android