InvokeTargetFilter

#include <bb/system/InvokeTargetFilter>

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

Describes the kinds of unbound invocations supported by a target.

Through unbound invocation a target will only receive invocations that match one of its filters. A filter describes the action/MIME type/URI combinations for which the target supports unbound invocation.

An invocation target filter must be specified as follows:
  • The filter must contain at least one valid action in actionList(). An action can be up to 50 characters based on the following grammar:

    • action: <domain><sub-domain>

    • domain: [a-zA-Z] ([a-zA-Z0-9_])*

    • sub-domain: NUL | .<domain><sub-domain>

    An example action is "bb.action.VIEW". This maps to the "actions" attribute of an Invoke-Target-Filter as defined in the BAR manifest.

  • The filter must contain at least one valid MIME type in mimeTypeList(). A valid MIME type is of the form:

    • mimetype: type subtype

    • type: [a-zA-Z0-9_]+

    • subtype: NUL | / [a-zA-Z0-9_-.+]+

    A MIME type may include wildcards for the complete type (e.g., "*") or for the subtype only (e.g., "image/*"). The MIME type maps to the "types" attribute of an Invoke-Target-Filter as defined in the BAR manifest.

  • The filter may contain a list of URI prefixes in uriList() which can be used as criteria to match the URI in the invocation request (e.g., "file://", "http://localhost:port", or "file://specific/path/"). This maps to the "uris" attribute of an Invoke-Target-Filter as defined in the BAR manifest. If no URIs are specified then the in-band URI ("data://local") is implied.

  • The filter may contain a list of supported file extensions in fileExtensionList() that must be suffix of the path to be a match (e.g. "jpg"). This maps to the "exts" attribute of an Invoke-Target-Filter as defined in the BAR manifest.

    Note that the file extensions are only applied if the scheme of the accompanying URI is "file://". Also note that combining file extensions and specific MIME types in a filter means both must be specified by a client for the filter to match. This can also work if the extension is for a known MIME type where the invocation framework will perform type inference. However, for most cases it is best to have the "exts" filter as a separate Target-Invoke-Filter declaration in the BAR manifest file that accepts any file of any MIME type (that is, the filter should include "uris=file://;types=*;" so the only filtering criteria will be the file extensions in the "exts" attribute).

An example of an invoke target filter, as defined in a BAR manifest, is as follows:

Invoke-Target-Filter:actions=bb.action.OPEN;types=vnd.custom.type;uris=file://;exts=acme;

Since:

BlackBerry 10.0.0

Public Functions Index

InvokeTargetFilter ()
InvokeTargetFilter (const InvokeTargetFilter &other)
~InvokeTargetFilter ()
InvokeTargetFilter &operator= (const InvokeTargetFilter &other)
QStringListactionList () const
booladdAction (const QString &action)
voidremoveAction (const QString &action)
QStringListmimeTypeList () const
booladdMimeType (const QString &mimeType)
voidremoveMimeType (const QString &mimeType)
QStringListuriList () const
voidaddUri (const QString &uri)
voidremoveUri (const QString &uri)
QStringListfileExtensionList () const
voidaddFileExtension (const QString &fileExtension)
voidremoveFileExtension (const QString &fileExtension)
QStringListcustomAttributeNames () const
QStringListcustomAttributeList (const QString &customAttribute) const
voidaddCustomAttributeValue (const QString &customAttribute, const QString &attributeValue)
voidremoveCustomAttributeValue (const QString &customAttribute, const QString &attributeValue)
voidremoveCustomAttribute (const QString &customAttribute)
boolisValid () const

Public Functions

InvokeTargetFilter ()

Creates a new InvokeTargetFilter object.

Since:

BlackBerry 10.0.0

