• BlackBerry Dynamics
  • Runtime library for Android applications
  • 9.1.0.122
GDServiceClient Class Reference

AppKinetics service consumer. More...

Description

This class is mandatory for AppKinetics service consumer applications. This class also includes the programming interface for sending AppKinetics service requests.

To utilize this interface, the application must meet the requirements listed under Service Consumer Requirements, below.

For an overall description of AppKinetics see the icc package reference.

The methods in this programming interface cannot be used until BlackBerry Dynamics authorization processing is complete, see under GDAndroid.authorize.

See also
GDServiceError

Service Consumer Requirements

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

  • Instantiate a single object of the GDServiceClient class.
  • Set the listener to an instance of a class that implements the GDServiceClientListener 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 on the Build-Time Configuration page.

Note that an application that consumes multiple services still instantiates only a single object of this class. The listener of the object handles responses from all the services that the application consumes.

Static Public Member Functions

static String sendTo (String application, String service, String version, String method, Object params, String[] attachments, GDICCForegroundOptions option) throws GDServiceException
 Send a service request. More...
 
static void bringToFront (String application) throws GDServiceException
 Bring another application to the foreground. More...
 
static void setServiceClientListener (GDServiceClientListener listener) throws GDServiceException
 Set the listener for responses service requests. More...
 

Member Function Documentation

◆ sendTo()

static String sendTo ( String  application,
String  service,
String  version,
String  method,
Object  params,
String[]  attachments,
GDICCForegroundOptions  option 
) throws GDServiceException
static

Call this method to send an AppKinetics service request. The request includes a method name, and can include service parameters and file attachments to be conveyed to the provider application.

For an overall description of AppKinetics see the icc package reference.

The AppKinetics system will assign a unique identifier to the service request and make this available to the application. This value will also be returned with any response to the request. An application that makes multiple concurrent requests can use the request identifier to match responses with requests.

This method may perform storage or network I/O, and therefore should not be called on the UI thread.

Parameters
applicationString containing the package name of the service provider application. A suitable value could be obtained from the address field of a GDServiceProvider object returned by the GDAndroid.getServiceProvidersFor method.
serviceString containing the identifier of the service to which the request is being sent. The value should correspond to a service that the service provider application offers.
versionString containing the version of the service being requested. The value should correspond to a version of service that the service provider application offers.
methodString containing the name of the method, within the service, that is being requested. The value should correspond to the name of a method that the service provider application offers.
paramsThe service parameters object for the request. See under Service Parameters in the icc package reference.
attachmentsArray of String objects containing the paths of files in the BlackBerry Dynamics secure file systemthat are to be attached to the request. See under File Attachments in the icc package reference.
optionGDICCForegroundOptions specifying the foreground execution preference for processing of the request:
GDICCForegroundOptions.PreferPeerInForeground for the provider application being in the foreground.
GDICCForegroundOptions.PreferMeInForeground for this application being in the foreground.
GDICCForegroundOptions.NoForegroundPreference to specify that there is no preference.
See also the notes under Foreground Execution in the icc package reference.
Returns
String containing a unique identifier assigned to the request by the AppKinetics system.
The result of the service request could be notified to the application by invocation of its GDServiceClientListener.onReceiveMessage callback, depending on the service, and whether the request is able to be delivered. See GDServiceError .
Exceptions
GDServiceExceptionif the request isn't accepted by the AppKinetics system.

◆ bringToFront()

static void bringToFront ( String  application) throws GDServiceException
static

Call this method to bring another application to the foreground. This would typically be used when a service provider application has requested foreground execution to process a request that has already been sent. See under Foreground Execution in the icc package reference for details. Don't use this method outside the context of service request processing. This method cannot specify which part of the other application's user interface will be opened, i.e. which activity.

Parameters
applicationString containing the native application identifier of the application to be brought to the foreground.
Exceptions
GDServiceExceptionif the specified application wasn't brought to the foreground, based on the return code from the native layer.

◆ setServiceClientListener()

static void setServiceClientListener ( GDServiceClientListener  listener) throws GDServiceException
static

When a response to an AppKinetics service request is received, the BlackBerry Dynamics runtime dispatches an event to a callback method within the application.

Call this method to set the listener to an instance of a class in the application that contains the code for the required callback method , i.e. a class that implements the GDServiceClientListener interface. The class should be coded to handle responses from service providers to which the application sends service requests.

Note that there is only one listener, that handles all service responses received by the application.

Parameters
listenerInstance of a GDServiceClientListener object to set as the listener, typically this.