Invoke

The Invoke object contains methods that interact with other applications.

Since: BlackBerry WebWorks 2.0

On BlackBerry 10, the blackberry.invoke.invoke() function will take arguments in the form of JavaScript object literal.

Installation:

To use this API in your project, add the invoke plugin:

webworks plugin add com.blackberry.invoke

Learning Resources:

Sample - Invocation Sample that demonstrates how to invoke apps and how to create an invokable app [BlackBerry on GitHub].

Functions:
void closeChildCard()
void invoke()
void query()

closeChildCard()

As a parent, close the child Card.

Synopsis:

void blackberry.invoke.closeChildCard()

Example:

<script type="text/javascript">

    function closeChildCard() {
        // Close the child Card for some reason
        blackberry.invoke.closeChildCard();
    }

</script>

invoke()

Invokes another application.

Synopsis:

void blackberry.invoke.invoke(request, onSuccess, onError)

Parameters:

request {Object}

Object literal that specifies what to invoke. None of the fields are required. Refer to the example code for more information.

target {String}

The id that identifies the component to invoke. If target is omitted, the invocation framework would perform brokering based on the specified action, type, URI or data to locate an appropriate target to invoke.

action {String}

The action to be performed by the target.

type {String}

MIME type of data to be acted on. If the MIME type is not specified, then the mime type would be inferred from the given URI. If the MIME type cannot be inferred or URI field is empty, then invocation will be rejected.

uri {String}

URI pointing to invocation data. If no URI is provided, then this implies that the invocation data is provided in-band in the data field of the invocation request.

data {String|Blob}

Data (String or Blob) to be acted upon encoded based on the specified type. NOTE: If a String is passed, make sure that it does not contain Unicode characters or invocation will fail.

file_transfer_mode {String}

An optional string that represents the file transfer mode that can be one of FILE_TRANSFER_PRESERVE, FILE_TRANSFER_COPY_RO, FILE_TRANSFER_COPY_RW, FILE_TRANSFER_LINK. If omitted, it a sensible default of FILE_TRANSFER_COPY_RO will be used.

onSuccess(response) {} {Function}

Callback function that will be triggered when the invocation is successful. Expected signature: function onSuccess().

onError(error) {}

Callback function that will be triggered when invocation is not successful, or if request's data field cannot be encoded (for example, when it contains Unicode characters). Expected signature: function onError(error).

error {String}

A String that describes the error.

Example:

<script type="text/javascript">

    function onInvokeSuccess() {
        console.log("Invocation successful!");
    }

    function onInvokeError(error) {
       alert("Invocation failed, error: " + error);
    }

    function openWebLink() {
        // open web link - allows the system to choose an appropriate target that handles http://
        blackberry.invoke.invoke({
            uri: "http://www.blackberry.com"
        }, onInvokeSuccess, onInvokeError);
    }

    function openWebLinkInBrowser() {
        // open web link in browser
        blackberry.invoke.invoke({
            target: "sys.browser",
            uri: "http://www.blackberry.com"
        }, onInvokeSuccess, onInvokeError);
    }

    function openMP3File() {
        // open mp3 file - allows the system to choose an appropriate target that handles audio/mpeg3
        blackberry.invoke.invoke({
            type: "audio/mpeg3",
            uri: <path to mp3 file>
        }, onInvokeSuccess, onInvokeError);
    }

    function viewPicture() {
        // view picture
        blackberry.invoke.invoke({
            uri: <path to jpg file>,
            action: "bb.action.VIEW"
        }, onInvokeSuccess, onInvokeError);
    }

    function openAnotherApp() {
        // open another application that understands custom data
        blackberry.invoke.invoke({
            target: "another.app.that.handles.custom.json.data",
            type: "text/plain",
            data: "{'myData': 'A string I pass to another app'}"
        }, onInvokeSuccess, onInvokeError);
    }

    function openAnotherAppWithUnicodeData(unicodeStr) {
        // convert unicode string before calling invoke, the receiver app will have to
        // call decodeURIComponent(escape(str)) to get the unicode string back
        var convertedStr = unescape(encodeURIComponent(unicodeStr));

        // open another application that understands custom data
        blackberry.invoke.invoke({
            target: "another.app.that.handles.unicode.data",
            data: convertedStr
        }, onInvokeSuccess, onInvokeError);
    }

    function invokeCard() {
        // invoking Card is the same as invoking an application, except the target specified should point to the "Card" target entry point
        blackberry.invoke.invoke({
            target: "an.app.that.supports.card", // The target should point to the "Card" target entry point of an application
            type: "text/plain",
            data: "{'myData': 'Some data'}"
        }, onInvokeSuccess, onInvokeError);
    }

    function invokePictureViewer() {
        // invoking Card is the same as invoking an application, except the target specified should point to the "Card" target entry point
        blackberry.invoke.invoke({
            action: "bb.action.VIEW",
            uri : "local:///img/image.jpg",
            file_transfer_mode : blackberry.invoke.FILE_TRANSFER_COPY_RO
        }, onInvokeSuccess, onInvokeError);
    }

    function invokeAudoPlayer() {
        blackberry.invoke.invoke({
            action: "bb.action.VIEW",
            uri : "local:///audio/test.mp3",
            file_transfer_mode : blackberry.invoke.FILE_TRANSFER_COPY_RO
        }, onInvokeSuccess, onInvokeError);
    }

    function invokeAudioWithoutTrasnsfer() {
        blackberry.invoke.invoke({
            action: "bb.action.VIEW",
            uri : "local:///audio/test.mp3",
        }, onInvokeSuccess, onInvokeError);
    }

    function invokePhone() {
        blackberry.invoke.invoke(
            {uri: "tel:5555555555"},
            onSuccess, onError);
    }

</script>

query()