InvokeTargetFilter (

Creates a copy of an existing InvokeTargetFilter object.

Parameters
other

The source InvokeTargetFilter object to copy.
Since:

BlackBerry 10.0.0

~InvokeTargetFilter ()

Destructor.

Since:

BlackBerry 10.0.0

InvokeTargetFilter & operator= (

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

Parameters
other

The source InvokeTargetFilter object to copy.
Return:

The InvokeTargetFilter instance.

Since:

BlackBerry 10.0.0

QStringList actionList ()

Returns the list of actions.

Return:

The list of actions.

Since:

BlackBerry 10.0.0

bool addAction (

Adds an action to the action list.

An action can be up to 50 characters based on the following grammar:

  • action: <domain><sub-domain>

  • domain: [a-zA-Z] ([a-zA-Z0-9_])*

  • sub-domain: NUL | .<domain><sub-domain>

Parameters
action

The action to add. If the action is already in the list, it is not added again.
Return:

Returns true if the action was added; false otherwise. An action is rejected if it is invalid (it is too long or does not match the grammar) or if it is already in the list.

Since:

BlackBerry 10.0.0

void removeAction (

Removes an action from the action list.

Parameters
action

The action to remove.
Since:

BlackBerry 10.0.0

QStringList mimeTypeList ()

Returns the list of MIME types.

Return:

The list of MIME types.

Since:

BlackBerry 10.0.0

bool addMimeType (

Adds a MIME type to the MIME type list.

A valid MIME type is of the form:

  • mimeType: type subtype

  • type: [a-zA-Z0-9_]+

  • subtype: NUL | / [a-zA-Z0-9_-.+]+

A MIME type may include wildcards for the complete type (e.g., "*") or for the subtype (e.g., "image/*").
Parameters
mimeType

The MIME type to add. If the MIME type is already in the list, it is not added again.
Return:

Returns true if the supplied MIME type was added to the list, false otherwise. A MIME type is rejected if it is invalid (it does not match the grammar) or if it is already in the list.

Since:

BlackBerry 10.0.0

void removeMimeType (

Removes a MIME type from the MIME type list.

Parameters
mimeType

The action to remove.
Since:

BlackBerry 10.0.0

QStringList uriList ()

Returns the list of URIs.

Return:

The list of URIs.

Since:

BlackBerry 10.0.0

void addUri (

Adds a URI to the URI list.

Parameters
uri

A string representing the URI to add. If the URI is already in the list, it is not added again.
Since:

BlackBerry 10.0.0

void removeUri (

Removes a URI from the URI list.

Parameters
uri

A string representing the URI to remove.
Since:

BlackBerry 10.0.0

QStringList fileExtensionList ()

Returns the list of file extensions.

Return:

The list of file extensions.

Since:

BlackBerry 10.0.0

void addFileExtension (

Adds a file extension to the file extension list.

Parameters
fileExtension

The file extension to add. If the file extension is already in the list, it is not added again.
Since:

BlackBerry 10.0.0

void removeFileExtension (

Removes a file extension from the file extension list.

Parameters
fileExtension

The file extension to remove.
Since:

BlackBerry 10.0.0

QStringList customAttributeNames ()

Returns a list of custom attribute names of the filter.

Use addCustomAttributeValue() and removeCustomAttributeValue()to manipulate the values of the custom attributes.

Return:

The list of custom attribute names.

Since:

BlackBerry 10.0.0

QStringList customAttributeList (

Returns the list of values for custom attribute customAttribute.

Use customAttributeNames() to retrieve the list of attribute names that can be used.

Parameters
customAttribute

The name of the custom attribute for which the values are requested.
Return:

The list of values for customAttribute.

Since:

BlackBerry 10.0.0

void addCustomAttributeValue (

Adds attributeValue to the list of values for custom attribute customAttribute.

If attributeValue has already been added to the list for customAttribute, it will not be added again.

Parameters
customAttribute

The name of the custom attribute to which to add attributeValue.

attributeValue

The value to add to the list of values for customAttribute.
Since:

BlackBerry 10.0.0

void removeCustomAttributeValue (

Removes attributeValue from the list of values for custom attribute customAttribute.

Parameters
customAttribute

The name of the custom attribute from which to remove attributeValue.

attributeValue

The value to remove from the list of values for customAttribute.
Since:

BlackBerry 10.0.0

void removeCustomAttribute (

Removes all values associated with custom attribute customAttribute.

Parameters
customAttribute

The name of the custom attribute from which to remove all attribute values.
Since:

BlackBerry 10.0.0

bool isValid ()

Returns an indication of whether this instance is valid.

An InvokeTargetFilter instance is valid if at least one action has been added and at least one MIME type has been added.

Return:

Returns true if this instance is valid, false otherwise.

Since:

BlackBerry 10.0.0