rim:invoke-target element

Supported platforms

  • no BlackBerry OS: 5.0 - 7.0
  • no BlackBerry PlayBook OS: 2.0+
  • yes BlackBerry 10 OS

Syntax

<rim:invoke-target id="string">
    <type>[ APPLICATION | VIEWER ]</type>
        <filter>
            <action>string</action>
            <mime-type>mime type</mime-type>
            <property var=["exts" | "uris"] value="string" />
        </filter>
</rim:invoke-target>

Description

You can use the <rim:invoke-target> element to register your BlackBerry WebWorks application as a handler for invocation events. In BlackBerry 10 OS, the invocation framework provides the ability by which a client process can send a message to a target process so it can perform a certain action.

If you register your application with the invocation framework, your application can be invoked through:
  • Bound invocation: The target is invoked by using an identifier.
  • Unbound invocation: The target is invoked without specifying a target.
  • Bound and unbound invocation: The target is invoked by using an identifier and other attributes.

All invocations must specify an action that the target must perform as well as data to be acted upon. The data can be specified by using a combination of MIME types, URIs, and file extensions.

Parent elements

<widget>

Child elements

See element structure below.

Occurrences

Zero or more

Element structure

All child elements of the <rim:invoke-target> element have the rim namespace by default. Therefore, you do not have to prepend any of the other child elements of the <rim:invoke-target> element with rim.

Element Parent Description
<rim:invoke-target> <widget>

Registers a bound and/or unbound invocation against an application type.

This is an optional element.
<rim:type> <rim:invoke-target>
Describes the type of invocation of <rim:invoke-target>. The type can be one of the following:
  • application
  • viewer

This element is required for the parent element.

<rim:require-source-permissions> <rim:invoke-target>

Lists the capabilities that the invoking application must support.

This is an optional element.
<rim:filter> <rim:invoke-target>

Describes a set of instances in which the target may receive an unbound invocation.

This is an optional element.
<rim:action> <rim:filter>

Contains a valid action for the target to perform on the data.

This element is required for the parent element.

<rim:mime-type> <rim:filter>

Contains a valid MIME type for the data (wildcard characters are allowed).

This element is required for the parent element.

<rim:property> <rim:filter>

Contains a valid prefix for URIs or suffix for file extensions of the URI provided during invocation.

This is an optional element.

Element attributes

Attribute Defined in Description
rim:id <rim:invoke-target>

Specifies a globally unique name. This name is verified when you sign the application. It's recommended that you use the reverse-DNS naming convention.

Example: com.ea.needforspeed.target

This attribute is required.
rim:var <rim:property>

Specifies extra properties that can be used to register an unbound invocation. The invocation framework supports invocation by URI or by file extensions. The value can be uris or exts.

This attribute is optional.
rim:value <rim:property>

Specifies the property values to use when registering an unbound invocation. This attribute is optional.

Examples of URI values include (but are not limited to):

  • http://
  • https://
  • ftp://

Examples of file extension values include (but are not limited to):

  • html
  • htm
  • php
  • jsp
  • asp

Examples

Registering bound and unbound invocations 

<rim:invoke-target id="com.domain.subdomain.appname.app">
    <type>APPLICATION</type>
    <filter>
        <action>bb.action.OPEN</action>
        <action>bb.action.SET</action>
        <mime-type>text/*</mime-type>
        <property var="exts" value="bmp,css,html,js" />
        <property var="uris" value="data://local,file://" />
    </filter>
</rim:invoke-target>

Registering multiple filters against an invocation 

<rim:invoke-target id="com.domain.subdomain.appname.app">
    <type>APPLICATION</type>
    <filter>
        <action>bb.action.OPEN</action>
        <mime-type>application/*</mime-type>
        <mime-type>text/*</mime-type>
        <mime-type>audio/*</mime-type>
        <mime-type>image/*</mime-type>
        <mime-type>message/*</mime-type>
        <mime-type>video/*</mime-type>
    </filter>
    <filter>
        <action>bb.action.VIEW</action>
        <mime-type>text/*</mime-type>
    </filter>
    <filter>
        <action>bb.action.SET</action>
        <mime-type>image/*</mime-type>
        <property var="exts" value="bmp,png,jpg,gif" />
    </filter>
</rim:invoke-target>

Registering multiple targets against an invocation type 

<rim:invoke-target id="com.domain.subdomain.appname.app">
    <type>APPLICATION</type>
    <filter>
        <action>bb.action.OPEN</action>
        <mime-type>image/*</mime-type>
        <mime-type>text/*</mime-type>
        <mime-type>video/*</mime-type>
    </filter>
</rim:invoke-target>
<rim:invoke-target id="com.domain.subdomain.appname.view">
    <type>VIEWER</type>
    <filter>
        <action>bb.action.VIEW</action>
        <mime-type>image/*</mime-type>
        <mime-type>text/*</mime-type>
        <mime-type>video/*</mime-type>
    </filter>
</rim:invoke-target>

Last modified: 2013-05-02