Data transfer

This section explains how the invocation framework sends data, to help you understand how to optimize your invocation requests and send multiple files between client and target apps. Although apps can use many different URI schemes to transfer data, the invocation framework provides support for in-band transfer and file transfer.

In-band transfer

Most often, an invocation request carries only a small amount of data (less than 16 KB). In some cases, this small amount of data can be encoded directly into a URI. It is also possible to send it as part of the invocation request. When data is sent as part of the invocation message, it is placed in the data attribute. This type of transfer is called an in-band transfer.

During an in-band transfer, the URI value should be set to data://local, which points to the data attribute. When the data is sent in-band, the MIME type must describe the type of the data, to allow both the invocation framework and the target app to handle the message.

Not applicable

InvokeRequest request;

// Set the target app
request.setTarget("com.example.text.view");            

// Set the action that the target app should execute
request.setAction("bb.action.OPEN");

// Set the MIME type of the data
request.setMimeType("text/plain");

// Specify the data, which must be a QByteArray   
request.setData("Hello world!".toUtf8()) 

File transfer

This section contains information on how the invocation framework handles file transfers and the types of files that are supported.

File extensions

The invocation framework supports file handling based on the file extension. The file extensions can be defined as file:// in the scheme attribute when the data is referenced by the URI. The invocation framework also supports the declaration of an extensions attribute in the target filters. In an invocation request, if the URI is suffixed with a file extension that matches any of the file extensions declared in the extensions attribute, then a given target filter will match with that invocation request. When the extensions attribute is defined, the target filter implicitly supports the file:// URI for those declared extension cases.

The extensions attribute is applied only if the accompanying URIs contain a file://-based URI. Also, combining the extensions attribute and specific MIME types in a target filter means that both must be specified by a client app for the target filter to successfully match with an invocation request. The best practice in most cases is to define the extensions-related target filters as a separate declaration, where the URI attribute is file:// and the MIME type is a wildcard character (*).

File transfer modes

Sending an invocation request with a file:// URI to pass files succeeds only if the target app can access the file. BlackBerry 10 supports the use of a shared area in the file system to share data between the client and target apps. However, to send sensitive data to a target app, a client app can use the file transfer feature of the invocation framework.

When the framework receives an invocation request with a file:// URI, it inspects the URI to determine if the request refers to a shared area. If the file is already shared, the invocation request passes the URI to the file in the shared area, as specified by the sender. However, if the invocation framework detects that the file is not shared, then it creates a read/write copy of the file in a private inbox for the target app. The client app can specify the file transfer mode attribute to override this behavior.

Invocation requests support the following file transfer modes:

File transfer mode Description

Preserve

Skip file transfer handling and deliver the file as-is.

CopyReadOnly

Create a read-only copy of the file in the target app's private inbox.

CopyReadWrite

Create a read/write copy of the file in the target app's private inbox. This is the default behavior.

Link

Create a hard link to the file in the target app's private inbox. When Link is specified, the file must have read/write permissions and the sender must be the owner of the file.

Not applicable

Here's how to set the file transfer mode for an invocation request:

InvokeRequest request;

request.setFileTransferMode(FileTransferMode::Preserve);

Sending multiple files

For certain invocation requests, you might want to send multiple files in a single request. The invocation framework supports a special set of MIME types ( type/subtype ). Each type is a combination of supported file types, as explained below:

Type Supported file types

filelist/audio

audio/mp4, audio/mpeg

filelist/video

video/mpeg, video/mp4

filelist/image

image/gif, image/jpeg, image/png

filelist/media

Any of the files supported for filelist/audio, filelist/video, or filelist/image

filelist/document

application/pdf, application/vnd.ms-excel, application/msword, application/vnd.ms-powerpoint

filelist/mixed

Any

When sending multiple files, you can set the URI attribute to describe the common file path that is associated with each file. Usually, this file path is the common root directory, if one exists. If no common root directory exists, set the URI attribute to list://. After you set the type and URI, you can assign the list of individual file URIs to the data attribute using the following JSON format:

[
   {
      "uri":<file-uri>,
      "type":<mime-type>,
      "data":<metadata>
   }
]

To learn more about how to use data in JSON format, see Working with JSON.

Make sure that URIs are percent-encoded. Percent-encoding is an efficient way to encode the data in a URI.

Attribute Format Description Mandatory? Example

uri

File URI

The URI of the file being listed; the URI prefix must match the invoke.uri attribute value

Yes

file://path/to/file

type

MIME

The MIME type of the specified file

No

image/jpeg

data

JSON

Additional metadata in JSON format

No

test metadata

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus