Invocation framework

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

Depending on your application's functionality, the invocation framework can allow your application to become more discoverable if you register your app as a target application. This allows other applications to invoke your application without first knowing about your application.

An invocation request is the message structure that is passed between a client application and a target application. 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 application when the target is invoked. The framework takes care of launching the target application if it is not already running. An invocation request contains:

  • Target: The unique ID of the target application
  • Action: The action that should be performed on the data
  • Data: The data that should be acted upon

Invocation targets

An application that is registered with the invocation framework is called a target application. Other applications can invoke a target application by using the invocation framework. Upon invocation, the user's context switches to the target application.

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 application developer and is guaranteed to be unique when the application 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 define various tasks which your application 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 applications of the BlackBerry 10 OS (for example, registering your app as a target would allow an image in the Pictures app to be shared with your app).

All 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 the JSON format.

Last modified: 2014-03-10

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

comments powered by Disqus