This class is mandatory for service provider applications within the BlackBerry Inter-Container Communication (ICC) system. This class also includes the specific API for sending ICC service responses.

For an overall description of ICC, see under BlackBerry Inter-Container Communication below. To utilize this API the application must meet the requirements listed under Service Provider Requirements.

The functions in this API cannot be used until BlackBerry Dynamics authorization processing is complete, see under GDWindows::Authorize.

BLACKBERRY INTER-CONTAINER COMMUNICATION

The BlackBerry Inter-Container Communication (ICC) system is a means of exchanging data securely between two BlackBerry Dynamics applications running on the same device. The security of data is not compromised during exchange.

Interaction in the ICC system follows a service consumer-provider model. One application initiates communication by sending a service request to another. The initiating application is the service consumer. The application that receives the request is the service provider.

After receiving the service request, the provider executes the necessary processing and could then send a service response back to the consumer. Both the service request and the service response, if any, can contain a number of parameters and file attachments. See under Service Parameters and File Attachments, below.

The sequence of APIs used in a typical ICC interaction is as follows:

1. The consumer application calls the service discovery API.
2. The consumer application calls GDServiceClient::SendRequestAsync(String, String, String, String, IDictionaryString, String, IListIGDStorageFile, String)
3. The GDService::HandleRequest event in the provider application is invoked by the ICC system.
4. The provider application executes any required processing and then calls GDService::SendResponseAsync(String, String, IDictionaryString, String, IListIGDStorageFile, GDServiceError)
5. The GDServiceClient::HandleResponse event in the consumer is invoked by the ICC system.

Note that an ICC interaction can be initiated with any BlackBerry Dynamics application whose native application identifier is known in the service consumer. The identifier could be known by being present in the application code or, as shown in the above, could be obtained at run time by using BlackBerry Dynamics service discovery. See GDWindows::GetServiceProvidersAsync(GDServiceProviderType, String, String) for details of the service discovery API.

Note that the service provider does not necessarily send a response, i.e. the call to GDService::SendResponseAsync(String, String, IDictionaryString, String, IListIGDStorageFile, GDServiceError) and subsequent invocation of the callback in the consumer do not necessarily take place. The service definition specifies when and whether the provider sends a response, see under Service Definition, below.

The data for requests and responses is sent across an encrypted payload file. The file is created and maintained as necessary by the BlackBerry Dynamics Runtime. This is transparent to the applications, although not always to the end user since the device may sometimes "flip" between applications during ICC interaction. See also the Foreground Execution section, below.

The ICC system cannot be used when running under Enterprise Simulation mode.

By default the ICC system of the SDK for Windows Universal Platform (UWP) can not communicate with ICC system of the SDK for Windows 8.1. See the SDK interoperability related section for instructions on how to enable ICC compatibility mode, here.

SERVICE DEFINITION

The service provided by an application may conform to a declared service definition. The declaration, if there is one, will specify the following:

• Name of the service, conventionally a reversed Internet domain followed by a number of sub-domains separated by full stops (periods). Formally, service names conform to the <subdomain> format defined in section 2.3.1 of RFC1035.
• Methods that comprise the service.
• Expected parameters to service requests, per method.
• Expected file attachments to service requests, per method
• Whether and in what circumstances service responses will be issued, per method.
• What types of service response will be issued, per method.
• Expected parameters to service responses, per method and per type.
• Expected file attachments to service responses, per method and per type.
• Error conditions that are specific to the service.

An application that registers as providing a service for which there is a definition must adhere to the definition. Similarly, an application that consumes a service that is based on a declared definition should only send requests that conform to the definition.

The service definition for a public service may be published to the BlackBerry Dynamics Network (GDN) website. The published definition may include a link to a more detailed API for the service. In any case, the service API may be obtained from the developer of a service provider application, or from the creator of the service definition.

See also: BlackBerry Dynamics Service Definition for a description of BlackBerry Dynamics service definition.

SERVICE PARAMETERS

An ICC service request can include a number of parameters, sent by the consumer. Service responses can also include parameters, sent by the provider to convey detailed results to the consumer. The parameters in a request or response are always provided to the application as a map object. The ICC system supports only string type parameters. Any object serialization must be performed by an application.

Note that the service name, version, and method name are not service parameters as such and are not included in the parameters object.

Error responses can include additional details of the error condition. For example, if a parameter exceeds a maximum value, then the additional details could include the value of the maximum. Additional details are specified in the service definition, per condition, in the same way as service parameters.

FILE ATTACHMENTS

An ICC service request can include a number of file attachments specified by the consumer. Service responses can also include file attachments, when these are sent by the provider as results.

File attachments are sent from the secure store of one application, and copied to the secure store of the other application. Deletion of the recipient's copy of the file is the responsibility of the recipient application. The ICC system does not delete copies of files that were attached to a request or response.

In the API, the sending application specifies file attachments as file handles (GDStorageFile) in its secure store. The ICC system copies the files to the receiving application's secure store, and then invokes a callback in the receiving application. The callback is passed the file handles of the copies, which it can used in the usual manner.

The ICC system uses the following naming convention to construct the paths of the receiving application's copies: Inbox Directory/Sender/Reference time/Original Path where:

Note that all the files attached to a particular service request or response will be placed under one directory. This means that the receiving application can delete all these files easily, by deleting the directory.

FOREGROUND EXECUTION

Due to Microsoft Windows limitations all ICC service processing in consumer or provider is executed in the foreground. That means that Front Request API/Service isn't available on Windows.

Every time ICC service provider receives a request or ICC service consumer receives a response, the application is switched to foreground execution. This can can cause an impression of "application flickering" if there is frequent request/response interchange. Sending many small requests/responses should be avoided, one large request/response is preferred instead.

SERVICE CONSUMER REQUIREMENTS

To work as an ICC service provider, a BlackBerry Dynamics application must:

• Access object of the GDService class using Instance property.
• Register event handlers from GDService class that application is interested in.
• Register the ICC URL type on the device. This will normally be achieved by utilizing the mandatory BlackBerry Dynamics build-time configuration, as detailed in the GDWindows class reference.

Note that an application that provides multiple services still instantiates only a single object of this class. The HandleRequest delegate of the object handles requests for all the services that the application provides.

To be on the list returned by a service discovery query, an application must be registered as a service provider. Register the application as a service provider:

• In the enterprise BlackBerry Dynamics management console, if an in-house application.
• Using the BlackBerry Developer Network website, if a partner application.

In either user interface, enter the application identifier, for example "com.example.application.name" that is defined in application manifest in Id attribute of Package/Applications/Application tag.

See GDWindows::GetServiceProvidersAsync(GDServiceProviderType, String, String) for details of the service discovery API.

Reference