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.
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 |
API | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
blackberry.invoke.closeChildCard | Y | Y | |||||
blackberry.invoke.invoke | Y | Y | Y | Y | Y | Y | |
blackberry.invoke.invoke | Y | Y | |||||
blackberry.invoke.query | Y | Y | |||||
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 ID | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<feature id="blackberry.invoke" /> | Y | Y | Y | Y | Y | Y | Y |
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
Events
Properties
Function | interrupter |
Constants
String | FILE_TRANSFER_COPY_RO |
String | FILE_TRANSFER_COPY_RW |
String | FILE_TRANSFER_LINK |
String | FILE_TRANSFER_PRESERVE |
Functions
static
void
blackberry.invoke.closeChildCard
()
As a parent, close the child Card
Supported Platforms | |
---|---|
- BlackBerry 10 | |
- Ripple Emulator |
Code Example:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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 |