GDService Class Reference

AppKinetics service provider. More...

#import <BlackBerryDynamics/GD/GDServices.h>

Inheritance diagram for GDService:

Description

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) .

See also

AppKinetics Errors

GDServiceClient for the parts of the interface that are specific to service consumers.

getServiceProvidersFor: (GDiOS) for the service discovery programming interface.

AppKinetics

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 getServiceProvidersFor: (GDiOS) .
2. The consumer application calls sendTo (GDServiceClient) .
3. The GDServiceDidReceiveFrom 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 GDServiceClientDidReceiveFrom 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	NSString
number	NSNumber
integer	NSNumber
boolean	NSNumber
null	NSNull
UInt8Array	NSData
array	NSArray of any of the simple types listed above.
object	NSDictionary 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 entries in the userInfo dictionary in an NSError object.

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

GDFileManager 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) 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.

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: function.
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: 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:

• 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: function, to be executed if all checks pass.

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.

+ (BOOL)consumeFrontRequestService:(NSString*) serviceID forApplication:(NSString*) application forMethod:(NSString*) method withVersion:(NSString*)version
{
 if([serviceID isEqual:GDFrontRequestService] && [version isEqual:@"1.0.0.0"])
 {
     if([method isEqual:GDFrontRequestMethod])
     {
         [GDService bringToFront:application completion:^(BOOL success) { } error:nil];
         return YES;
     }
 }
 return NO;
}

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:

• Instantiate a single object of the GDService class.
• Set the delegate property to point to an object of a class that implements the GDServiceDelegate protocol, typically self.
• Register the AppKinetics URL type on the device. This will normally be achieved by utilizing the mandatory BlackBerry Dynamics build-time configuration, as detailed in the GDiOS 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 native bundle identifier of the application, for example "com.example.application.name". Different bundle identifiers can be entered for different device types.

See also

getServiceProvidersFor: (GDiOS) for details of the service discovery programming interface.

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...

Method Documentation

replyTo:withParams:bringClientToFront:withAttachments:requestID:error:

+ (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.

Parameters

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.

Returns

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.

bringToFront:completion:error:

+ (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.

Parameters

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.

Returns

YES if the completion code block will be invoked.

NO otherwise.

bringToFront:error:

+ (BOOL) bringToFront:		(nonnull NSString *)	application
error:		(NSError **)	error

Deprecated:

This function is deprecated and will be removed in a future release. Use GDService::bringToFront:completion:error: instead.

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.

Parameters

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.

Returns

YES if the specified application was brought to the foreground, based on the return code from the native layer.

NO otherwise.

Property Documentation

delegate

- (id<GDServiceDelegate>) delegate

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:

• Implement the GDServiceDelegate protocol.
• Process received service requests in accordance with the published interface of the service provided. The interface could be, for example, a BlackBerry Dynamics service definition.

The processing could include calling replyTo (GDService) to issue a service response.

---

The documentation for this class was generated from the following file:

• platform/apple/ios/build/BlackBerryDynamics.framework/Headers/GDServices.h