Receiving invocation

You can configure your application to receive invocation request from other applications. To receive an invocation request, your application must support invocation targets. To support invocation targets, you must declare your targets in the config.xml file and handle invocation messages.

Target declaration

In order to be invoked, an application identifies itself by declaring itself as a target in its config.xml file. To declare a target, add the following elements to the config.xml file for each target that the application exposes.
<invoke-target id="com.example.image.view">
  <invoke-target-type>application</invoke-target-type>
  <invoke-target-name>My App Name</invoke-target-name>
  <icon>
    <image>icon.png</image>
  </icon>
</invoke-target>

To let the platform know the type of the target, define the <invoke-target-type>  element as shown in the example below.

Attribute Description
invoke-target id Uniquely identifies the application as a target. This parameter can also be used by the client applications to perform Bound invocation.
type The type of the target. Applications and cards are supported as types of the target.
name The name of the target application.
image The icon for the target application.

The following sections explain how you can create different kinds of targets. Targets include applications and cards.

Receiving invocations

Declaring your application as a target is essential for receiving an invocation request, but to be invoked you need to add code in your application to receive invocation messages. Before you can receive invocation messages, you must specify your app in the config.xml file as shown below:

<rim:invoke-target id="com.bb.test.invokable">
<type>APPLICATION</type>
<filter>
<action>bb.action.OPEN</action>
<mime-type>text/plain</mime-type>
</filter>
</rim:invoke-target>

The following code describes how to configure your application to listen for invocation messages:

// Add an event listener for when
// the application gets invoked:
document.addEventListener('invoked',onInvoked);

// The following function parses the incoming data
function onInvoked(invokeRequest) {
}   

Handling launch through invocation

An important thing to consider when you write an application target is how an application is launched. Usually an application launches when the BlackBerry device user taps the app icon on the home screen. However, with the invocation framework the application can also be invoked. So how does an application know whether it was invoked or launched? Here's how your application can listen for the invocation events:

function onInvoked(info) {
    if(info.source) {
        console.log("Source: " + info.source);
    }
    if(info.target) {
        console.log("Target(me): " + info.target);
    }
    if(info.action) {
        console.log("Action: " + info.action);
    }
    if(info.data) {
        console.log("Data: " + info.data);
        //the data comes in as a base64 string you can convert it using atob(...)
        //note that atob will fail if you are being passed unicode strings
        console.log("Data: " + atob(info.data));
    }
}

document.addEventListener('invoked',onInvoked);

You can also specify any particular behavior that you'd like your app to exhibit when it is invoked (for example, screen orientation) by setting app preferences. For more information, see Configuring your app preferences.

Target filters

One of the key features of the invocation framework is the ability to discover target applications or cards on a BlackBerry device. Targets are discovered based on the filters they declare in their config.xml file, which describe the kinds of invocation request that a target supports. Target filters allow your application to be queried for by other apps and make your application a candidate for unbound invocation requests.

Target filters are declared as part of the <invoke-target> element in the config.xml file and consist of the following attributes:

Attribute Description
filter Describes the criteria for this application to be considered for unbound invocations or invocation queries.
action Describes the actions that can be performed on the content. It represents the action that the target supports for the types specified in the type attribute. Include one <action> element for each supported action.
mime-type Describes the type of content. This attribute represents the different types for which the specified actions are supported. The type and the subtype can both be specified as a wildcard, within a target filter. For example, a filter can specify image/png, image/* or *. Include one <mime-type> element for each supported MIME type.
uris Describes the supported URI pattern that must prefix the URI that is provided in the invocation request. This attribute represents the URI prefixes that describe how the target supports the delivery of the data. The URI value may contain the single wildcard character * to indicate that the filter supports any delivery mechanism. If the target application or a card supports the delivery of the data as part of the message body then it should include the data://local URI.
exts Represents the list of file extensions supported by the target. The values specified in this attribute apply only to file:// URIs. When exts are specified in a target filter, they are generally specified in conjunction with MIME type=*. A best practice is to be as specific as possible when specifying the filter criteria, to increase the chances of being selected to handle the invocation request. Wildcard characters (*) are considered a relatively weak match when performing selection, therefore if your target supports a specific set of types, you must specify each of the types in the filter. In cases where your application supports both specific MIME types and extensions, you should split the registration into two separate filters. One filter registers for the specific types and one filter registers for the extensions against the type=*.
When you declare a target filter, make sure that your filter description abides by the following rules:
  • The URI value cannot be set as a wildcard character (*). That is, you cannot declare <property var= "uris" value="*"/> in your config.xml file.
  • If the target filter contains actions such as bb.action.VIEW or bb.action.OPEN, and has MIME types set as a wildcard character (*), and has the URI attribute set as data:// or file:// or left unstated, then your application cannot be deployed or installed on the device.
  • For a target filter that utilizes the URI file:// and a MIME type wildcard character (*), to successfully register with the invocation framework, you must also specify a file extension value which is not a wildcard character (*).
  • If you declare a file extension value in the target filter, the file extension value is considered during the brokering and selection process if it is used with a file:// URI.
If your application uses a target filter declaration that is restricted, then on deployment, the result::failure 884 Restricted Invoke Filter detected error is displayed in the command line tool.

Here are some examples of target filters that successfully register with the invocation framework:

  • actions=bb.action.OPEN;types=*;uris=http://;
  • actions=bb.action.OPEN,bb.action.VIEW;types=*;uris=file://;exts=jpg,gif,tif;
  • actions=bb.action.VIEW;types=*;uris=data://;exts=jpg,gif,tif;
The following target filters do not follow the rules specified above and will not allow the application to be deployed or installed on the device:
  • actions=bb.action.OPEN,bb.action.VIEW,bb.action.SET;types=*;uris=file://;
  • actions=bb.action.OPEN;types=*;uris=data://;
  • actions=bb.action.VIEW;types=*;uris=*;
  • actions=bb.action.VIEW;types=*;
  • actions=bb.action.OPEN,bb.action.VIEW;types=*;uris=file://;exts=*;

The following example describes an invoke target that has two filters. The first filter describes the support for bb.action.OPEN and bb.action.VIEW actions on .png and .jpeg image files that are delivered in a file or in the message body. The second filter describes the support for bb.action.OPEN and bb.action.VIEW actions on any URI file with .jpg or .png extensions.

<invoke-target id="com.example.image.view">
  <entry-point-id></entry-point-id>
  <invoke-target-type>application</invoke-target-type>
  <filter>
    <action>bb.action.VIEW</action>
    <action>bb.action.OPEN</action>
    <mime-type>image/png</mime-type>
    <mime-type>image/jpeg</mime-type>
    <property var="uris" value="file://,data://local"/>
  </filter>
  <filter>
    <action>bb.action.VIEW</action>
    <action>bb.action.OPEN</action>
    <mime-type>*</mime-type>
    <property var="uris" value="file://"/>
    <property var="exts" value="jpg,png"/>
  </filter>
</invoke-target>

Last modified: 2014-05-14



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

comments powered by Disqus