Android
android.content
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, 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
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. 

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  Quality adjustment applied to the category of match that signifies the default, base value; higher numbers improve the quality while lower numbers reduce it.  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 
Constants inherited from interface android.os.Parcelable

Public Constructors

            IntentFilter()
New empty IntentFilter.
            IntentFilter(String action)
New IntentFilter that matches a single action with no data.
            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<String 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, int type)
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<IntentFilter.AuthorityEntry authoritiesIterator()
Return an iterator over the filter's data authorities.
    final      Iterator<String categoriesIterator()
Return an iterator over the filter's categories.
    final      int  countActions()
Return the number of actions in the filter.
    final      int  countCategories()
Return the number of categories in the filter.
    final      int  countDataAuthorities()
Return the number of data authorities in the filter.
    final      int  countDataPaths()
Return the number of data paths in the filter.
    final      int  countDataSchemes()
Return the number of data schemes in the filter.
    final      int  countDataTypes()
Return the number of data types in the filter.
      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.
    final      int  describeContents()
Describe the kinds of special objects contained in this Parcelable's marshalled representation.
          void  dump(Printer du, String prefix)
    final      String  getAction(int index)
Return an action in the filter.
    final      String  getCategory(int index)
Return a category in the filter.
    final      IntentFilter.AuthorityEntry  getDataAuthority(int index)
Return a data authority in the filter.
    final      PatternMatcher  getDataPath(int index)
Return a data path in the filter.
    final      String  getDataScheme(int index)
Return a data scheme in the filter.
    final      String  getDataType(int index)
Return a data type in the filter.
    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<String> 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<String> 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      int  matchDataAuthority(Uri data)
Match this intent filter against the given Intent data.
    final      Iterator<PatternMatcher pathsIterator()
Return an iterator over the filter's data paths.
          void  readFromXml(XmlPullParser parser)
    final      Iterator<String schemesIterator()
Return an iterator over the filter's data schemes.
    final      void  setPriority(int priority)
Modify priority of this filter.
    final      Iterator<String typesIterator()
Return an iterator over the filter's data types.
    final      void  writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel.
          void  writeToXml(XmlSerializer serializer)
Write the contents of the IntentFilter as an XML stream.
Methods inherited from class java.lang.Object
Methods inherited from interface android.os.Parcelable

Details

Constants

public static final Creator<IntentFilter> CREATOR

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

Quality adjustment applied to the category of match that signifies the default, base value; higher numbers improve the quality while lower numbers reduce it.
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

The part of a match constant that describes the category of match that occurred. May be either MATCH_CATEGORY_EMPTY, MATCH_CATEGORY_SCHEME, MATCH_CATEGORY_HOST, MATCH_CATEGORY_PORT, MATCH_CATEGORY_PATH, or MATCH_CATEGORY_TYPE. Higher values indicate a better match.
Constant Value: 268369920 (0x0fff0000)

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.

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 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".

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<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.

Parameters

path Either a raw string that must exactly match the file path, or a simple pattern, depending on type.
type Determines how path will be compared to determine a match: either PATTERN_LITERAL, PATTERN_PREFIX, or PATTERN_SIMPLE_GLOB.

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".

public final Iterator<IntentFilter.AuthorityEntry> authoritiesIterator()

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.

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.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.

Returns

  • a bitmask indicating the set of special object types marshalled by the Parcelable.

public void dump(Printer du, String prefix)

public final String getAction(int index)

Return an action in the filter.

public final String getCategory(int index)

Return a category in the filter.

public final IntentFilter.AuthorityEntry getDataAuthority(int index)

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.

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

  • 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.

Returns

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

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.

Returns

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.

public final Iterator<PatternMatcher> pathsIterator()

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.

Parameters

dest The Parcel in which the object should be written.
flags Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE.

public void writeToXml(XmlSerializer serializer)

Write the contents of the IntentFilter as an XML stream.

Throws

IOException
Copyright 2007 Google Inc. Build 119366-119366 - 19 Nov 2008 16:04