blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Static Public Member Functions | Properties

GDServiceClient Class Reference

AppKinetics service consumer. More...

#import <GDServices.h>

List of all members.

Static Public Member Functions

Properties


Detailed 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 GDService class reference.

The functions in this programming interface cannot be used until BlackBerry Dynamics authorization processing is complete, see under authorize (GDiOS).

See also:
AppKinetics Errors

Service Consumer Requirements

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

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


Member Function Documentation

+ (BOOL) sendTo: (NSString *)  application
withService: (NSString *)  service
withVersion: (NSString *)  version
withMethod: (NSString *)  method
withParams: (id)  params
withAttachments: (NSArray *)  attachments
bringServiceToFront: (GDTForegroundOption option
requestID: (NSString **)  requestID
error: (NSError **)  error 

Call this function 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 GDService class 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.

Parameters:
applicationNSString containing the native bundle identifier of the service provider application. A suitable value could be obtained from the address field of a GDServiceProvider object returned by the getServiceProvidersFor: (GDiOS) function.
serviceNSString 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.
versionNSString containing the version of the service being requested. The value should correspond to a version of service that the service provider application offers.
methodNSString 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 GDService class reference.
attachmentsNSArray of NSString objects containing the paths of files in the BlackBerry Dynamics secure file system that are to be attached to the request. See under File Attachments in the GDService class reference.
optionGDTForegroundOption specifying the foreground execution preference for processing of the request:
GDEPreferPeerInForeground for the provider 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.
requestIDLocation of a an NSString pointer for returning the unique identifier assigned to the request by the AppKinetics system.
errorFor returning an NSError object if an error occurs. If nil, no object will be returned.
Returns:
YES if the request was accepted by the AppKinetics system. The result of the service request could be notified to the application by invocation of its GDServiceClientDidReceiveFrom callback, depending on the service, and whether the request is able to be delivered. See AppKinetics Errors.
NO Otherwise. The error location, if provided, will be set to point to an NSError object with details of the error condition.
+ (BOOL) cancelRequest: (NSString *)  requestID
toApplication: (NSString *)  application 

Call this function to cancel AppKinetics service requests. The application can only cancel requests that it sent, not requests sent by other applications.

This function can be used to cancel a single service request. Specify the unique identifier of the request, which will have been generated when sendTo (GDServiceClient) was called.

This function can also be used to cancel all service requests addressed to a specific application.

Cancellation of a request can succeed or fail. If cancellation succeeds:

  • The GDServiceClientDidFinishSendingTo: callback in the sending application isn't subsequently invoked.
  • The GDServiceClientDidReceiveFrom callback in the receiving application won't be invoked.

Cancellation will fail if the service request has already been delivered, in which case the above callback invocations would take place.

Parameters:
requestIDNSString containing the identifier of the request to be cancelled, or nil to cancel all requests to the specified recipient.
applicationNSString containing the native application identifier of the recipient to which the request or requests were sent.
Returns:
YES if one or more requests were cancelled.
NO otherwise. This function returns NO if there is no service request that matches the specified values, or if none of the requests that match could be cancelled.
+ (BOOL) bringToFront: (NSString *)  application
completion: (BOOL)  completion
error: (NSError **)  error 

Call this function 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 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:
applicationNSString containing the native application identifier of the application to be brought to the foreground.
completionCode 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.
errorFor 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.
+ (BOOL) bringToFront: (NSString *)  application
error: (NSError **)  error 
Deprecated:
This function is deprecated and will be removed in a future release. Use bringToFront: with a completion block instead.

Call this function 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 GDService class reference for details.

Don't use this function outside the context of service request processing.

Parameters:
applicationNSString containing the native application identifier of the application to be brought to the foreground.
errorFor 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

- (id<GDServiceClientDelegate>) delegate [read, write, assign]

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

Set this property to an instance of a class in the application that contains the code for the required callback function , i.e. a class that implements the GDServiceClientDelegate protocol. The class should be coded to handle responses from service providers to which the application sends service requests.

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


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