Queries device for list of invokable applications.

Synopsis:

void blackberry.invoke.query(request, onSuccess, onError)

Parameters:

request {Object}

An object containing a query to be performed on applications on the device.

action {String}

An identifier of the action to be performed by the target. Omitting action implies the query should apply to any action supported for the specified type or that the target should infer the action.

type {String}

The MIME type of data to be acted on. It must be provided if the uri attribute is not provided.

uri {String}

Used to infer the MIME type of the data. It must be provided if type is not specified.

target_type Mandatory {String[]}

An array that contains a set of target types that the query should return. Possible target types are "VIEWER" or "APPLICATION".

action_type {String}

Indicates the type of actions to be returned. Possible values are "MENU" or "ALL". Menu actions specify addtional icon and label properties.

receiver_capabilities {String}

The list of capabilities that must be granted to the target in order for it to be considered a candidate.

onSuccess {Function}

The callback function that will be triggerd if the query is successful.

response {QueryResponse[]}

An array which contains the result of the query.

onError

The callback function that will be triggered if there was an error processing the query.

error {String}

A String that contains an error message.

Example:

<script type="text/javascript">

    function onSuccess(response) {
        console.log("response: " + JSON.stringify(response, null, 2));
    }

    function onError(error) {
        alert("error: " + error);
    }

    function findAllTargetsThatCanOpenJPEGImages() {
        var request = {
            "action": "bb.action.OPEN",
            "type": "image/jpeg",
            "uri": "file://",
            "target_type": ["APPLICATION", "VIEWER"],
            "action_type": "ALL"
        };

        blackberry.invoke.query(request, onSuccess, onError);
    }

    function findViewersThatCanViewPDFDocs() {
        var request = {
            "action": "bb.action.VIEW",
            "type": "application/pdf",
            "uri": "file://",
            "target_type": ["VIEWER"],
            "action_type": "ALL"
        };

        blackberry.invoke.query(request, onSuccess, onError);
    }

    function findApplicationsThatCanOpenAudioFiles() {
        var request = {
            "action": "bb.action.OPEN",
            "type": "audio/mp3",
            "uri": "file://",
            "target_type": ["APPLICATION"],
            "action_type": "ALL"
        };

        blackberry.invoke.query(request, onSuccess, onError);
    }

    function findAllTargetsThatCanHandleAllVideoFiles() {
        var request = {
            "type": "video/mp4",
            "uri": "file://",
            "target_type": ["APPLICATION", "VIEWER"],
            "action_type": "ALL"
        };

        blackberry.invoke.query(request, onSuccess, onError);
    }

</script>

onChildCardClosed

This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.addEventListener function. The onChildCardClosed event is fired by the navigator to notify the parent that a card is closed. The event includes any response data sent by the card (if the card requested its own closure).

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the onChildCardClosed event.

request {Object}

An object that includes any response data sent by the card (if the card requested closure).

reason {String}

Describes application level description of why the card was closed. If the close was due to a navigation, Navigator will insert the value "navigation".

type {String}

Describes the type and encoding of the value in the data attributes.

data {String}

Describes the data that will be returned to the parent.

Example:

<script type="text/javascript">

    function onChildCardClosedHandler(request) {
        // The child Card is closed and reason is "OK", process the closure data;
        // otherwise do nothing.
        if (request.reason == "OK") {
            processCardClosureData(request.type, request.data);
        }
    }

    document.addEventListener("onChildCardClosed", onChildCardClosedHandler);

</script>

onChildCardEndPeek

This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.addEventListener function. The onChildCardEndPeek event is fired by the navigator to notify the parent that it is no longer being peeked at.

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the onChildCardEndPeek event.

Example:

<script type="text/javascript">

    function onChildCardEndPeekHandler() {
        // The Card stopped peeking
        console.log("I am no longer being peeked at.");
    }

    document.addEventListener("onChildCardEndPeek", onChildCardEndPeekHandler);

</script>

onChildCardStartPeek

This event is fired by the system. If you want to listen to the event you can do so using the document.addEventListener function and remove the listener using the document.addEventListener function. The onChildCardStartPeek event is fired by the navigator to notify the parent that it is being peeked at and describe the type of peek being performed.

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the onChildCardStartPeek event.

peekType {String}

Describes the type of peek to be performed as a peek to the content of the parent or a peek to the content of the root. The value is either "content" or "root".

Example:

<script type="text/javascript">

    function onChildCardStartPeekHandler(peekType) {
        // The Card started peeking
        console.log("The card started peeking.");
        if (peekType == "root") {
            updateContent(true);
        }
    }

    document.addEventListener("onChildCardStartPeek", onChildCardStartPeekHandler);

</script>

FILE_TRANSFER_COPY_RO

Describes the file transfer mode where the file will be copied to the invoked application with read only privileges.

Synopsis:

constant
String blackberry.invoke.FILE_TRANSFER_COPY_RO = "COPY_RO"

FILE_TRANSFER_COPY_RW

Describes the file transfer mode where the file will be copied to the invoked application with read and write privileges.

Synopsis:

constant
String blackberry.invoke.FILE_TRANSFER_COPY_RW = "COPY_RW"

FILE_TRANSFER_LINK

Describes the file transfer mode where the invoked application will receive a link to the file path provided. The permissions of the original file MUST include o+r. It o+w the sender must be the owner of the file.

Synopsis:

constant
String blackberry.invoke.FILE_TRANSFER_LINK = "LINK"

FILE_TRANSFER_PRESERVE

Describes the file transfer mode where the provided URI is preserved as is. No box-2-box logic is applied.

Synopsis:

constant
String blackberry.invoke.FILE_TRANSFER_PRESERVE = "PRESERVE"

Last modified: 2014-09-29



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

comments powered by Disqus