InvokeRequest

#include <bb/system/InvokeRequest>

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

Encapsulates a request to invoke a remote application, card or service.

Clients send invoke messages to a target by creating an instance of InvokeRequest, populating it with data, and passing the object to InvokeManager::invoke(). An invoke messages must contain a MIME type. All other fields are optional.

Targets handle invoke messages by connecting to the InvokeManager::invoked() signal and parsing the InvokeRequest object passed to their slot.

Invoke requests can also belong to a specific invoke list. When the target of an invoke request belongs to a invoke list, then the user will be able to navigate among the list targets using gestures and keyboard shortcuts (bb::system::InvokeManager for more details).

Since:

BlackBerry 10.0.0

Public Functions Index

InvokeRequest ()
InvokeRequest (const InvokeRequest &other)
~InvokeRequest ()
InvokeRequest &operator= (const InvokeRequest &other)
bb::system::InvokeSourcesource () const
QStringtarget () const
QStringaction () const
QStringmimeType () const
QUrluri () const
bb::system::FileTransferMode::TypefileTransferMode () const
bb::system::InvokeTarget::TypestargetTypes () const
QByteArraydata () const
QVariantMapmetadata () const
bb::system::SecurityPerimeter::Typeperimeter () const
intlistId () const
voidsetTarget (const QString &name)
voidsetAction (const QString &name)
voidsetMimeType (const QString &type)
voidsetUri (const QUrl &uri)
voidsetUri (const QString &uri)
voidsetUri (const char *uri)
voidsetFileTransferMode (bb::system::FileTransferMode::Type fileTransferMode)
voidsetData (const QByteArray &data)
voidsetMetadata (const QVariantMap &metadata)
voidsetPerimeter (bb::system::SecurityPerimeter::Type perimeter)
voidsetListId (int listId)
voidsetTargetTypes (bb::system::InvokeTarget::Types types)

Public Functions

InvokeRequest ()

Creates a new InvokeRequest object.

Since:

BlackBerry 10.0.0

