android.content
public class
public class
android.content.IntentFilter
| java.lang.Object | ||
| android.content.IntentFilter | Parcelable | |
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), 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, then any type will match; if you specify a type but no scheme, then any scheme will match. 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 either the data type or data scheme+authority+path 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
| IntentFilter.AuthorityEntry | This is an entry for a single authority in the Iterator returned by authoritiesIterator(). |
| IntentFilter.MalformedMimeTypeException | This exception is thrown when a given MIME type does not have a valid syntax. |
| IntentFilter.PathEntry | This is an entry for a single path in the Iterator returned by pathsIterator(). |
Summary
Constants
| Value | ||||
|---|---|---|---|---|
| Creator | CREATOR | |||
| int | MATCH_AUTHORITY | 30000 | 0x00007530 | |
| int | MATCH_EMPTY | 10000 | 0x00002710 | |
| int | MATCH_PATH | 40000 | 0x00009c40 | |
| int | MATCH_SCHEME | 20000 | 0x00004e20 | |
| int | MATCH_TYPE | 100000 | 0x000186a0 | |
| int | NO_MATCH_ACTION | -3 | 0xfffffffd | |
| int | NO_MATCH_CATEGORY | -4 | 0xfffffffc | |
| int | NO_MATCH_DATA | -2 | 0xfffffffe | |
| int | NO_MATCH_TYPE | -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
| IntentFilter() | |||||
| New empty IntentFilter. | |||||
| IntentFilter(String action) | |||||
| New IntentFilter that matches a single action. | |||||
| IntentFilter(String action, String dataType) | |||||
| New IntentFilter that matches a single action and data type. | |||||
| IntentFilter(IntentFilter o) | |||||
| New IntentFilter containing a copy of an existing filter. | |||||
Public Methods
| final | Iterator | actionsIterator() | |||
| Return an iterator over the filter's actions. | |||||
| final | void | addAction(String action) | |||
| Add a new Intent action to match against. | |||||
| final | void | addCategory(String category) | |||
| Add a new Intent category to match against. | |||||
| final | void | addDataAuthority(String host, String port) | |||
| Add a new Intent data authority to match against. | |||||
| final | void | addDataPath(String path) | |||
| Add a new Intent data oath to match against. | |||||
| final | void | addDataScheme(String scheme) | |||
| Add a new Intent data scheme to match against. | |||||
| final | void | addDataType(String type) | |||
| Add a new Intent data type to match against. | |||||
| final | Iterator | authoritiesIterator() | |||
| Return an iterator over the filter's data authorities. | |||||
| final | Iterator | categoriesIterator() | |||
| Return an iterator over the filter's categories. | |||||
| static | IntentFilter | create(String action, String dataType) | |||
| Create a new IntentFilter instance with a specified action and MIME type, where you know the MIME type is correctly formatted. | |||||
| void | dump(Printer du, String prefix) | ||||
| final | int | getPriority() | |||
| Return the priority of this filter. | |||||
| 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. | |||||
| final | boolean | hasCategory(String category) | |||
| Is the given category included in the filter? | |||||
| 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. | |||||
| 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. | |||||
| 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. | |||||
| 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. | |||||
| final | int | match(String action, String type, String scheme, Uri data, Set categories, String logTag) | |||
| Test whether this filter matches the given intent data. | |||||
| final | int | match(ContentResolver resolver, Intent intent, boolean resolve, String logTag) | |||
| Test whether this filter matches the given intent. | |||||
| final | boolean | matchAction(String action) | |||
| Match this filter against an Intent's action. | |||||
| final | String | matchCategories(Set categories) | |||
| Match this filter against an Intent's categories. | |||||
| final | int | matchData(String type, String scheme, Uri data) | |||
| Match this filter against an Intent's data (type, scheme and path). | |||||
| final | Iterator | pathsIterator() | |||
| Return an iterator over the filter's data paths. | |||||
| final | Iterator | schemesIterator() | |||
| Return an iterator over the filter's data schemes. | |||||
| final | void | setPriority(int priority) | |||
| Modify priority of this filter. | |||||
| final | Iterator | typesIterator() | |||
| Return an iterator over the filter's data types. | |||||
| final | void | writeToParcel(Parcel dest) | |||
Methods inherited
from class
java.lang.Object
Methods inherited
from interface
android.os.Parcelable
Details
Constants
public static final Creator CREATOR
public static final int MATCH_AUTHORITY
Constant Value:
30000
(0x00007530)
public static final int MATCH_EMPTY
Constant Value:
10000
(0x00002710)
public static final int MATCH_PATH
Constant Value:
40000
(0x00009c40)
public static final int MATCH_SCHEME
Constant Value:
20000
(0x00004e20)
public static final int MATCH_TYPE
Constant Value:
100000
(0x000186a0)
public static final int NO_MATCH_ACTION
Constant Value:
-3
(0xfffffffd)
public static final int NO_MATCH_CATEGORY
Constant Value:
-4
(0xfffffffc)
public static final int NO_MATCH_DATA
Constant Value:
-2
(0xfffffffe)
public static final int NO_MATCH_TYPE
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.
See Also
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.
See Also
Constant Value:
-1000
(0xfffffc18)
Public Constructors
public IntentFilter()
New empty IntentFilter.
public IntentFilter(String action)
New IntentFilter that matches a single action.
Parameters
| action | The action to match, i.e. Intent.MAIN_ACTION. |
|---|
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.VIEW_ACTION. |
|---|---|
| dataType | The type to match, i.e. "vnd.android.cursor.dir/person". |
public IntentFilter(IntentFilter o)
New IntentFilter containing a copy of an existing filter.
Parameters
| o | The original filter to copy. |
|---|
Public Methods
public final Iterator 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.VIEW_ACTION. |
|---|
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.EMBED_CATEGORY. |
|---|
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)
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.
Parameters
| path | Regexp of the path to match, i.e. "/picviewer?pic=.*". |
|---|
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:". |
|---|
See Also
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". |
|---|
See Also
public final Iterator authoritiesIterator()
Return an iterator over the filter's data authorities.
public final Iterator categoriesIterator()
Return an iterator over the filter's categories.
public static IntentFilter create(String action, String dataType)
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.VIEW_ACTION. |
|---|---|
| dataType | The type to match, i.e. "vnd.android.cursor.dir/person". |
Returns
- A new IntentFilter for the given action and type.
See Also
public final int getPriority()
Return the priority of this filter.
Returns
- The priority of the filter.
See Also
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
- 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 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. |
Returns
- How well the filter matches. 0 if it doesn't match, positive values if it does with a higher value representing a better match.
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. |
Returns
- How well the filter matches. Negative if it doesn't match, zero or positive positive value if it does with a higher value representing a better match.
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 succeed.
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 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. |
Returns
- MATCH_SCHEME if the data matches a scheme; MATCH_AUTHORITY if the data matches an authority; MATCH_PATH if the data matches a path; MATCH_TYPE if the data matches a type; MATCH_EMPTY if the filter does not specify a data match and the Intent does not include data; NO_MATCH_TYPE if the type didn't match; NO_MATCH_DATA if the scheme/path didn't match.
public final Iterator pathsIterator()
Return an iterator over the filter's data paths.
public final Iterator 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 typesIterator()
Return an iterator over the filter's data types.