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

<GDServiceDelegate> Protocol Reference

AppKinetics service provider implementation. More...

#import <GDServices.h>

List of all members.

Public Member Functions


Detailed Description

Service requests received within the AppKinetics system are handled by creating a class that implements this protocol. Implementation is mandatory for applications that provide services. An instance of the class must be set as the observer for inbound service requests, by setting the delegate property of the application's GDService instance.

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

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

Callback Invocation Sequence

The callbacks in this class will be invoked in the following sequence when a service request 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. GDServiceDidReceiveFrom 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, GDServiceDidReceiveFrom.

See also:
The GDService class reference for:
  • An overall description of AppKinetics.
  • A list of requirements for applications that provide services, under Service Provider Requirements

Member Function Documentation

- (void) GDServiceDidReceiveFrom: (NSString *)  application
forService: (NSString *)  service
withVersion: (NSString *)  version
forMethod: (NSString *)  method
withParams: (id)  params
withAttachments: (NSArray *)  attachments
forRequestID: (NSString *)  requestID 
[required]

This callback is invoked when a service request is sent to the application within the AppKinetics system. The parameters with which this function is called give the details of the service request.

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

When this callback is invoked, the application must:

  1. Check that the service request is valid.
  2. Process the request, if valid.
  3. If required by the service definition or other published interface, respond to the request with a success or failure result by calling the replyTo (GDService) function.

If the application determines that a service request is invalid then the application should return an error in the replyTo call. For some check failures, the application must set a particular code in the returned error. These are documented in the Parameters section, below.

See also:
AppKinetics Errors.
Parameters:
applicationNSString containing the native application identifier of the consumer application that sent the service request. The application is not required to check the value, but may do so. For example, the application could be coded only to process service requests from a known set of consumer applications, and to fail requests from unknown applications.
serviceNSString containing the identifier of the service being requested. The application must check the value. If the application does not offer the requested service then the GDServicesErrorServiceNotFound code must be set.
versionNSString containing the version identifier of the service being requested. The application must check the value. If the application does not offer the requested service version then the GDServicesErrorServiceVersionNotFound code must be set.
methodNSString containing the name of the method within the service request. The application must check the value. If the application does not offer the requested method then the GDServicesErrorMethodNotFound code must be set.
paramsThe service parameters in the request, sent by the consumer application. See under Service Parameters in the GDService class reference. If the service parameters are in some way invalid then a service-specific error code could be set, or this could be handled in some other way according to the service definition.
attachmentsNSArray of NSString objects containing the paths of files that were attached to the service request. See under File Attachments in the GDService class reference. If the file attachments are in some way invalid then a service-specific error code could be set in the results object, or this could be handled in some other way according to the service definition.
requestIDNSString containing the unique identifier assigned to this service request by the AppKinetics system. The application must pass this value as the requestID parameter in the replyTo (GDService) call if it responds to the request.
- (void) GDServiceDidStartSendingTo: (NSString *)  application
withFilename: (NSString *)  filename
correspondingToRequestID: (NSString *)  requestID 
[optional]

This callback is invoked when delivery of a service response 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 response.

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

See also:
replyTo (GDService) for details of sending a service response.
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 ID of the original service request, the response to which the file is attached.
- (void) GDServiceDidFinishSendingTo: (NSString *)  application
withAttachments: (NSArray *)  attachments
withParams: (id)  params
correspondingToRequestID: (NSString *)  requestID 
[optional]

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

Invocation of this callback notifies the application that:

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

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

See also:
replyTo (GDService) for details of sending service responses.
Parameters:
requestIDNSString containing the unique identifier of the service request to which the sending of the response has completed.
attachmentsNSArray of NSString objects containing the paths of any files that were attached to the service response.
paramsReference to the parameters object of the service response.
applicationNSString containing the native application identifier of the application to which the service response was sent.
- (void) GDServiceWillStartReceivingFrom: (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 request that has attachments. See under Callback Invocation Sequence, above, for its position in the order of service request callbacks.

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

Parameters:
applicationNSString containing the native application identifier of the consumer application that sent the service request 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 requests that have no attachments.
requestIDNSString containing the unique identifier of the service request to which the files are attached.
- (void) GDServiceWillStartReceivingFrom: (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 request callbacks.

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

Parameters:
applicationNSString containing the native application identifier of the consumer application that sent the service request 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 GDServiceDidReceiveFrom 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 service request to which the file is attached.

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