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.
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.
This section contains information on how invocation framework handles file transfers and the type of files supported.
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 (*).
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.|
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/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|
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:
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.
|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