Invoked

The Invoked object allows the application to be invoked by other applications.


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 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.invoked.cardRequestClosure           YY
blackberry.invoked.cardStartPeek           YY
blackberry.invoked.invoked           Y 
blackberry.invoked.onCardClosed           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.invoked" />           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.invoked.cardRequestClosure (request : Object)


As a Card, request the Navigator to close itself.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
request Object literal that specifies reason, type and response data of the closure request.

reason: The reason that identifies application level description of why the card was closed.
type: MIME type of data to be returned. It's mandatory if data is returned.
data: The data that will be returned to the parent.

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

function requestClosure() {
    blackberry.invoked.cardRequestClosure({
        reason: "ItemSelected",
        type: "application/contact",
        data: "{"name":"......}"
    });
}

</script>

static void blackberry.invoked.cardStartPeek (peekType : String)


As a Card, request the navigator to perform a peek on the deck


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
peekType Describes the type of peek to perform as a peek to the content of the parent or a peek to the content of the root. The value should be either "content" or "root".

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

function peekParent() {
    // Request the navigator to perform a peek to the content of the parent
    blackberry.invoked.cardStartPeek("content");
}

</script>

Events

blackberry.invoked.invoked


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 invoked event is triggered by the system when the application is invoked by another application.


Supported Platforms
 - BlackBerry 10


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

info: An object the pertinent information
info.source: Identifier of invocation target (as stated in its BAR manifest) to which the receiver can send results. Omitting the source attribute implies that the sender does NOT support results.
info.target: Identifier of target (as stated in its BAR manifest) to which invocation should be delivered. If the target is supplied then brokering is bypassed and attempt is made to invoke the specified target.
info.action: Identifier of action to be performed by target. Omitting action implies brokering should apply to any action supported for the specified type or that the target should infer the action.
info.type: MIME type of data to be acted on. If the mime type is not specified then Invocation Framework would attempt to infer the mime type from the given URI. If the mime type can not be inferred or URI field is empty then invocation will be rejected.
info.uri: URI pointing to invocation data. If no URI is provided then this implies the data://local URI indicating that the invocation data is provided in-band in the data field of the invocation message.
info.data: Data passed to target. Omitting the data implies that the action-type are sufficient to carry out the invocation. Note that target invocation allows passing arbitrary binary data that will be encoded into Base64 encoded string.

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

function onInvoked(onInvokedInfo) {
   if(onInvokedInfo.source) {
       console.log("Source: " + onInvokedInfo.source);
   }
   if(onInvokedInfo.target) {
       console.log("Target(me): " + onInvokedInfo.target);
   }
   if(onInvokedInfo.action) {
       console.log("Action: " + onInvokedInfo.action);
   }
   if(onInvokedInfo.data) {
       console.log("Data: " + onInvokedInfo.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(onInvokedInfo.data));
   }
}

blackberry.event.addEventListener("invoked", onInvoked);

</script>

blackberry.invoked.onCardClosed


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.
As a Card, the onCardClosed event is fired by the navigator to it to indicate that it should clean-up its state and wait for invocation as it is pooled. When a card receives a cardClosed event it should assume that its child card is also closed (if one exists). When a card is dismissed by the Parent or navigator the reason value is "closed".


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the onCardClosed 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 onCardClosedHandler(request) {
   // If it was closed by the navigator, do the clean-up
   if (request.reason == "navigation") {
       cleanup();
   }
}

blackberry.event.addEventListener("onCardClosed", onCardClosedHandler);

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