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

<GDServiceClientDelegate> Protocol Reference

Handler for AppKinetics consumer events. More...

#import <GDServices.h>

List of all members.

Public Member Functions


Detailed Description

Responses to AppKinetics service requests are handled by creating a class that implements this protocol.

This class is part of the service consumer side of the AppKinetics programming interface.

The GDServiceClientDidReceiveFrom callback would be invoked after the application had sent a service request to a service provider, and the provider had responded or an error had occurred.

See also:
The GDService class reference for an overall description of AppKinetics.

This class also includes a callback that is invoked when transmission of a service request completes.

Callback Invocation Sequence

The callbacks in this class will be invoked in the following sequence when a service response is received.

  1. GDServiceWillStartReceivingFrom:numberOfAttachments:forRequestID: once, if the service request has any file attachments.
  2. GDServiceWillStartReceivingFrom:attachmentPath:fileSize:forRequestID: once for each file attachment.
  3. GDServiceClientDidReceiveFrom once.

The first two of these callbacks enable the application to display a receiving status in its user interface. No action should be taken on any attachment files until the last callback, GDServiceClientDidReceiveFrom.


Member Function Documentation

- (void) GDServiceClientDidReceiveFrom: (NSString *)  application
withParams: (id)  params
withAttachments: (NSArray *)  attachments
correspondingToRequestID: (NSString *)  requestID 
[required]

This callback is invoked when a response is received to an AppKinetics service request. The parameters give the details of the service response.

For an overall description of AppKinetics see the GDService class reference.

See under Callback Invocation Sequence, above, for the position of this callback in the order of service response callbacks.

A service response may be received in relation to a call to sendTo (GDServiceClient) that was accepted by the AppKinetics system.

The response can include file attachments and a results object from the provider application. Check the type of the results object to determine whether the service request succeeded.

If the results object is of type NSError then the service request failed. The error domain of the object will either be the GDServicesErrorDomain value, in the case of a generic AppKinetics failure, or a value that is specific to the service or to the provider application. In any case, the NSError object should have a suitable error code, a localizedDescription, and possibly additional data in its userInfo dictionary. See also the NSError class reference on the apple.com developer website for the full programming interface.

If the results object isn't of type NSError then the service request succeeded. In that case the results object will be of a valid service parameter type, as defined under Service Parameters in the GDService class reference.

Parameters:
applicationNSString containing the native application identifier of the provider application to which the original service request was sent.
paramsThe results object, as returned by the provider application.
attachmentsNSArray of NSString objects containing the paths of files that were attached to the service response. See under File Attachments in the GDService class reference.
requestIDNSString containing the ID assigned to the original service request. An application that makes multiple concurrent service requests can use this value to tie the response back to the original request. The application must have retained the ID from when sendTo (GDServiceClient) was originally called.
- (void) GDServiceClientDidStartSendingTo: (NSString *)  application
withFilename: (NSString *)  filename
correspondingToRequestID: (NSString *)  requestID 
[optional]

This callback is invoked when delivery of a service request file attachment by the AppKinetics system starts. The path of the file is passed as a parameter.

Invocation of this callback notifies the application that the AppKinetics system has started transferring the data in the file to the recipient of the service request.

The function that is invoked could display a sending status in its user interface. The sending status could be cleared on receipt of the GDServiceClientDidFinishSendingTo: callback.

See also:
sendTo (GDServiceClient) for details of sending service requests.
Parameters:
applicationNSString containing the native application identifier of the recipient of the file.
filenameNSString containing the path in the secure store of the file that is now being sent.
requestIDNSString containing the unique identifier of the service request to which the file is attached.
- (void) GDServiceClientDidFinishSendingTo: (NSString *)  application
withAttachments: (NSArray *)  attachments
withParams: (id)  params
correspondingToRequestID: (NSString *)  requestID 
[optional]

This callback is invoked when the delivery of an AppKinetics service request completes.

Invocation of this callback notifies the application that:

  • Any files that were attached to the service request have been copied to the secure store of the service provider.
  • An independent copy of the parameters of the request, if any, has been made available to the service provider.

The function that is invoked can delete or modify any of the original file attachments, and free any resources used to hold the request parameters.

See also:
sendTo (GDServiceClient) for details of sending service requests.
Parameters:
requestIDNSString containing the unique identifier of the service request whose sending has completed.
attachmentsNSArray of NSString objects containing the paths of any files that were attached to the service request.
paramsReference to the parameters object of the service request.
applicationNSString containing the native application identifier of the application to which the service request was sent.
- (void) GDServiceClientWillStartReceivingFrom: (NSString *)  application
numberOfAttachments: (NSUInteger)  attachments
forRequestID: (NSString *)  requestID 
[optional]

This callback is invoked when file attachments are about to be received through the AppKinetics system. The number of files that are about to be received is passed as a parameter.

This callback will be invoked once per service response that has attachments. See under Callback Invocation Sequence, above, for its position in the order of service response callbacks.

The function that is invoked could display a receiving status in its user interface. The status could be cleared on receipt of the GDServiceClientDidReceiveFrom callback.

Parameters:
applicationNSString containing the native application identifier of the provider application that sent the service response to which the files are attached.
attachmentsNSUInteger number of files that are about to be received, always one or more. This callback isn't invoked for service responses that have no attachments.
requestIDNSString containing the unique identifier of the original service request, the response to which the files are attached.
- (void) GDServiceClientWillStartReceivingFrom: (NSString *)  application
attachmentPath: (NSString *)  path
fileSize: (NSNumber *)  size
forRequestID: (NSString *)  requestID 
[optional]

This callback is invoked when an individual file attachment is about to be received through the AppKinetics system. The path and size of the file that is about to be received are passed as parameters.

This callback will be invoked once per attachment. See under Callback Invocation Sequence, above, for its position in the order of service response callbacks.

The function that is invoked could display or update a receiving status in its user interface. The status could be cleared on receipt of the GDServiceClientDidReceiveFrom callback.

Parameters:
applicationNSString containing the native application identifier of the provider application that sent the service response to which the file is attached.
pathNSString containing the path of the attachment. The value will be the same as one of the elements in the attachments parameter passed to the subsequent GDServiceClientDidReceiveFrom invocation.
sizeNSNumber representing the size of the file in bytes. The value will be an unsigned long long.
requestIDNSString containing the unique identifier of the original service request, the response to which the files are attached.

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