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. 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 application to handle the message.

Not applicable

InvokeRequest request;
request.setTarget("com.example.text.view");            
request.setAction("bb.action.OPEN");                
request.setMimeType("text/plain"); 
// The data needs to be a QByteArray   
request.setData("Hello world!".toUtf8()) 

File handling

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

File extensions

The invocation framework supports file handling based on the file extension. The file extensions can be defined as file:// within the scheme parameter when the data is referenced by the URI. The invocation framework also supports the declaration of the exts attribute within 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 exts attribute, then a given target filter will match with that invocation request. When the exts attribute is defined, the target filter implicitly supports the  uris="file://"  for those declared extension cases.

The exts attribute is applied only if the accompanying URIs contain a file:// based URI. Also, combining exts  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 exts related target filters as a separate declaration, where uris is file:// and the MIME type is a wildcard character (*).

File transfer

Sending an invocation request with a file:// URI to pass files succeeds only if the target app can access the file. The platform 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 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's private inbox.
CopyReadWrite Create a read/write copy of the file in the target's private inbox.
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

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 type
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:

Not applicable

[
   {
      "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-09-30



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

comments powered by Disqus