android.content.IntentFilter
Structured description of Intent values to be matched. An IntentFilter can
match against actions, categories, and data (either via its type, scheme,
and/or path) in an Intent. It also includes a "priority" value which is
used to order multiple matching filters.
IntentFilter objects are often created in XML as part of a package's
AndroidManifest.xml file,
using intent-filter
tags.
There are three Intent characteristics you can filter on: the
action, data, and categories. For each of these
characteristics you can provide
multiple possible matching values (via addAction(String),
addDataType(String), addDataScheme(String) addDataAuthority(String, String),
addDataPath(String, int), and addCategory(String), respectively).
For actions, the field
will not be tested if no values have been given (treating it as a wildcard);
if no data characteristics are specified, however, then the filter will
only match intents that contain no data.
The data characteristic is
itself divided into three attributes: type, scheme, authority, and path.
Any that are
specified must match the contents of the Intent. If you specify a scheme
but no type, only Intent that does not have a type (such as mailto:) will
match; a content: URI will never match because they always have a MIME type
that is supplied by their content provider. Specifying a type with no scheme
has somewhat special meaning: it will match either an Intent with no URI
field, or an Intent with a content: or file: URI. If you specify neither,
then only an Intent with no data or type will match. To specify an authority,
you must also specify one or more schemes that it is associated with.
To specify a path, you also must specify both one or more authorities and
one or more schemes it is associated with.
A match is based on the following rules. Note that
for an IntentFilter to match an Intent, three conditions must hold:
the action and category must match, and
the data (both the data type and
data scheme+authority+path if specified) must match.
Action matches if any of the given values match the
Intent action, or if no actions were specified in the filter.
Data Type matches if any of the given values match the
Intent type. The Intent
type is determined by calling resolveType(ContentResolver). A wildcard can be
used for the MIME sub-type, in both the Intent and IntentFilter, so that the
type "audio/*" will match "audio/mpeg", "audio/aiff", "audio/*", etc.
Data Scheme matches if any of the given values match the
Intent data's scheme.
The Intent scheme is determined by calling getData()
and getScheme() on that URI.
Data Authority matches if any of the given values match
the Intent's data authority and one of the data scheme's in the filter
has matched the Intent, or no authories were supplied in the filter.
The Intent authority is determined by calling
getData() and getAuthority() on that URI.
Data Path matches if any of the given values match the
Intent's data path and both a scheme and authority in the filter
has matched against the Intent, or no paths were supplied in the
filter. The Intent authority is determined by calling
getData() and getPath() on that URI.
Categories match if all of the categories in
the Intent match categories given in the filter. Extra categories in the
filter that are not in the Intent will not cause the match to fail. Note
that unlike the action, an IntentFilter with no categories
will only match an Intent that does not have any categories.
Nested Classes
Summary
Constants
|
|
|
Value |
|
Creator<IntentFilter> |
CREATOR |
|
|
|
int |
MATCH_ADJUSTMENT_MASK |
The part of a match constant that applies a quality adjustment to the
basic category of match. |
65535 |
0x0000ffff |
int |
MATCH_ADJUSTMENT_NORMAL |
|
32768 |
0x00008000 |
int |
MATCH_CATEGORY_EMPTY |
The filter matched an intent that had no data specified. |
1048576 |
0x00100000 |
int |
MATCH_CATEGORY_HOST |
The filter matched an intent with the same data URI scheme and
authority host. |
3145728 |
0x00300000 |
int |
MATCH_CATEGORY_MASK |
The part of a match constant that describes the category of match
that occurred. |
268369920 |
0x0fff0000 |
int |
MATCH_CATEGORY_PATH |
The filter matched an intent with the same data URI scheme,
authority, and path. |
5242880 |
0x00500000 |
int |
MATCH_CATEGORY_PORT |
The filter matched an intent with the same data URI scheme and
authority host and port. |
4194304 |
0x00400000 |
int |
MATCH_CATEGORY_SCHEME |
The filter matched an intent with the same data URI scheme. |
2097152 |
0x00200000 |
int |
MATCH_CATEGORY_TYPE |
The filter matched an intent with the same data MIME type. |
6291456 |
0x00600000 |
int |
NO_MATCH_ACTION |
The filter didn't match due to different actions. |
-3 |
0xfffffffd |
int |
NO_MATCH_CATEGORY |
The filter didn't match because it required one or more categories
that were not in the Intent. |
-4 |
0xfffffffc |
int |
NO_MATCH_DATA |
The filter didn't match due to different data URIs. |
-2 |
0xfffffffe |
int |
NO_MATCH_TYPE |
The filter didn't match due to different MIME types. |
-1 |
0xffffffff |
int |
SYSTEM_HIGH_PRIORITY |
The filter setPriority(int) value at which system high-priority
receivers are placed; that is, receivers that should execute before
application code. |
1000 |
0x000003e8 |
int |
SYSTEM_LOW_PRIORITY |
The filter setPriority(int) value at which system low-priority
receivers are placed; that is, receivers that should execute after
application code. |
-1000 |
0xfffffc18 |
Public Constructors
Public Methods
|
|
final |
|
|
Iterator<String> |
actionsIterator() |
|
|
final |
|
|
void |
addAction(String action) |
|
|
final |
|
|
void |
addCategory(String category) |
|
|
final |
|
|
void |
addDataAuthority(String host, String port) |
|
|
final |
|
|
void |
addDataPath(String path, int type) |
|
|
final |
|
|
void |
addDataScheme(String scheme) |
|
|
final |
|
|
void |
addDataType(String type) |
|
|
final |
|
|
Iterator<IntentFilter.AuthorityEntry> |
authoritiesIterator() |
|
|
final |
|
|
Iterator<String> |
categoriesIterator() |
|
|
final |
|
|
int |
countActions() |
|
|
final |
|
|
int |
countCategories() |
|
|
final |
|
|
int |
countDataAuthorities() |
|
|
final |
|
|
int |
countDataPaths() |
|
|
final |
|
|
int |
countDataSchemes() |
|
|
final |
|
|
int |
countDataTypes() |
|
|
|
static |
|
IntentFilter |
create(String action, String dataType) |
|
|
final |
|
|
int |
describeContents() |
|
|
|
|
|
void |
dump(Printer du, String prefix) |
|
|
final |
|
|
String |
getAction(int index) |
|
|
final |
|
|
String |
getCategory(int index) |
|
|
final |
|
|
IntentFilter.AuthorityEntry |
getDataAuthority(int index) |
|
|
final |
|
|
PatternMatcher |
getDataPath(int index) |
|
|
final |
|
|
String |
getDataScheme(int index) |
|
|
final |
|
|
String |
getDataType(int index) |
|
|
final |
|
|
int |
getPriority() |
|
|
final |
|
|
boolean |
hasAction(String action) |
|
|
final |
|
|
boolean |
hasCategory(String category) |
|
|
final |
|
|
boolean |
hasDataAuthority(Uri data) |
|
|
final |
|
|
boolean |
hasDataPath(String data) |
|
|
final |
|
|
boolean |
hasDataScheme(String scheme) |
|
|
final |
|
|
boolean |
hasDataType(String type) |
|
|
final |
|
|
int |
match(String action, String type, String scheme, Uri data, Set<String> categories, String logTag) |
|
|
final |
|
|
int |
match(ContentResolver resolver, Intent intent, boolean resolve, String logTag) |
|
|
final |
|
|
boolean |
matchAction(String action) |
|
|
final |
|
|
String |
matchCategories(Set<String> categories) |
|
|
final |
|
|
int |
matchData(String type, String scheme, Uri data) |
|
|
final |
|
|
int |
matchDataAuthority(Uri data) |
|
|
final |
|
|
Iterator<PatternMatcher> |
pathsIterator() |
|
|
|
|
|
void |
readFromXml(XmlPullParser parser) |
|
|
final |
|
|
Iterator<String> |
schemesIterator() |
|
|
final |
|
|
void |
setPriority(int priority) |
|
|
final |
|
|
Iterator<String> |
typesIterator() |
|
|
final |
|
|
void |
writeToParcel(Parcel dest, int flags) |
|
|
|
|
|
void |
writeToXml(XmlSerializer serializer) |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Constants
public
static
final
int
MATCH_ADJUSTMENT_MASK
The part of a match constant that applies a quality adjustment to the
basic category of match. The value
MATCH_ADJUSTMENT_NORMAL
is no adjustment; higher numbers than that improve the quality, while
lower numbers reduce it.
Constant Value:
65535
(0x0000ffff)
public
static
final
int
MATCH_ADJUSTMENT_NORMAL
Constant Value:
32768
(0x00008000)
public
static
final
int
MATCH_CATEGORY_EMPTY
The filter matched an intent that had no data specified.
Constant Value:
1048576
(0x00100000)
public
static
final
int
MATCH_CATEGORY_HOST
The filter matched an intent with the same data URI scheme and
authority host.
Constant Value:
3145728
(0x00300000)
public
static
final
int
MATCH_CATEGORY_MASK
public
static
final
int
MATCH_CATEGORY_PATH
The filter matched an intent with the same data URI scheme,
authority, and path.
Constant Value:
5242880
(0x00500000)
public
static
final
int
MATCH_CATEGORY_PORT
The filter matched an intent with the same data URI scheme and
authority host and port.
Constant Value:
4194304
(0x00400000)
public
static
final
int
MATCH_CATEGORY_SCHEME
The filter matched an intent with the same data URI scheme.
Constant Value:
2097152
(0x00200000)
public
static
final
int
MATCH_CATEGORY_TYPE
The filter matched an intent with the same data MIME type.
Constant Value:
6291456
(0x00600000)
public
static
final
int
NO_MATCH_ACTION
The filter didn't match due to different actions.
Constant Value:
-3
(0xfffffffd)
public
static
final
int
NO_MATCH_CATEGORY
The filter didn't match because it required one or more categories
that were not in the Intent.
Constant Value:
-4
(0xfffffffc)
public
static
final
int
NO_MATCH_DATA
The filter didn't match due to different data URIs.
Constant Value:
-2
(0xfffffffe)
public
static
final
int
NO_MATCH_TYPE
The filter didn't match due to different MIME types.
Constant Value:
-1
(0xffffffff)
public
static
final
int
SYSTEM_HIGH_PRIORITY
The filter
setPriority(int) value at which system high-priority
receivers are placed; that is, receivers that should execute before
application code. Applications should never use filters with this or
higher priorities.
Constant Value:
1000
(0x000003e8)
public
static
final
int
SYSTEM_LOW_PRIORITY
The filter
setPriority(int) value at which system low-priority
receivers are placed; that is, receivers that should execute after
application code. Applications should never use filters with this or
lower priorities.
Constant Value:
-1000
(0xfffffc18)
Public Constructors
public
IntentFilter()
New empty IntentFilter.
public
IntentFilter(String action)
New IntentFilter that matches a single action with no data. If
no data characteristics are subsequently specified, then the
filter will only match intents that contain no data.
Parameters
action
| The action to match, i.e. Intent.ACTION_MAIN.
|
public
IntentFilter(String action, String dataType)
New IntentFilter that matches a single action and data type.
Throws IntentFilter.MalformedMimeTypeException if the given MIME type is
not syntactically correct.
Parameters
action
| The action to match, i.e. Intent.ACTION_VIEW. |
dataType
| The type to match, i.e. "vnd.android.cursor.dir/person".
|
New IntentFilter containing a copy of an existing filter.
Parameters
o
| The original filter to copy.
|
Public Methods
public
final
Iterator<String>
actionsIterator()
Return an iterator over the filter's actions. If there are no actions,
returns null.
public
final
void
addAction(String action)
Add a new Intent action to match against. If any actions are included
in the filter, then an Intent's action must be one of those values for
it to match. If no actions are included, the Intent action is ignored.
Parameters
action
| Name of the action to match, i.e. Intent.ACTION_VIEW.
|
public
final
void
addCategory(String category)
Add a new Intent category to match against. The semantics of
categories is the opposite of actions -- an Intent includes the
categories that it requires, all of which must be included in the
filter in order to match. In other words, adding a category to the
filter has no impact on matching unless that category is specified in
the intent.
Parameters
category
| Name of category to match, i.e. Intent.CATEGORY_EMBED.
|
public
final
void
addDataAuthority(String host, String port)
Add a new Intent data authority to match against. The filter must
include one or more schemes (via
addDataScheme(String)) for the
authority to be considered. If any authorities are
included in the filter, then an Intent's data must match one of
them. If no authorities are included, then only the scheme must match.
Parameters
host
| The host part of the authority to match. May start with a
single '*' to wildcard the front of the host name. |
port
| Optional port part of the authority to match. If null, any
port is allowed. |
public
final
void
addDataPath(String path, int type)
Add a new Intent data oath to match against. The filter must
include one or more schemes (via
addDataScheme(String))
and
one or more authorities (via
addDataAuthority(String, String)) for the
path to be considered. If any paths are
included in the filter, then an Intent's data must match one of
them. If no paths are included, then only the scheme/authority must
match.
The path given here can either be a literal that must directly
match or match against a prefix, or it can be a simple globbing pattern.
If the latter, you can use '*' anywhere in the pattern to match zero
or more instances of the previous character, '.' as a wildcard to match
any character, and '\' to escape the next character.
public
final
void
addDataScheme(String scheme)
Add a new Intent data scheme to match against. If any schemes are
included in the filter, then an Intent's data must be
either
one of these schemes
or a matching data type. If no schemes
are included, then an Intent will match only if it includes no data.
Parameters
scheme
| Name of the scheme to match, i.e. "http:". |
public
final
void
addDataType(String type)
Add a new Intent data type to match against. If any types are
included in the filter, then an Intent's data must be
either
one of these types
or a matching scheme. If no data types
are included, then an Intent will only match if it specifies no data.
Throws IntentFilter.MalformedMimeTypeException if the given MIME type is
not syntactically correct.
Parameters
type
| Name of the data type to match, i.e. "vnd.android.cursor.dir/person". |
Return an iterator over the filter's data authorities.
public
final
Iterator<String>
categoriesIterator()
Return an iterator over the filter's categories.
public
final
int
countActions()
Return the number of actions in the filter.
public
final
int
countCategories()
Return the number of categories in the filter.
public
final
int
countDataAuthorities()
Return the number of data authorities in the filter.
public
final
int
countDataPaths()
Return the number of data paths in the filter.
public
final
int
countDataSchemes()
Return the number of data schemes in the filter.
public
final
int
countDataTypes()
Return the number of data types in the filter.
Create a new IntentFilter instance with a specified action and MIME
type, where you know the MIME type is correctly formatted. This catches
the
IntentFilter.MalformedMimeTypeException exception that the constructor
can call and turns it into a runtime exception.
Parameters
action
| The action to match, i.e. Intent.ACTION_VIEW. |
dataType
| The type to match, i.e. "vnd.android.cursor.dir/person". |
Returns
- A new IntentFilter for the given action and type.
public
final
int
describeContents()
Describe the kinds of special objects contained in this Parcelable's
marshalled representation.
public
final
String
getAction(int index)
Return an action in the filter.
public
final
String
getCategory(int index)
Return a category in the filter.
Return a data authority in the filter.
public
final
PatternMatcher
getDataPath(int index)
Return a data path in the filter.
public
final
String
getDataScheme(int index)
Return a data scheme in the filter.
public
final
String
getDataType(int index)
Return a data type in the filter.
public
final
int
getPriority()
Return the priority of this filter.
Returns
- The priority of the filter.
public
final
boolean
hasAction(String action)
Is the given action included in the filter? Note that if the filter
does not include any actions, false will
always be returned.
Parameters
action
| The action to look for. |
Returns
- True if the action is explicitly mentioned in the filter.
public
final
boolean
hasCategory(String category)
Is the given category included in the filter?
Parameters
category
| The category that the filter supports. |
Returns
- True if the category is explicitly mentioned in the filter.
public
final
boolean
hasDataAuthority(Uri data)
Is the given data authority included in the filter? Note that if the
filter does not include any authorities, false will
always be
returned.
Parameters
data
| The data whose authority is being looked for. |
Returns
- Returns true if the data string matches an authority listed in the
filter.
public
final
boolean
hasDataPath(String data)
Is the given data path included in the filter? Note that if the
filter does not include any paths, false will
always be
returned.
Parameters
data
| The data path to look for. This is without the scheme
prefix. |
Returns
- True if the data string matches a path listed in the
filter.
public
final
boolean
hasDataScheme(String scheme)
Is the given data scheme included in the filter? Note that if the
filter does not include any scheme, false will
always be
returned.
Parameters
scheme
| The data scheme to look for. |
Returns
- True if the scheme is explicitly mentioned in the filter.
public
final
boolean
hasDataType(String type)
Is the given data type included in the filter? Note that if the filter
does not include any type, false will
always be returned.
Parameters
type
| The data type to look for. |
Returns
- True if the type is explicitly mentioned in the filter.
public
final
int
match(String action, String type, String scheme, Uri data, Set<String> categories, String logTag)
Test whether this filter matches the given intent data. A match is
only successful if the actions and categories in the Intent match
against the filter, as described in
IntentFilter; in that case,
the match result returned will be as per
matchData(String, String, Uri).
Parameters
action
| The intent action to match against (Intent.getAction). |
type
| The intent type to match against (Intent.resolveType()). |
scheme
| The data scheme to match against (Intent.getScheme()). |
data
| The data URI to match against (Intent.getData()). |
categories
| The categories to match against
(Intent.getCategories()). |
logTag
| Tag to use in debugging messages. |
public
final
int
match(ContentResolver resolver, Intent intent, boolean resolve, String logTag)
Test whether this filter matches the given
intent.
Parameters
intent
| The Intent to compare against. |
resolve
| If true, the intent's type will be resolved by calling
Intent.resolveType(); otherwise a simple match against
Intent.type will be performed. |
logTag
| Tag to use in debugging messages. |
public
final
boolean
matchAction(String action)
Match this filter against an Intent's action. If the filter does not
specify any actions, the match will always fail.
Parameters
action
| The desired action to look for. |
Returns
- True if the action is listed in the filter or the filter does
not specify any actions.
public
final
String
matchCategories(Set<String> categories)
Match this filter against an Intent's categories. Each category in
the Intent must be specified by the filter; if any are not in the
filter, the match fails.
Parameters
categories
| The categories included in the intent, as returned by
Intent.getCategories(). |
Returns
- If all categories match (success), null; else the name of the
first category that didn't match.
public
final
int
matchData(String type, String scheme, Uri data)
Match this filter against an Intent's data (type, scheme and path). If
the filter does not specify any types and does not specify any
schemes/paths, the match will only succeed if the intent does not
also specify a type or data.
Note that to match against an authority, you must also specify a base
scheme the authority is in. To match against a data path, both a scheme
and authority must be specified. If the filter does not specify any
types or schemes that it matches against, it is considered to be empty
(any authority or data path given is ignored, as if it were empty as
well).
Parameters
type
| The desired data type to look for, as returned by
Intent.resolveType(). |
scheme
| The desired data scheme to look for, as returned by
Intent.getScheme(). |
data
| The full data string to match against, as supplied in
Intent.data. |
public
final
int
matchDataAuthority(Uri data)
Match this intent filter against the given Intent data. This ignores
the data scheme -- unlike
matchData(String, String, Uri), the authority will match
regardless of whether there is a matching scheme.
Parameters
data
| The data whose authority is being looked for. |
Return an iterator over the filter's data paths.
public
void
readFromXml(XmlPullParser parser)
public
final
Iterator<String>
schemesIterator()
Return an iterator over the filter's data schemes.
public
final
void
setPriority(int priority)
Modify priority of this filter. The default priority is 0. Positive
values will be before the default, lower values will be after it.
Applications must use a value that is larger than
SYSTEM_LOW_PRIORITY and smaller than
SYSTEM_HIGH_PRIORITY .
Parameters
priority
| The new priority value. |
public
final
Iterator<String>
typesIterator()
Return an iterator over the filter's data types.
public
final
void
writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel.
public
void
writeToXml(XmlSerializer serializer)
Write the contents of the IntentFilter as an XML stream.