BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient Interface Reference

More...

Public Member Functions
void	BringToFront (string application)
Task	BringToFrontAsync (string application)
string	SendTo (string application, string service, string version, string method, object parameters, IBBDFileEntry[] attachments, BBDICCForegroundOptions option)

Events
EventHandler< ClientMessageSentEventArgs >	ClientMessageSent
EventHandler< ReceivingAttachmentsEventArgs >	ReceivingAttachments
EventHandler< ReceivingAttachmentFileEventArgs >	ReceivingAttachmentFile
EventHandler< ReceiveClientMessageEventArgs >	ReceiveClientMessage

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.

The functions in this programming interface cannot be used until BlackBerry Dynamics authorization processing is complete

Service Consumer Requirements

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

• Instantiate a single object of the IBBDServiceClient class.
• Register the AppKinetics URL type on the device. This will normally be achieved by utilizing the mandatory BlackBerry Dynamics build-time configuration, as detailed on the Build-Time Configuration page.

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

Member Function Documentation

BringToFront()

void BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.BringToFront

(

string

application

)

Deprecated:

This method is deprecated and will be removed in a future release. Use BringToFrontAsync 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.

This function cannot be used outside the context of service request processing.

Parameters

application

String containing the native application identifier of the application to be brought to the foreground.

Exceptions

Errors.BBDServiceException

Thrown when the specified application wasn't brought to the foreground, based on the return code from the native layer.

BringToFrontAsync()

Task BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.BringToFrontAsync

(

string

application

)

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.

This function cannot be used outside the context of service request processing.

Parameters

application

String containing the native application identifier of the application to be brought to the foreground.

Exceptions

Errors.BBDServiceException

Thrown when the specified application wasn't brought to the foreground, based on the return code from the native layer.

SendTo()

string BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.SendTo	(	string	application,
		string	service,
		string	version,
		string	method,
		object	parameters,
		IBBDFileEntry[]	attachments,
		BBDICCForegroundOptions	option
	)

Call this method 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.

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.

Returns

String containing a unique identifier assigned to the request by the AppKinetics system.

Parameters

application	String containing the package name of the service provider application. A suitable value could be obtained from the Address field of a IBBDServiceProvider object returned by the GetServiceProviders method.
service	String 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	String containing the version of the service being requested. The value should correspond to a version of service that the service provider application offers.
method	String 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.
parameters	The service parameters object for the request.
attachments	Array of IBBDFileEntry objects containing the referemces to the files in the BlackBerry Dynamics secure file system that are to be attached to the request.
option	BBDICCForegroundOptions specifying the foreground execution preference for processing of the request.

Exceptions

Errors.BBDServiceException

Thrown when the request isn't accepted by the AppKinetics system.

Event Documentation

ClientMessageSent

EventHandler<ClientMessageSentEventArgs> BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.ClientMessageSent

This event occurs whenever the delivery of an AppKinetics service request.

This event 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 method that is invoked can delete or modify any of the original file attachments, and free any resources used to hold the request parameters.

ReceiveClientMessage

EventHandler<ReceiveClientMessageEventArgs> BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.ReceiveClientMessage

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

A service response may be received in relation to a call to IBBDServiceClient.SendTo 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 BBDServiceError then the service request failed. The object will have either an AppKinetics system error code, or a custom error code from the service provider. Additional data about the error may be in the details attribute. See BBDServiceError for details.

If the results object isn't of type BBDServiceError then the service request succeeded. In that case the results object will be of a valid service parameter type.

ReceivingAttachmentFile

EventHandler<ReceivingAttachmentFileEventArgs> BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.ReceivingAttachmentFile

Occurs 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 event will be invoked once per attachment.

ReceivingAttachments

EventHandler<ReceivingAttachmentsEventArgs> BBDXamarinForms.Common.Interfaces.AppKinetics.IBBDServiceClient.ReceivingAttachments

This event occurs 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.

Occurs once per service response that has attachments.

This event isn't invoked for service responses that have no attachments.