AppKinetics secure inter-application data exchange. More...
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.
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.
A service provided by an application may conform to a declared service definition. The declaration, if there is one, will specify the following.
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.
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 |
|
number |
|
integer |
|
boolean |
|
null |
|
UInt8Array |
|
array |
|
object |
|
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 .
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.
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.
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:
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.
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.
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:
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.
The following requirements apply to BlackBerry Dynamics applications that are service providers.
To function as an AppKinetics service provider, a BlackBerry Dynamics application must:
GDSer
vice
listener to an object of a class that implements the GDServiceListener
interface, typically this
.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.
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 either user interface, enter the full name of the Android package, for example "com.example.application.name".
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.
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.
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:
AndroidManifest.xml
file and in its source code. See the GDIccReceivingActivity Class Reference for details.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... | |