InvokeRequest (

Creates a copy of an existing InvokeRequest object.

Parameters
other

The source InvokeRequest object to copy.
Since:

BlackBerry 10.0.0

~InvokeRequest ()

Destructor.

Since:

BlackBerry 10.0.0

InvokeRequest & operator= (

Copies the data of an existing InvokeRequest object to this object.

Parameters
other

The source InvokeRequest object to copy.
Return:

The InvokeRequest instance.

Since:

BlackBerry 10.0.0

bb::system::InvokeSource source ()

Returns the source of this request.

This property is set when the application receives an invocation request.

Return:

The source of the request.

Since:

BlackBerry 10.0.0

QString target ()

Returns the identity of the receiver as stated in its BAR manifest file.

If omitted, the invocation service performs brokering to find the most appropriate target for the action and MIME type in this invocation request.

Required: NO.

Return:

The identity of the receiver or an empty string if invocation service should perform brokering.

Since:

BlackBerry 10.0.0

QString action ()

Returns the operation the client is asking the target to perform.

Valid values are target-specific. If omitted, the invocation service or target will choose an appropriate action based on the MIME type.

Required: NO.

Return:

The operation the client is asking the target to perform or an empty string if the invocation service or target should choose an appropriate action.

Since:

BlackBerry 10.0.0

QString mimeType ()

Returns the format of the data sent to the target.

The MIME type must be a valid Internet media type, such as "image/png".

Required: YES.

Return:

The Internet media type of the data.

Since:

BlackBerry 10.0.0

QUrl uri ()

Returns the uniform resource identifier (URI) sent to the target.

If omitted, the MIME type, action, and/or data are sufficient for the target to do its work.

Required: NO.

Return:

The uniform resource identifier (URI) sent to the target or an empty URI if the target does not require a URI.

Since:

BlackBerry 10.0.0

bb::system::FileTransferMode::Type fileTransferMode ()

Returns the file transfer mode for this request.

The file transfer mode controls how a file specified by the URI in an invocation request (if present) is transferred to the target.

If omitted, the default transfer mode will apply.

Required: NO.

Return:

The file transfer mode for this request. See bb::system::FileTransferMode for the list of file transfer modes.

Since:

BlackBerry 10.0.0

bb::system::InvokeTarget::Types targetTypes ()

Returns the class of targets that will be considered for an unbound invocation.

Required: NO.

See:

bb::system::InvokeTarget::Type for the list of individual target types.

Note:

targetTypes() only applies to the InvokeRequest sent to the invocation framework. It is not available in the InvokeRequest received by the invoked target.

Return:

The class of targets that will be considered for an unbound invocation.

Since:

BlackBerry 10.0.0

QByteArray data ()

Returns the binary data sent to the target.

Valid values are target-specific. If omitted, the specified MIME type, action, and URI must be sufficient for the target to complete the request.

Required: NO.

Return:

The binary data sent to the target or an empty array if the target does not require any data.

Since:

BlackBerry 10.0.0

QVariantMap metadata ()

Returns the metadata sent to the target.

Metadata is optional and can be included to pass additional information to the target. It will be encoded as a JSON object and sent to the target.

Required: NO.

Return:

The metadata.

Since:

BlackBerry 10.0.0

bb::system::SecurityPerimeter::Type perimeter ()

Returns the security perimeter requested for the target.

Required: NO.

Return:

The security perimeter for the request. See bb::system::SecurityPerimeter for the list of perimeters.

Since:

BlackBerry 10.0.0

int listId ()

Returns the list that this request belongs to.

Requests can belong to lists that are navigable. This allows the user to navigate to the previous and next items in the list.

Required: NO.

Return:

The list the request belongs to or 0 if the request should not belong to a list.

Since:

BlackBerry 10.2.0

void setTarget (

Sets the identity of the receiver as stated in its BAR manifest.

If omitted, the invocation service performs brokering to find the most appropriate target for the action and MIME type in this invocation request.

Required: NO.

Parameters
name

The identity of the receiver or an empty string if invocation service should perform brokering.
Since:

BlackBerry 10.0.0

void setAction (

Sets the operation the client is asking the target to perform.

Valid values are target-specific. If omitted, the invocation service or target will choose an appropriate action based on the MIME type.

Required: NO.

Parameters
name

The operation the client is asking the target to perform or an empty string if the invocation service or target should choose an appropriate action.
Since:

BlackBerry 10.0.0

void setMimeType (

Sets the format of the data sent to the target.

The MIME type must be a valid Internet media type, such as "image/png".

Required: YES.

Parameters
type

The Internet media type of the data.
Since:

BlackBerry 10.0.0

void setUri (

Sets the uniform resource identifier (URI) sent to the target.

If omitted, the specified MIME type, action, and data must be sufficient for the target to do its work.

Note:

For URIs to local files, consider using QUrl::fromLocalFile() to construct a QUrl instance.

Required: NO.
Parameters
uri

The uniform resource identifier (URI) sent to the target or an empty URI if the target does not require a URI.
Since:

BlackBerry 10.0.0

void setUri (

Sets the uniform resource identifier (URI) sent to the target.

If omitted, the specified MIME type, action, and data must be sufficient for the target to do its work.

Note:

Use this method to pass a URI that is in human-readable format.

,

QUrl(const QString&) will be used for constructing the URI.

Required: NO.
Parameters
uri

A string representing the uniform resource identifier (URI) sent to the target, or an empty string if the target does not require a URI.
Since:

BlackBerry 10.0.0

void setUri (
  • const char *uri)

Sets the uniform resource identifier (URI) sent to the target.

If omitted, the specified MIME type, action, and data must be sufficient for the target to do its work.

Note:

Use this method to pass a URI that is in human-readable format in UTF-8 encoding.

,

QUrl(const QString&) will be used for constructing the URI.

Required: NO.
Parameters
uri

A character array representing the uniform resource identifier (URI) sent to the target, or an empty character array if the target does not require a URI.
Since:

BlackBerry 10.0.0

void setFileTransferMode (

Sets the file transfer mode for the request.

The file transfer mode controls how a file specified by the URI in an invocation request (if present) is transferred to the target.

Required: NO.

Parameters
fileTransferMode

The file transfer mode for this request. See bb::system::FileTransferMode for the list of file transfer modes.
Since:

BlackBerry 10.0.0

void setData (

Sets the binary data sent to the target.

Valid values are target-specific. If omitted, the specified MIME type, action and URI must be sufficient for the target to complete the request.

Required: NO.

Parameters
data

The binary data sent to the target or an empty array if the target does not require any data.
Since:

BlackBerry 10.0.0

void setMetadata (

Sets the metadata sent to the target.

Metadata is optional and can be included to pass additional information to the target. It will be encoded as a JSON object and sent to the target.

Required: NO.

Parameters
metadata

The metadata to be sent to the target.
Since:

BlackBerry 10.0.0

void setPerimeter (

Sets the security perimeter in which the target should be invoked.

Required: NO.

The service can override this value to invoke the target in the same perimeter as the calling application based on its permissions.

Parameters
perimeter

The security perimeter for the invoked target. See bb::system::SecurityPerimeter for the list of valid values.
Since:

BlackBerry 10.0.0

void setListId (
  • intlistId)

Sets the list that this request belongs to.

Requests can belong to lists that are navigable. This allows the user to navigate to the previous and next items in the list. bb::system::InvokeManager includes signals and functions that allow for list operations.

Note:

The invoke target must have a list-compatible bb::system::InvokeTarget::Type for list navigation to be enabled. bb::system::InvokeTarget::Card is currently the only list-enabled type.

,

An application can have only one currently active list.

Required: NO.
Parameters
listId

The list the request belongs to or 0 if the request should not belong to a list.
Since:

BlackBerry 10.2.0

void setTargetTypes (
  • bb::system::InvokeTarget::Typestypes)

Sets the class of targets that will be considered for an unbound invocation.

Required: NO.

Note:

targetTypes() only applies to the InvokeRequest sent to the invocation framework. It is not available in the InvokeRequest received by the invoked target.

Parameters
types

The class of targets that will be considered for an unbound invocation. See bb::system::InvokeTarget::Type for the list of individual target types.
Since:

BlackBerry 10.0.0