Invoke

The Invoke object contains methods that interact with other applications.

On BlackBerry OS 5.0+ and BlackBerry PlayBook 1.0+, the blackberry.invoke.invoke method on the invoke object allows you to pass arguments to the target application.
The types of arguments can be one of: blackberry.invoke.AddressBookArguments, blackberry.invoke.BrowserArguments, blackberry.invoke.CalendarArguments, blackberry.invoke.CameraArguments, blackberry.invoke.JavaArguments, blackberry.invoke.MapsArguments, blackberry.invoke.MemoArguments, blackberry.invoke.MessageArguments, blackberry.invoke.PhoneArguments, blackberry.invoke.SearchArguments, and blackberry.invoke.TaskArguments.

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


Beta Notice:

This API is considered to be in Beta. The function and property signatures listed below could change at anytime. Once the API moves out of Beta it will be distributed as part of the core API.



Last Updated: Sun Dec 30 2012 18:15:39 GMT-0500 (EST)

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.invoke.closeChildCard           YY
blackberry.invoke.invoke Y Y Y Y Y  Y
blackberry.invoke.invoke           YY
blackberry.invoke.query           YY
interrupter           Y 
FILE_TRANSFER_COPY_RO           Y 
FILE_TRANSFER_COPY_RW           Y 
FILE_TRANSFER_LINK           Y 
FILE_TRANSFER_PRESERVE           Y 
blackberry.invoke.onChildCardClosed           Y 
blackberry.invoke.onChildCardEndPeek           Y 
blackberry.invoke.onChildCardStartPeek           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.invoke" /> Y Y Y Y Y YY

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

static void blackberry.invoke.closeChildCard ()


As a parent, close the child Card


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Code Example:
<script type="text/javascript">

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

</script>

static void blackberry.invoke.invoke (appType : Number, [args : Object])


Invokes another application on the BlackBerry PlayBook or Blackberry OS 5.0+.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
appType an integer value representing the type of application to launch. Must be one of the 'APP_*' constants.
args An arguments object specifying information for the application being invoked.

Throws
Exception If values supplied are not correct.

Code Example:
<script type="text/javascript">

 function startCameraApp() {
     var args = new blackberry.invoke.CameraArguments();
     args.view = blackberry.invoke.CameraArguments.VIEW_RECORDER;

     blackberry.invoke.invoke(blackberry.invoke.APP_CAMERA, args);
 }

 startCameraApp();
 </script>

static void blackberry.invoke.invoke (request : Object, onSuccess: function(), onError: function([error: String]))


Invokes another application


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


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

target: 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: The action to be performed by the target.
type: 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: 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: 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: 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 Callback function that will be triggered when the invocation is successful. Expected signature: function onSuccess().
onError Callback function that will be triggered when invocation is not successful, or if request's data field cannot be encoded (e.g. when it contains unicode characters). Expected signature: function onError(error).

error: A String that describes the error.

Code Example:
<script type="text/javascript">

function onInvokeSuccess() {
    alert("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);
}


</script>

static void blackberry.invoke.query (request : Object, onSuccess: function(response : QueryResponse[]), onError: function([error: String]))


Queries device for list of invokable applications.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


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

action: 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: The MIME type of data to be acted on. It must be provided if the uri attribute is not provided.
uri: Used to infer the MIME type of the data. It must be provided if type is not specified.
target_type: Mandatory. An array that contains a set of target types that the query should return. Possible target types are "VIEWER" or "APPLICATION".
action_type: Indicates the type of actions to be returned. Possible values are "MENU" or "ALL". Menu actions specify addtional icon and label properties.
receiver_capabilites: The list of capabilities that must be granted to the target in order for it to be considered a candidate.
onSuccess The callback function that will be triggerd if the query is successful.

response: 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: A String that contains an error message.

Code Example:
<script type="text/javascript">

 function onSuccess(response) {
     alert("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": ["VIEWERS"],
             "action_type": "ALL"
         };

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

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

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

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

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

</script>

Events

blackberry.invoke.onChildCardClosed


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener 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).


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the onChildCardClosed event

request: An object that includes any response data sent by the card (if the card requested closure).
request.reason: Describes application level description of why the card was closed. In the case that the close was due to a navigation Navigator will insert the value "navigation"
request.type: Describes the type and encoding of the value in the data attributes
request.data: Describes the data that will be returned to the parent

Code 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);
   }
}

blackberry.event.addEventListener("onChildCardClosed", onChildCardClosedHandler);

</script>

blackberry.invoke.onChildCardEndPeek


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.

The onChildCardEndPeek event is fired by the navigator to notify the parent that it is no longer being peeked at.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the onChildCardEndPeek event

Code Example:
<script type="text/javascript">

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

blackberry.event.addEventListener("onChildCardEndPeek", onChildCardEndPeekHandler);

</script>

blackberry.invoke.onChildCardStartPeek


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener 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


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the onChildCardStartPeek event

peekType: 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".

Code Example:
<script type="text/javascript">

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

blackberry.event.addEventListener("onChildCardStartPeek", onChildCardStartPeekHandler);

</script>

Properties

static Function interrupter


Registers a function that is triggered during invocation as an interrupter. Allows developers to interrupt the invocation, and perform any action they please. Developers are passed the invocation object, and can perform any modifications to it they like. The modifications should be returned from the function


Supported Platforms
 - BlackBerry 10


Parameters
onInvoke function that is triggered on invoke

Return:

modified request from the user to the system to be run on invocation



Code Example:
<script type="text/javascript">

 function registerForInvokeInterrupter() {
     blackberry.invoke.interrupter = function (request) {
         if(confirm("System would like to invoke: " + request + " would you like to continue?")) {
             return request;
         } else {
             alert("User canceled invocation");
         }
     };
 }

 function clearInterrupter () {
     blackberry.invoke.interrupter = null;
 }

 registerForInvokeInterrupter();
 clearInterrupter();
 </script>

Constants

static String FILE_TRANSFER_COPY_RO


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


Supported Platforms
 - BlackBerry 10

static String FILE_TRANSFER_COPY_RW


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


Supported Platforms
 - BlackBerry 10

static String 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.


Supported Platforms
 - BlackBerry 10

static String FILE_TRANSFER_PRESERVE


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


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:39 GMT-0500 (EST)