InvokeManager

Since: BlackBerry 10.0.0

#include <bb/system/InvokeManager>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

Manages all interactions with the invocation service.

Invocation is the process by which a client process can send a message to a target process so it will perform a particular action. Invocation addresses locating a target instance (spawning one if necessary) and delivering the invocation message. Clients may explicitly specify a target (bound invocation) or allow the invocation service to find a "best fit" (unbound invocation). Clients can also request a list of available targets to perform their own selection.

Invocation targets can be applications, cards, or services, and must declare themselves as the appropriate target in their BAR manifest so that they are registered as valid invocation targets.

The InvokeManager supports both sending and receiving invoke messages thus allowing an application to act as a client, a target, or both. Applications and cards receive invoke messages by connecting to the invoked(const bb::system::InvokeRequest&) signal. Applications and cards can determine if they were launched as the result of an invoke message using the startupMode() method. The data from an invoke message received at startup will arrive via one of the aforementioned signals.

To send an invoke message, construct an InvokeRequest object and pass it to the invoke() method. The returned InvokeReply object will contain the result of the invoke operation when it becomes available. To discover which invocation targets are available, construct an InvokeQueryTargetsRequest object and pass it to queryTargets(). Similar to invoke(), the results are returned asynchronously via an instance of InvokeQueryTargetsReply.

An application target behaves like a typical application. When it is invoked through the invocation framework, the context switches to the invoked application, and it behaves as if it was launched from the home screen (it will appear thumbnailed on the screen that shows running applications).

A card is similar to an application, but when a card is invoked, the context does not switch to a separate application. Instead, the card is transitioned into the foreground of the application that invoked it, thus integrating more fluently into the flow of the invoking application. Although a card executes in its own process and renders in its own windows, it can still be considered part of the running application in that the card cannot be minimized on its own (and will not appear separately in the list of running applications on the home screen). A card is intended to provide discrete functionality such as picking a contact, composing an email, or previewing an image. Cards can be "stacked", but a parent (the invoking entity) can only invoke one card at a time.

When a card has completed the activity is was invoked to perform, it informs the parent using the sendCardDone() method, passing a CardDoneMessage to include any results. Results from a card can include the reason the card completed, any data that needs to be sent to the parent, and the data type of the data. The parent will receive the childCardDone() signal. After the invocation framework has transitioned the card off-screen, it will emit the cardPooled() signal to the card. This indicates that the card process is still running, but has been pooled so that future invocations are optimized. Therefore, when the card receives this signal, it must reset its state so that it is ready to be invoked cleanly again. For example, for a composer, any input should be discarded.

A parent can close its child and any stacked cards by calling closeChildCard(). Each card will be notified with the cardPooled() signal, and the parent will receive the childCardDone() signal as an acknowledgment. Similarly, the invocation framework can close a stack of cards (for example, if the user navigates away from the cards); if this occurs, the parent receives the childCardDone() signal and each card receives a cardPooled() signal.

Cards can also be invoked as part of a list of invocations by specifying bb::system::InvokeRequest::setListId(). Cards that belong to lists can be navigated through using system gestures and keyboard shortcuts. The currently open card of a list may request to be replaced with its previous or next item via selectListItem().

The application requesting a card to be opened as a list item should connect to the relevant signals (listItemSelected(), listItemSelectedFromCursor(), listCursorMoved()) and if appropriate, issue corresponding invoke requests.

An application can have at most one invoke list active at a time.


Overview

Public Functions Index

InvokeManager (QObject *parent=0)
virtual ~InvokeManager ()
boolcardPeek (bb::system::CardPeek::Type peekType)
boolcardReady ()
boolcardResized (const CardResizeMessage &message)
boolcloseChildCard ()
InvokeReply *deregisterTimer (const QString &timerId)
InvokeTargetReply *invoke (const InvokeRequest &request)
InvokeQueryTargetsReply *queryTargets (const InvokeQueryTargetsRequest &request)
InvokeReply *registerTimer (const InvokeTimerRequest &request)
boolrequestCardReadyCheck (bool check)
InvokeRequestTargetFiltersReply *requestTargetFilters (const QString &targetKey)
boolselectListItem (bb::system::InvokeListCursorDirection::Type direction)
boolsendCardDone (const CardDoneMessage &message)
bb::system::ApplicationStartupMode::TypestartupMode () const
boolswipeAway ()
InvokeReply *updateTargetFilters (const InvokeUpdateTargetFiltersRequest &request)

