rim:invoke-target element

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.

You must include the following namespace declaration in the parent <widget> element to use the <rim:invoke-target> element:

xmlns:rim="http://www.blackberry.com/ns/widgets">

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 prefix 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: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

<widget xmlns:rim="http://www.blackberry.com/ns/widgets">
.
.
.
    <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>
</widget>

Registering multiple filters against an invocation

<widget xmlns:rim="http://www.blackberry.com/ns/widgets">
.
.
.
    <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>
</widget>

Registering multiple targets against an invocation type

<widget xmlns:rim="http://www.blackberry.com/ns/widgets">
.
.
.
    <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>
</widget>

Code sample: Parsing invoke parameters

When you set the <content> element's rim:allowInvokeParams attribute to a value of true, the start up parameters for the application are available to the start page as a query string. You can parse the query string using JavaScript.

function parseQueryString() {        

    // Create result container
    var queryParamResult;
    
    // Start at 1 to skip the leading '?'
    var query = window.location.search.substring(1);
    
    // Split the string on key-value pairs
    var params = query.split('&');
    
    // Loop through the pairs
    for ( var i = 0 ; i < params.length ; i++ ) {
        // Locate the '='
        var position = params[i].indexOf('=');
        if ( position > 0 ) {
            
            // Text before the '=' is the key
            var key = params[i].substring( 0, position );
            
            // Text after the '=' is the value
            var value = params[i].substring( position + 1 );
            
            // Add to result container
            queryParamResult[key] = value;
        }
    }
    
    return queryParamResult;
}

Last modified: 2014-03-10

comments powered by Disqus