AppKinetics service provider. More...
#import <BlackBerryDynamics/GD/GDServices.h>
This class is mandatory for service provider applications within the AppKinetics system. This class also includes the programming interface for sending AppKinetics service responses. This interface would be utilized in the code of the delegate of this class.
For an overall description of AppKinetics, see below. To utilize this programming interface, the application must meet the requirements listed under Service Provider Requirements.
The functions in the AppKinetics programming interface utilize NSError
in a conventional way. Function calls accept as a parameter the location of a pointer to NSError
, i.e. a pointer to a pointer, with type NSError**
. The location may be nil
. If the location isn't nil
, and an error occurs, the BlackBerry Dynamics runtime overwrites the pointer at the specified location with the address of an object that describes the error that occurred.
The functions in this interface cannot be used until BlackBerry Dynamics authorization processing is complete, see under authorize (GDiOS) .
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 entries in the userInfo
dictionary in an NSError
object.
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) function.
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) function.
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:
function, with the following parameter values.
sendTo:
the native application identifier of the other application, which typically will have been supplied in a GDServiceDidReceiveFrom:
invocation resulting from the original service request.withService:
the GDFrontRequestService
constant, which always has the service-id
value in the above.withVersion:
"1.0.0.0"
withMethod:
"FRONT_REQ"
.withParams:
nil
.withAttachments:
nil
.bringServiceToFront:
GDENoForegroundPreference
.requestID:
Location of a local pointer or nil
, as for any call to sendTo:
error:
Location of a local pointer or nil
, as for any call to sendTo:
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: function.
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
class.delegate
property to point to an object of a class that implements the GDServiceDelegate
protocol, typically self
.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 native bundle identifier of the application, for example "com.example.application.name". Different bundle identifiers can be entered for different device types.
Class Methods | |
(BOOL) | + replyTo:withParams:bringClientToFront:withAttachments:requestID:error: |
Send a response or error message. More... | |
(BOOL) | + bringToFront:completion:error: |
Bring another application to the foreground. More... | |
(BOOL) | + bringToFront:error: |
Bring another application to the foreground (deprecated). More... | |
Properties | |
id< GDServiceDelegate > | delegate |
Handler that implements the services provided by the application. More... | |
+ (BOOL) replyTo: | (nullable NSString *) | application | |
withParams: | (nullable id) | params | |
bringClientToFront: | (GDTForegroundOption) | option | |
withAttachments: | (nullable NSArray< NSString * > *) | attachments | |
requestID: | (NSString *) | requestID | |
error: | (NSError **) | error | |
Call this function to respond to a consumer application from which an AppKinetics service request has been received. The response can include a results object and file attachments to be conveyed to the consumer application. The results object will notify the consumer of the success or failure of the request.
For an overall description of AppKinetics see the GDService class reference.
If the request failed for any reason, pass an NSError
as the results object. Populate the NSError
with a suitable error code and a localizedDescription
. Add any additional data to the userInfo
dictionary. The error domain will be set by the BlackBerry Dynamics runtime to be the same as the service identifier. See also the NSError class reference on the apple.com developer website.
If the request succeeded then pass a results object of a valid service parameter type, as defined under Service Parameters in the GDService class reference.
application | NSString containing the native application idenitifer of the consumer, as supplied in the original service request. |
params | NSObject for the results object. |
option | GDTForegroundOption specifying the foreground execution preference after delivery of the response:GDEPreferPeerInForeground for the consumer application being in the foreground.GDEPreferMeInForeground for this application being in the foreground.GDENoForegroundPreference to specify that there is no preference.See also the notes under Foreground Execution in the GDService class reference. |
attachments | NSArray of NSString objects containing the paths of files in the BlackBerry Dynamics secure file system that are to be attached to the response. See under File Attachments in the GDService class reference. |
requestID | NSString containing the identifier of the service request to which this is a response. The identifier will have been passed as a parameter to the delegated handler that implements the service. |
error | For returning an NSError object if an error occurs. If nil , no object will be returned. Note that this means errors that occur when attempting to deliver the response, and is not a reference to the results object. |
YES
if the response was accepted by the AppKinetics system. NO
otherwise. The error
location, if provided, will be set to point to an NSError
object with details of the error condition. + (BOOL) bringToFront: | (nonnull NSString *) | application | |
completion: | (void(^)(BOOL)) | completion | |
error: | (NSError **) | error | |
Call this function to bring another application to the foreground. This could be used when the application is a service provider, to bring the service consumer back to the foreground without sending a response. See under Foreground Execution in the GDService class reference for details.
This function is asynchronous. Success or failure is returned by invocation of a code block specified in the completion
parameter. The block will receive one parameter of type BOOL
and should have no return value. It may or may not be executed on the main thread.
Don't use this function outside the context of service request processing.
application | NSString containing the native application identifier of the application to be brought to the foreground. |
completion | Code block to execute when the operation completes or fails. It receives one parameter:YES if the other application was brought to the foreground, based on the return code from the native layer.NO otherwise. |
error | For returning an NSError object if an error occurs. If nil , no object will be returned. |
YES
if the completion
code block will be invoked. NO
otherwise. + (BOOL) bringToFront: | (nonnull NSString *) | application | |
error: | (NSError **) | error | |
Call this function to bring another application to the foreground. This could be used when the application is a service provider, to bring the service consumer back to the foreground without sending a response. See under Foreground Execution in the GDService class reference for details.
Don't use this function outside the context of service request processing.
application | NSString containing the native application identifier of the application to be brought to the foreground. |
error | For returning an NSError object if an error occurs. If nil , no object will be returned. |
YES
if the specified application was brought to the foreground, based on the return code from the native layer. NO
otherwise.
|
readwriteatomicweak |
When an AppKinetics service request is received, the BlackBerry Dynamics runtime dispatches an event to an observer within the application. Set this property to the observer object instance in the application.
The observer object must:
The processing could include calling replyTo (GDService) to issue a service response.