Signals Index

voidcardPeekEnded ()
voidcardPeekStarted (bb::system::CardPeek::Type peekType)
voidcardPooled (const bb::system::CardDoneMessage &message)
voidcardReadyCheck ()
voidcardResizeRequested (const bb::system::CardResizeMessage &message)
voidchildCardDone (const bb::system::CardDoneMessage &message)
voidchildPeekEnded ()
voidchildPeekStarted (bb::system::CardPeek::Type peekType)
voidinvoked (const bb::system::InvokeRequest &request)
voidlistCursorMoved (int listId, bb::system::InvokeListCursorDirection::Type direction)
voidlistItemSelected (int listId, bb::system::InvokeListCursorDirection::Type direction)
voidlistItemSelectedFromCursor (int listId)

Public Functions

InvokeManager (

Creates a new InvokeManager object.

Note:

By default, this instance will be the parent of any futures that it returns. If the lifetime of this instance is shorter than the lifetime of the requests, the parent of the futures should be changed using QObject::setParent(). Otherwise, the futures will be destroyed when this instance is destroyed. This will result in signals from the futures not being emitted, though the requests will not be canceled.

Futures are returned by:
Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~InvokeManager ()

Destructor.

Any futures that have this instance as their parent will be destroyed without canceling the associated requests.

Since:

BlackBerry 10.0.0

bool cardPeek (

Tells the parent that a peek has been detected.

Parameters
peekType

The type of peek that should be initiated. See bb::system::CardPeek for the list of possible card peeks.

Return:

true if the operation was successful, false otherwise.

Since:

BlackBerry 10.0.0

bool cardReady ()

Notifies the system that the card's window is ready to be shown.

If this function is called without first calling requestCardReadyCheck(), then the behavior is undefined.

Return:

true if the notification was successfully sent, false otherwise.

Since:

BlackBerry 10.0.0

bool cardResized (

Responds to a request to be resized.

Parameters
message

A message describing the resize parameters, as received in the cardResizeRequested() signal.

Return:

true if the response was sent successfully, false otherwise.

Since:

BlackBerry 10.0.0

bool closeChildCard ()

Tells a card invoked by this application or card to close.

Return:

true if the child card was successfully closed, false otherwise.

Since:

BlackBerry 10.0.0

InvokeReply * deregisterTimer (

Sends a timer deregistration request to the invocation service.

The results of the deregistration operation will be communicated asynchronously via the returned #InvokeReply object. It is important to mention that Recurrence Rule Timers have to be explicitly deregistered. Otherwise, the recurrence rule timer would stay active forever.

Note:

The returned future has its parent set to this instance. Unless its parent is changed (using #QObject::setParent()), the future will be destroyed when this instance is destroyed.

,

To minimize memory usage, explicitly destroy the returned object using #QObject::deleteLater() instead of relying on the implicit cleanup that occurs due to the QObject parent-child relationship.

Parameters
timerId

The timerId of the timer to be deregistered.

Return:

A future representing the result this operation or 0 if the register message could not be sent.

Since:

BlackBerry 10.3.0

InvokeTargetReply * invoke (

Constructs an invoke message to send to an application, card or service using the data in the specified request object and sends it to the invocation service.

The results of the invoke operation will be communicated asynchronously via the returned InvokeTargetReply object.

Note:

The returned future has its parent set to this instance. Unless its parent is changed (using QObject::setParent()), the future will be destroyed when this instance is destroyed.

,

To minimize memory usage, explicitly destroy the returned object using QObject::deleteLater() instead of relying on the implicit cleanup that occurs due to the QObject parent-child relationship.

Parameters
request

The data used to construct the invoke message.

Return:

A future representing the result this operation or 0 if the invoke message could not be sent.

Since:

BlackBerry 10.0.0

InvokeQueryTargetsReply * queryTargets (

Constructs a query message to search for available actions and targets using the data in the specified request object and sends it to the invocation service.

The results of the query operation will be communicated asynchronously via the returned InvokeQueryTargetsReply object.

Note:

The returned future has its parent set to this instance. Unless its parent is changed (using QObject::setParent()), the future will be destroyed when this instance is destroyed.

,

To minimize memory usage, explicitly destroy the returned object using QObject::deleteLater() instead of relying on the implicit cleanup that occurs due to the QObject parent-child relationship.

Parameters
request

The data used to construct the query message.

Return:

A future representing the result this operation or 0 if the query message could not be sent.

Since:

BlackBerry 10.0.0

InvokeReply * registerTimer (

Sends a timer registration request to the invocation service.

The results of the timer request operation will be communicated asynchronously via the returned #InvokeReply object. It is important to mention that Recurrence Rule Timers have to be explicitly deregistered. Otherwise, the recurrence rule timer would stay active forever.

If a Recurrence Rule defines a schedule that leads to generating time slots that are less than 6 minutes apart, this rule will be rejected and registration will fail.

Note:

The returned future has its parent set to this instance. Unless its parent is changed (using #QObject::setParent()), the future will be destroyed when this instance is destroyed.

,

To minimize memory usage, explicitly destroy the returned object using #QObject::deleteLater() instead of relying on the implicit cleanup that occurs due to the QObject parent-child relationship.

Parameters
request

The data used to construct the timer request message. If the timer request has a specific time which is of type #InvokeDateTime::Anchored, the assigned time zone may or may not be recognized. If the assigned time zone is not recognized the timer registration request will fail.(the returned #InvokeReply will contain an error after its finished() signal is emitted).

Return:

A future representing the result this operation or 0 if the register message could not be sent.

Since:

BlackBerry 10.3.0

bool requestCardReadyCheck (
  • boolcheck)

Requests that the card be notified before its window is displayed.

When requested, the cardReadyCheck() signal will be emitted before the card's window is shown. The window will not be shown until the card calls cardReady() or the system timeout for this operation expires.

The request can be made at any time during the card's lifecycle, and applies to all subsequent appearances of the card's window. If the card wishes to be notified before its first appearance, this request must precede the posting of a window.

Parameters
check

true if the card should be notified before its window is displayed, false otherwise.

Return:

true if the operation was successful, false otherwise.

Since:

BlackBerry 10.0.0

InvokeRequestTargetFiltersReply * requestTargetFilters (

Constructs a message to request the set of filters that are associated with a target.

The calling entity can only request filters for targets that it owns.

Note:

The length of targetKey must not exceed 50 bytes. If the size limit is exceeded, an InvokeRequestTargetFiltersReply shall be returned with error() set to InvokeReplyError::BadRequest.

,

The returned future has its parent set to this instance. Unless its parent is changed (using QObject::setParent()), the future will be destroyed when this instance is destroyed.

,

To minimize memory usage, explicitly destroy the returned object using QObject::deleteLater() instead of relying on the implicit cleanup that occurs due to the QObject parent-child relationship.

Parameters
targetKey

The target key that identifies the target for which filters will be requested.

Return:

A future representing the result this operation or 0 if the query message could not be sent.

Since:

BlackBerry 10.0.0

bool selectListItem (

Requests that this list item be replaced with the list item determined by direction.

The request will fail if this application was not launched as a result of a list invocation. If the request is successful, the current list item will be closed in the normal manner (including the usual applicable signals such as cardPooled).

Parameters
direction

Whether to activate the previous or next list item.

Return:

true if the request was successfully sent, false otherwise.

Since:

BlackBerry 10.2.0

bool sendCardDone (

Tells the card's parent that it has completed its intended activity and that the parent can close the card.

The parent will be notified via the childCardDone(const CardDoneMessage&) signal. Once the card has been moved off screen, it will be pooled so that if it is invoked again, it can resume processing quickly. The card will be notified of this via the cardPooled(const CardDoneMessage&) signal. Upon reception of this signal, the card should transition to a state in which it is ready to be invoked again.

Parameters
message

A completion message for the card's parent.

Return:

true if operation was successful, false otherwise.

Since:

BlackBerry 10.0.0

bb::system::ApplicationStartupMode::Type startupMode ()

Returns the reason this application was launched.

Use this method to determine if your application was launched as the result of an invoke message.

Return:

The reason this application was launched. See bb::system::ApplicationStartupMode for the list of startup modes.

Since:

BlackBerry 10.0.0

bool swipeAway ()

Tells the invocation framework that the application and its stack of cards have been swiped away.

A "swipe away" gesture is a horizontal swipe utilized by the Universal Inbox (UIB) to hide itself and all of its child cards. The UIB can be dismissed using this gesture. Instead of closing, the UIB and any open cards are slid off-screen and remain in the same state so that activity can be resumed when the UIB is brought to the foreground again.

Any card that can be invoked directly by the UIB or indirectly as part of the UIB's card stack should detect the swipe away gesture and call swipeAway() when detected.

Return:

true if the notification was successfully sent, false otherwise.

Since:

BlackBerry 10.0.0

InvokeReply * updateTargetFilters (

Constructs a message to update the set of filters that will be applied when determining whether a target should be a candidate for an unbound invocation.

Note:

The returned future has its parent set to this instance. Unless its parent is changed (using QObject::setParent()), the future will be destroyed when this instance is destroyed.

,

To minimize memory usage, explicitly destroy the returned object using QObject::deleteLater() instead of relying on the implicit cleanup that occurs due to the QObject parent-child relationship.

Parameters
request

The data used to construct the request message.

Return:

A future representing the result this operation or 0 if the query message could not be sent.

Since:

BlackBerry 10.0.0

Signals

void cardPeekEnded ()

Emitted when the card has been released from the peek.

Since:

BlackBerry 10.0.0

void cardPeekStarted (

Emitted when the card has been pulled to the side, to peek to an application or card under it in the stack.

Parameters
peekType

The type of peek that was issued. See bb::system::CardPeek for the list of peek types.

Since:

BlackBerry 10.0.0

void cardPooled (

Emitted when the card has been moved off-screen and has been pooled.

Upon receipt of this signal, the card should transition to a state in which it is ready to be invoked again.

Parameters
message

A message describing the reason the card was closed.

Since:

BlackBerry 10.0.0

void cardReadyCheck ()

Emitted when a card's window is about to be displayed.

The window will not be displayed until the card calls cardReady() or the system timeout for this operation expires.

This signal is only emitted if it has been requested by a previous call to requestCardReadyCheck().

Since:

BlackBerry 10.0.0

void cardResizeRequested (

Emitted when this card has received a request to resize.

Parameters
message

A message describing the resize parameters.

Since:

BlackBerry 10.0.0

void childCardDone (

Emitted to the parent of a card to notify it that the child card has completed its tasks and has been moved off-screen and pooled.

Parameters
message

A message containing the results from the child.

Since:

BlackBerry 10.0.0

void childPeekEnded ()

Emitted on an application or card when a child card has been released from a peek operation, hiding this application or card.

Since:

BlackBerry 10.0.0

void childPeekStarted (

Emitted on an application or card when a child card has been pulled to the side, to peek at this application or card.

Parameters
peekType

The type of peek that was issued. See bb::system::CardPeek for the list of possible peek types.

Since:

BlackBerry 10.0.0

void invoked (

Emitted when this application receives an invoke message and should run as an application or as a card.

Parameters
request

The data contained in the invoke message.

Since:

BlackBerry 10.0.0

void listCursorMoved (

Emitted to indicate the cursor position of list listId has moved in the direction direction.

listCursorMoved signals are emitted only after childPeekStarted has been emitted. The movement is considered to have ended when listItemSelectedFromCursor signal is emitted, or when childPeekEnded signal is emitted. If childPeekEnded signal is emitted first, then the request for list item selection is considered to be canceled.

Parameters
listId

The list this request refers to.

direction

The direction of movement of the cursor.

Since:

BlackBerry 10.2.0

void listItemSelected (

Emitted when a transition has been requested from the currently active list item of listId to the selection item.

The current list item will be replaced with the next invoke request which belongs to the same list. childCardDone will be emitted when the current list item has been transitioned out.

Parameters
listId

The list this request refers to.

direction

Whether to activate the previous or next list item.

Since:

BlackBerry 10.2.0

void listItemSelectedFromCursor (
  • intlistId)

Emitted when a transition has been requested from the currently active list item of listId to the item selected based on the previous listCursorMoved signals.

This signal will be emitted during a peek, and will cause the termination of the peek, and closing of the current list item. childPeekEnded() and childCardDone() will be emitted when those events take place.

Parameters
listId

The list this request refers to.

Since:

BlackBerry 10.2.0

Last modified: 2014-09-30



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

comments powered by Disqus