Invocation framework

The invocation framework in the BlackBerry 10 OS allows one app to invoke another by sending it a message. When an app calls for an invocation on some content, the invocation framework responds with appropriate apps that can carry out a requested action on that particular content. For example, using the invocation framework, your app can allow the user to perform a set of actions on a piece of content such as a .doc file. These actions allow the user to share, open, or send the .doc file in an email using another app from within the UI of your app. In this example, your app is the client app in the invocation framework and the app that shares, opens, or sends the .doc file as an email is the target app.

Depending on your app's functionality, the invocation framework can allow your app to become more discoverable if you register your app as a target. Registering allows other apps to invoke your app and use its features.

An invocation request is the message structure that is passed between a client app and a target app. An invocation message represents either a request for the target to perform a task or a notification about an event that has occurred. An invocation request is passed to a target app when the target is invoked. The framework takes care of opening the target app if it is not already running.

An invocation request contains the following information:

  • The unique ID of the target app
  • The action that should be performed
  • The data that should be acted upon

If you're developing a Cascades app, you can download sample client and target apps that use the invocation framework. See the invokeclient and invoketarget sample apps.

Invocation target

An app that is registered with the invocation framework is called a target app. Other apps can invoke a target app by using the invocation framework. Upon invocation, the user's context switches to the target app. The client app (the app from which the invocation request is sent) moves to the background while the user works in the target app.

The target ID in an invocation message tells the invocation framework where to send the invocation message. A target ID is assigned by the target app developer and is guaranteed to be unique when the app is signed. To help select a unique value, the target ID uses a reverse DNS style structure (for example, com.acme.myapp).

Invocation action

The action attribute in an invocation request describes the task that can be performed on the content. Every action is uniquely identified by a name. Action names end with a verb in uppercase letters. To help identify the ownership and uniqueness of each action, the action attributes in an invocation request use a reverse DNS style structure (for example, com.acme.action.VIEW).

The invocation framework supports a set of actions that your app can request the platform to perform (for example, viewing an image). You can also use actions to register your app as a target in the core apps of the BlackBerry 10 OS (for example, registering your app as a target could allow an image in the Pictures app to be shared with your app).

All of the actions available on the BlackBerry 10 OS begin with bb.action and are appended by a verb in uppercase letters. Before you add a custom action, check to see if there is already a suitable action provided by the platform. For a complete list of available platform actions, see Invoking core applications.

Invocation data

The data in an invocation message is provided as a URI and a MIME type. The URI identifies the location of the data resource and the MIME type describes the data. For common MIME types, the platform can deduce the MIME type from the URI, even if you do not specify the MIME type when you specify a URI. For example, it can deduce the MIME type from a file extension in the URI.

For small amounts of data, you can include the data directly in the invocation message using the data attribute. The URI is assumed to be  data://local and can therefore be left out of the message. When you send data directly in the invocation message, you must provide a MIME type because the platform can only deduce the MIME type if a URI is present in the message. The total size of the message cannot exceed 16 KB.

A custom MIME type that describes data should begin with the application/vnd. prefix. It should be followed by sufficient context so that the MIME type is properly distinguished from other types. If the data has multiple encodings represented in the MIME type, make sure that the data is the last element defined in the type (for example, application/vnd.mycompany.mydata).

You can also specify additional, optional data by using the metadata attribute in an invocation message. Data is sent in JSON format.

Last modified: 2015-03-31

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

comments powered by Disqus