Home | History | Annotate | Download | only in manifest
      1 page.title=<data>
      2 parent.title=The AndroidManifest.xml File
      3 parent.link=manifest-intro.html
      4 @jd:body
      5 
      6 <dl class="xml">
      7 <dt>syntax:</dt>
      8 <dd><pre class="stx">&lt;data android:<a href="#host">host</a>="<i>string</i>"
      9       android:<a href="#mime">mimeType</a>="<i>string</i>"
     10       android:<a href="#path">path</a>="<i>string</i>"
     11       android:<a href="#path">pathPattern</a>="<i>string</i>"
     12       android:<a href="#path">pathPrefix</a>="<i>string</i>"
     13       android:<a href="#port">port</a>="<i>string</i>"
     14       android:<a href="#scheme">scheme</a>="<i>string</i>" /&gt;</pre></dd>
     15 
     16 
     17 <dt>contained in:</dt>
     18 <dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code></dd>
     19 
     20 <dt>description:</dt>
     21 <dd>Adds a data specification to an intent filter.  The specification can 
     22 be just a data type (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code> attribute), 
     23 just a URI, or both a data type and a URI.  A URI is specified by separate 
     24 attributes for each of its parts:
     25 
     26 <p style="margin-left: 2em">{@code scheme://host:port/path} <i>or</i> 
     27 {@code pathPrefix} <i>or</i> {@code pathPattern}</p>
     28 
     29 <p>
     30 These attributes are optional, but also mutually dependent: 
     31 If a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> is not specified for the 
     32 intent filter, all the other URI attributes are ignored.  If a 
     33 <code><a href="{@docRoot}guide/topics/manifest/data-element.html#host">host</a></code> is not specified for the filter, 
     34 the {@code port} attribute and all the path attributes are ignored.
     35 </p>
     36 
     37 <p>
     38 All the {@code &lt;data&gt;} elements contained within the same
     39 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element contribute to
     40 the same filter.  So, for example, the following filter specification,
     41 </p>
     42 
     43 <pre>&lt;intent-filter . . . &gt;
     44     &lt;data android:scheme="something" android:host="project.example.com" /&gt;
     45     . . .
     46 &lt;/intent-filter&gt;</pre>
     47 
     48 <p>is equivalent to this one:</p>
     49 
     50 <pre>&lt;intent-filter . . . &gt;
     51     &lt;data android:scheme="something" /&gt
     52     &lt;data android:host="project.example.com" /&gt;
     53     . . .
     54 &lt;/intent-filter&gt;</pre>
     55 
     56 <p>
     57 You can place any number of &lt;data&gt; elements inside an
     58 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> to give it multiple data 
     59 options.  None of its attributes have default values.  
     60 </p>
     61 
     62 <p>
     63 Information on how intent filters work, including the rules for how Intent objects
     64 are matched against filters, can be found in another document,
     65 <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
     66 Intent Filters</a>.  See also the 
     67 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intent Filters</a> 
     68 section in the introduction.
     69 </p></dd>
     70 
     71 <dt>attributes:</dt>
     72 <dd><dl class="attr">
     73 <dt><a name="host"></a>{@code android:host}</dt>
     74 <dd>The host part of a URI authority.  This attribute is meaningless
     75 unless a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> attribute is also 
     76 specified for the filter.
     77 
     78 <p class="note">Note: host name matching in the Android framework is
     79 case-sensitive, unlike the formal RFC.  As a result, you should always specify
     80 host names using lowercase letters.</p>
     81 </dd>
     82 
     83 <dt><a name="mime"></a>{@code android:mimeType}</dt>
     84 <dd>A MIME media type, such as {@code image/jpeg} or {@code audio/mpeg4-generic}.  
     85 The subtype can be the asterisk wildcard ({@code *}) to indicate that any 
     86 subtype matches.
     87 
     88 <p class="note">Note: MIME type matching in the Android framework is
     89 case-sensitive, unlike formal RFC MIME types.  As a result, you should always
     90 specify MIME types using lowercase letters.</p>
     91 </dd>
     92 
     93 <dt><a name="path"></a>{@code android:path}
     94 <br/>{@code android:pathPrefix}
     95 <br/>{@code android:pathPattern}</dt>
     96 <dd>The path part of a URI.  The {@code path} attribute specifies a complete 
     97 path that is matched against the complete path in an Intent object.  The 
     98 {@code pathPrefix} attribute specifies a partial path that is matched against 
     99 only the initial part of the path in the Intent object.  The {@code pathPattern} 
    100 attribute specifies a complete path that is matched against the complete path 
    101 in the Intent object, but it can contain the following wildcards: 
    102 
    103 <ul>
    104 <li>An asterisk ('{@code *}') matches a sequence of 0 to many occurrences of
    105 the immediately preceding character.</li>
    106 
    107 <li>A period followed by an asterisk ("{@code .*}") matches any sequence of 
    108 0 to many characters.</li>
    109 </ul>
    110 
    111 <p>
    112 Because '{@code \}' is used as an escape character when the string is read 
    113 from XML (before it is parsed as a pattern), you will need to double-escape:  
    114 For example, a literal '{@code *}' would be written as "{@code \\*}" and a 
    115 literal '{@code \}' would be written as "{@code \\\\}".  This is basically 
    116 the same as what you would need to write if constructing the string in Java code.
    117 </p>
    118 
    119 <p>
    120 For more information on these three types of patterns, see the descriptions of 
    121 {@link android.os.PatternMatcher#PATTERN_LITERAL},
    122 {@link android.os.PatternMatcher#PATTERN_PREFIX}, and
    123 {@link android.os.PatternMatcher#PATTERN_SIMPLE_GLOB} in the
    124 {@link android.os.PatternMatcher} class.
    125 </p>
    126 
    127 <p>These attributes are meaningful only if the 
    128 <code><a href="#scheme">scheme</a></code> and <code><a href="#host">host</a></code> 
    129 attributes are also specified for the filter.
    130 </p></dd>
    131 
    132 <dt><a name="port"></a>{@code android:port}</dt>
    133 <dd>The port part of a URI authority.  This attribute is meaningful only 
    134 if the <code><a href="#scheme">scheme</a></code> and 
    135 <code><a href="#host">host</a></code> attributes are also specified for 
    136 the filter.</dd>
    137 
    138 <dt><a name="scheme"></a>{@code android:scheme}</dt>
    139 <dd>The scheme part of a URI.  This is the minimal essential attribute for 
    140 specifying a URI; at least one {@code scheme} attribute must be set 
    141 for the filter, or none of the other URI attributes are meaningful.
    142 
    143 <p>
    144 A scheme is specified without the trailing colon (for example,
    145 {@code http}, rather than {@code http:}).
    146 </p>
    147 
    148 <p>
    149 If the filter has a data type set (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code> 
    150 attribute) but no scheme, the {@code content:} and {@code file:} schemes are
    151 assumed.
    152 </p>
    153 
    154 <p class="note">Note: scheme matching in the Android framework is
    155 case-sensitive, unlike the RFC.  As a result, you should always specify schemes
    156 using lowercase letters.</p>
    157 </dd>
    158 </dl></dd>  
    159 
    160 <!-- ##api level indication## -->
    161 <dt>introduced in:</dt>
    162 <dd>API Level 1</dd>
    163 
    164 <dt>see also:</dt>
    165 <dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code>
    166 <br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code></dd>
    167 
    168 </dl>
    169