AppKinetics service consumer. More...
#import <GDServices.h>
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 (GDMac).
To function as an AppKinetics service consumer, a BlackBerry Dynamics application must:
GDServiceClient class.self.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.
| + (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.
| application | NSString 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: (GDMac) function. |
| service | NSString 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. |
| version | NSString containing the version of the service being requested. The value should correspond to a version of service that the service provider application offers. |
| method | NSString 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. |
| params | The service parameters object for the request. See under Service Parameters 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 request. See under File Attachments in the GDService class reference. |
| option | GDTForegroundOption 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. |
| requestID | Location of a an NSString pointer for returning the unique identifier assigned to the request by the AppKinetics system. |
| error | For returning an NSError object if an error occurs. If nil, no object will be returned. |
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:
GDServiceClientDidFinishSendingTo: callback in the sending application isn't subsequently invoked.Cancellation will fail if the service request has already been delivered, in which case the above callback invocations would take place.
| requestID | NSString containing the identifier of the request to be cancelled, or nil to cancel all requests to the specified recipient. |
| application | NSString containing the native application identifier of the recipient to which the request or requests were sent. |
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 | |
| 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 cannot be used 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. - (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.