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 applications. An invocation request describes the data that can be acted upon by the target application.

Although applications 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.

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. If in an invocation request, 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 only applied 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 application 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 application 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 applications. However, to send sensitive data to a target application, a client application can use the invocation framework's file transfer handling feature. 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 by default it creates a read/write copy of the file in a private inbox for the target application. The client application 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 hardlink to the file in the target application's private inbox. When Link is specified, the file must have read/write permissions. In addition, if the file has read/write permissions then the sender must be the owner of the file.
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 to list://. After you set the type and URI, you can assign the list of individual file URIs to the data section 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. The QUrl class in Qt provides a convenient static function for percent-encoding.

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 JSON formatted metadata. No test metadata

Last modified: 2014-04-17

comments powered by Disqus