tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
base/docs/html/guide/topics/manifest/action-element.jd Normal file
View File

@ -0,0 +1,50 @@
page.title=<action>
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;action android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code></dd>
<p>
<dt>description:</dt>
<dd>Adds an action to an intent filter.
An <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element must contain
one or more {@code &lt;action&gt;} elements. If it doesn't contain any, no
Intent objects will get through the filter. See
<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
Intent Filters</a> for details on intent filters and the role of action
specifications within a filter.
</dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the action. Some standard actions are defined in the
{@link android.content.Intent#ACTION_CHOOSER Intent} class as
{@code ACTION_<i>string</i>} constants. To assign one of these actions to
this attribute, prepend "{@code android.intent.action.}" to the
{@code <i>string</i>} that follows {@code ACTION_}.
For example, for {@code ACTION_MAIN}, use "{@code android.intent.action.MAIN}"
and for {@code ACTION_WEB_SEARCH}, use "{@code android.intent.action.WEB_SEARCH}".
<p>
For actions you define, it's best to use the package name as a prefix to
ensure uniqueness. For example, a {@code TRANSMOGRIFY} action might be specified
as follows:
</p>
<pre>&lt;action android:name="com.example.project.TRANSMOGRIFY" /&gt;</pre>
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code></dd>
</dl>

133
base/docs/html/guide/topics/manifest/activity-alias-element.jd Normal file
View File

@ -0,0 +1,133 @@
page.title=&lt;activity-alias&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;activity-alias android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#exported">exported</a>=["true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#trgt">targetActivity</a>="<i>string</i>" &gt;
. . .
&lt;/activity-alias&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>
<dt>description:</dt>
<dd>An alias for an activity, named by the {@code targetActivity}
attribute. The target must be in the same application as the
alias and it must be declared before the alias in the manifest.
<p>
The alias presents the target activity as a independent entity.
It can have its own set of intent filters, and they, rather than the
intent filters on the target activity itself, determine which intents
can activate the target through the alias and how the system
treats the alias. For example, the intent filters on the alias may
specify the "<code>{@link android.content.Intent#ACTION_MAIN
android.intent.action.MAIN}</code>"
and "<code>{@link android.content.Intent#CATEGORY_LAUNCHER
android.intent.category.LAUNCHER}</code>" flags, causing it to be
represented in the application launcher, even though none of the
filters on the target activity itself set these flags.
</p>
<p>
With the exception of {@code targetActivity}, {@code &lt;activity-alias&gt;}
attributes are a subset of <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> attributes.
For attributes in the subset, none of the values set for the target carry over
to the alias. However, for attributes not in the subset, the values set for
the target activity also apply to the alias.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the target activity can be instantiated by the system through
this alias &mdash; "{@code true}" if it can be, and "{@code false}" if not.
The default value is "{@code true}".
<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element has its own
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all
application components, including activity aliases. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> and {@code &lt;activity-alias&gt;}
attributes must both be "{@code true}" for the system to be able to instantiate
the target activity through the alias. If either is "{@code false}", the alias
does not work.
</p></dd>
<dt><a name="exported"></a>{@code android:exported}</dt>
<dd>Whether or not components of other applications can launch the target activity
through this alias &mdash; "{@code true}" if they can, and "{@code false}" if not.
If "{@code false}", the target activity can be launched through the alias only by
components of the same application as the alias or applications with the same user ID.
<p>
The default value depends on whether the alias contains intent filters. The
absence of any filters means that the activity can be invoked through the alias
only by specifying the exact name of the alias. This implies that the alias
is intended only for application-internal use (since others would not know its name)
&mdash; so the default value is "{@code false}".
On the other hand, the presence of at least one filter implies that the alias
is intended for external use &mdash; so the default value is "{@code true}".
</p></dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon for the target activity when presented to users through the alias.
See the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#icon">icon</a></code> attribute for more information.
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the alias when presented to users through the alias.
See the the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#label">label</a></code> attribute for more information.
</p></dd>
<dt><a name="nm">{@code android:name}</dt>
<dd>A unique name for the alias. The name should resemble a fully
qualified class name. But, unlike the name of the target activity,
the alias name is arbitrary; it does not refer to an actual class.
</p></dd>
<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that clients must have to launch the target activity
or get it to do something via the alias. If a caller of
<code>{@link android.content.Context#startActivity startActivity()}</code> or
<code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code>
has not been granted the specified permission, the target activity will not be
activated.
<p>This attribute supplants any permission set for the target activity itself. If
it is not set, a permission is not needed to activate the target through the alias.
</p>
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a>
section in the introduction.
</p></dd>
<dt><a name="trgt"></a>{@code android:targetActivity}</dt>
<dd>The name of the activity that can be activated through the alias.
This name must match the {@code name} attribute of an
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> element that precedes
the alias in the manifest.
</p></dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code></dd>
</dl>

780
base/docs/html/guide/topics/manifest/activity-element.jd Normal file
View File

@ -0,0 +1,780 @@
page.title=&lt;activity&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;activity android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"]
android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"]
android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"]
android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale",
"touchscreen", "keyboard", "keyboardHidden",
"navigation", "orientation", "screenLayout",
"fontScale", "uiMode"]
android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"]
android:<a href="#exported">exported</a>=["true" | "false"]
android:<a href="#finish">finishOnTaskLaunch</a>=["true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" |
"singleTask" | "singleInstance"]
android:<a href="#multi">multiprocess</a>=["true" | "false"]
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#nohist">noHistory</a>=["true" | "false"] <!-- ##api level 3## -->
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#proc">process</a>="<i>string</i>"
android:<a href="#screen">screenOrientation</a>=["unspecified" | "user" | "behind" |
"landscape" | "portrait" |
"sensor" | "nosensor"]
android:<a href="#state">stateNotNeeded</a>=["true" | "false"]
android:<a href="#aff">taskAffinity</a>="<i>string</i>"
android:<a href="#theme">theme</a>="<i>resource or theme</i>"
android:<a href="#wsoft">windowSoftInputMode</a>=["stateUnspecified",
"stateUnchanged", "stateHidden",
"stateAlwaysHidden", "stateVisible",
"stateAlwaysVisible", "adjustUnspecified",
"adjustResize", "adjustPan"] &gt; <!-- ##api level 3## -->
. . .
&lt;/activity&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares an activity (an {@link android.app.Activity} subclass) that
implements part of the application's visual user interface. All activities
must be represented by {@code &lt;activity&gt;}
elements in the manifest file. Any that are not declared there will not be seen
by the system and will never be run.
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a href name="reparent"></a>{@code android:allowTaskReparenting}</dt>
<dd>Whether or not the activity can move from the task that started it to
the task it has an affinity for when that task is next brought to the
front &mdash; "{@code true}" if it can move, and "{@code false}" if it
must remain with the task where it started.
<p>
If this attribute is not set, the value set by the corresponding
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#reparent">allowTaskReparenting</a></code>
attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element
applies to the activity. The default value is "{@code false}".
</p>
<p>
Normally when an activity is started, it's associated with the task of
the activity that started it and it stays there for its entire lifetime.
You can use this attribute to force it to be re-parented to the task it
has an affinity for when its current task is no longer displayed.
Typically, it's used to cause the activities of an application to move
to the main task associated with that application.
</p>
<p>
For example, if an e-mail message contains a link to a web page, clicking
the link brings up an activity that can display the page. That activity
is defined by the browser application, but is launched as part of the e-mail
task. If it's reparented to the browser task, it will be shown when the
browser next comes to the front, and will be absent when the e-mail task
again comes forward.
</p>
<p>
The affinity of an activity is defined by the
<code><a href="#aff">taskAffinity</a></code> attribute. The affinity
of a task is determined by reading the affinity of its root activity.
Therefore, by definition, a root activity is always in a task with the
same affinity. Since activities with "{@code singleTask}" or
"{@code singleInstance}" launch modes can only be at the root of a task,
re-parenting is limited to the "{@code standard}" and "{@code singleTop}"
modes. (See also the <code><a href="#lmode">launchMode</a></code>
attribute.)
</p></dd>
<dt><a name="always"></a>{@code android:alwaysRetainTaskState}</dt>
<dd>Whether or not the state of the task that the activity is in will always
be maintained by the system &mdash; "{@code true}" if it will be, and
"{@code false}" if the system is allowed to reset the task to its initial
state in certain situations. The default value is "{@code false}". This
attribute is meaningful only for the root activity of a task; it's ignored
for all other activities.
<p>
Normally, the system clears a task (removes all activities from the stack
above the root activity) in certain situations when the user re-selects that
task from the home screen. Typically, this is done if the user hasn't visited
the task for a certain amount of time, such as 30 minutes.
</p>
<p>
However, when this attribute is "{@code true}", users will always return
to the task in its last state, regardless of how they get there. This is
useful, for example, in an application like the web browser where there is
a lot of state (such as multiple open tabs) that users would not like to lose.
</p></dd>
<dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt>
<dd>Whether or not all activities will be removed from the task, except for
the root activity, whenever it is re-launched from the home screen &mdash;
"{@code true}" if the task is always stripped down to its root activity, and
"{@code false}" if not. The default value is "{@code false}". This attribute
is meaningful only for activities that start a new task (the root activity);
it's ignored for all other activities in the task.
<p>
When the value is "{@code true}", every time users start the task again, they
are brought to its root activity, regardless of what they were last doing in
the task and regardless of whether they used BACK or HOME to last leave it.
When the value is "{@code false}", the task may be cleared of activities in
some situations (see the
<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always.
</p>
<p>
Suppose, for example, that someone launches activity P from the home screen,
and from there goes to activity Q. The user next presses HOME, and then returns
to activity P. Normally, the user would see activity Q, since that is what they
were last doing in P's task. However, if P set this flag to "{@code true}", all
of the activities on top of it (Q in this case) were removed when the user pressed
HOME and the task went to the background. So the user sees only P when returning
to the task.
</p>
<p>
If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code>
are both "{@code true}", any activities that can be re-parented are moved to
the task they share an affinity with; the remaining activities are then dropped,
as described above.
</p></dd>
<dt><a name="config"></a>{@code android:configChanges}</dt>
<dd>Lists configuration changes that the activity will handle itself. When a configuration
change occurs at runtime, the activity is shut down and restarted by default, but declaring a
configuration with this attribute will prevent the activity from being restarted. Instead, the
activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged
onConfigurationChanged()}</code> method is called.
<p class="note"><strong>Note:</strong> Using this attribute should be
avoided and used only as a last-resort. Please read <a
href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a> for more
information about how to properly handle a restart due to a configuration change.</p>
<p>
Any or all of the following strings are valid values for this attribute. Multiple values are
separated by '{@code |}' &mdash; for example, "{@code locale|navigation|orientation}".
</p>
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code mcc}"</td>
<td>The IMSI mobile country code (MCC) has changed &mdash;
a SIM has been detected and updated the MCC.</td>
</tr><tr>
<td>"{@code mnc}"</td>
<td>The IMSI mobile network code (MNC) has changed &mdash;
a SIM has been detected and updated the MNC.</td>
</tr><tr>
<td>"{@code locale}"</td>
<td>The locale has changed &mdash; the user has selected a new
language that text should be displayed in.</td>
</tr><tr>
<td>"{@code touchscreen}"</td>
<td>The touchscreen has changed. (This should never normally happen.)</td>
</tr><tr>
<td>"{@code keyboard}"</td>
<td>The keyboard type has changed &mdash; for example, the user has
plugged in an external keyboard.</td>
</tr><tr>
<td>"{@code keyboardHidden}"</td>
<td>The keyboard accessibility has changed &mdash; for example, the
user has revealed the hardware keyboard.</td>
</tr><tr>
<td>"{@code navigation}"</td>
<td>The navigation type (trackball/dpad) has changed. (This should never normally happen.)</td>
</tr><tr>
<td>"{@code orientation}"</td>
<td>The screen orientation has changed &mdash; the user has rotated
the device.</td>
</tr><tr>
<td>"{@code screenLayout}"</td>
<td>The screen layout has changed &mdash; this might be caused by a
different display being activated.</td>
</tr><tr>
<td>"{@code fontScale}"</td>
<td>The font scaling factor has changed &mdash; the user has selected
a new global font size.</td>
</tr><tr>
<td>"{@code uiMode}"</td>
<td>The user interface mode has changed &mdash; this can be caused when the user places the
device into a desk/car dock or when the the night mode changes. See {@link
android.app.UiModeManager}. <em>Introduced in API Level 8</em>.</td>
</tr>
</table>
<p>
All of these configuration changes can impact the resource values seen by the
application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged
onConfigurationChanged()}</code> is called, it will generally be necessary to again
retrieve all resources (including view layouts, drawables, and so on) to correctly
handle the change.
</p></dd>
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the activity can be instantiated by the system &mdash;
"{@code true}" if it can be, and "{@code false}" if not. The default value
is "{@code true}".
<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element has its own
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code>
attribute that applies to all application components, including activities. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
and {@code &lt;activity&gt;} attributes must both be "{@code true}" (as they both
are by default) for the system to be able to instantiate the activity. If either
is "{@code false}", it cannot be instantiated.
</p></dd>
<dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt>
<dd>Whether or not the activity should be excluded from the list of recently
launched activities that can be displayed to users &mdash; "{@code true}" if
it should be excluded, and "{@code false}" if it should be included.
The default value is "{@code false}".
</p></dd>
<dt><a name="exported"></a>{@code android:exported}</dt>
<dd>Whether or not the activity can be launched by components of other
applications &mdash; "{@code true}" if it can be, and "{@code false}" if not.
If "{@code false}", the activity can be launched only by components of the
same application or applications with the same user ID.
<p>
The default value depends on whether the activity contains intent filters. The
absence of any filters means that the activity can be invoked only by specifying
its exact class name. This implies that the activity is intended only for
application-internal use (since others would not know the class name). So in
this case, the default value is "{@code false}".
On the other hand, the presence of at least one filter implies that the activity
is intended for external use, so the default value is "{@code true}".
</p>
<p>
This attribute is not the only way to limit an activity's exposure to other
applications. You can also use a permission to limit the external entities that
can invoke the activity (see the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code>
attribute).
</p></dd>
<dt><a name="finish"></a>{@code android:finishOnTaskLaunch}</dt>
<dd>Whether or not an existing instance of the activity should be shut down
(finished) whenever the user again launches its task (chooses the task on the
home screen) &mdash; "{@code true}" if it should be shut down, and "{@code false}"
if not. The default value is "{@code false}".
<p>
If this attribute and
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
are both "{@code true}", this attribute trumps the other. The affinity of the
activity is ignored. The activity is not re-parented, but destroyed.
</p>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon representing the activity. The icon is displayed to users when
a representation of the activity is required on-screen. For example, icons
for activities that initiate tasks are displayed in the launcher window.
The icon is often accompanied by a label (see the {@code label} attribute).
</p>
<p>
This attribute must be set as a reference to a drawable resource containing
the image definition. If it is not set, the icon specified for the application
as a whole is used instead (see the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).
</p>
<p>
The activity's icon &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element &mdash; is also the default icon for all the activity's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute).
</p></dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the activity. The label is displayed on-screen
when the activity must be represented to the user. It's often displayed along
with the activity icon.
<p>
If this attribute is not set, the label set for the application as a whole is
used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute).
</p>
<p>
The activity's label &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element &mdash; is also the
default label for all the activity's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute).
</p>
<p>
The label should be set as a reference to a string resource, so that
it can be localized like other strings in the user interface.
However, as a convenience while you're developing the application,
it can also be set as a raw string.
</p></dd>
<dt><a name="lmode"></a>{@code android:launchMode}</dt>
<dd>An instruction on how the activity should be launched. There are four modes
that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants)
in {@link android.content.Intent} objects to determine what should happen when
the activity is called upon to handle an intent. They are:</p>
<p style="margin-left: 2em">"{@code standard}"
<br>"{@code singleTop}"
<br>"{@code singleTask}"
<br>"{@code singleInstance}"</p>
<p>
The default mode is "{@code standard}".
</p>
<p>
As shown in the table below, the modes fall into two main groups, with
"{@code standard}" and "{@code singleTop}" activities on one side, and
"{@code singleTask}" and "{@code singleInstance}" activities on the other.
An activity with the "{@code standard}" or "{@code singleTop}" launch mode
can be instantiated multiple times. The instances can belong to any task
and can be located anywhere in the activity stack. Typically, they're
launched into the task that called
<code>{@link android.content.Context#startActivity startActivity()}</code>
(unless the Intent object contains a
<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code>
instruction, in which case a different task is chosen &mdash; see the
<a href="#aff">taskAffinity</a> attribute).
</p>
<p>
In contrast, "<code>singleTask</code>" and "<code>singleInstance</code>" activities
can only begin a task. They are always at the root of the activity stack.
Moreover, the device can hold only one instance of the activity at a time
&mdash; only one such task.
</p>
<p>
The "{@code standard}" and "{@code singleTop}" modes differ from each other
in just one respect: Every time there's a new intent for a "{@code standard}"
activity, a new instance of the class is created to respond to that intent.
Each instance handles a single intent.
Similarly, a new instance of a "{@code singleTop}" activity may also be
created to handle a new intent. However, if the target task already has an
existing instance of the activity at the top of its stack, that instance
will receive the new intent (in an
<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call);
a new instance is not created.
In other circumstances &mdash; for example, if an existing instance of the
"{@code singleTop}" activity is in the target task, but not at the top of
the stack, or if it's at the top of a stack, but not in the target task
&mdash; a new instance would be created and pushed on the stack.
</p>
<p>
The "{@code singleTask}" and "{@code singleInstance}" modes also differ from
each other in only one respect: A "{@code singleTask}" activity allows other
activities to be part of its task. It's always at the root of its task, but
other activities (necessarily "{@code standard}" and "{@code singleTop}"
activities) can be launched into that task. A "{@code singleInstance}"
activity, on the other hand, permits no other activities to be part of its task.
It's the only activity in the task. If it starts another activity, that
activity is assigned to a different task &mdash; as if {@code
FLAG_ACTIVITY_NEW_TASK} was in the intent.
</p>
<table>
<tr>
<th>Use Cases</th>
<th>Launch Mode</th>
<th>Multiple Instances?</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="2" style="width:20%;">Normal launches for most activities</td>
<td>"<code>standard</code>"</td>
<td>Yes</td>
<td>Default. The system always creates a new instance of the activity in the
target task and routes the intent to it.</td>
</tr>
<tr>
<td>"<code>singleTop</code>"</td>
<td>Conditionally</td>
<td>If an instance of the activity already exists at the top of the target task,
the system routes the intent to that instance through a call to its {@link
android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a
new instance of the activity.</td>
</tr>
<tr>
<td rowspan="2">Specialized launches<br>
<em>(not recommended for general use)</em></td>
<td>"<code>singleTask</code>"</td>
<td>No</td>
<td>The system creates the activity at the root of a new task and routes the
intent to it. However, if an instance of the activity already exists, the system
routes the intent to existing instance through a call to its {@link
android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a
new one.</td>
</tr>
<tr>
<td>"<code>singleInstance</code>"</td>
<td>No</td>
<td>Same as "<code>singleTask"</code>, except that the system doesn't launch any
other activities into the task holding the instance. The activity is always the
single and only member of its task.</td>
</tr>
</table>
<p>As shown in the table above, <code>standard</code> is the default mode and is
appropriate for most types of activities. <code>SingleTop</code> is also a
common and useful launch mode for many types of activities. The other modes
&mdash; <code>singleTask</code> and <code>singleInstance</code> &mdash; are
<span style="color:red">not appropriate for most applications</span>,
since they result in an interaction model that is likely to be unfamiliar to
users and is very different from most other applications.
<p>Regardless of the launch mode that you choose, make sure to test the usability
of the activity during launch and when navigating back to it from
other activities and tasks using the BACK key. </p>
<p>For more information on launch modes and their interaction with Intent
flags, see the
<a href="{@docRoot}guide/topics/fundamentals.html#acttask">Activities and
Tasks</a> section of the
<a href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals</a>
document.
</p>
</dd>
<dt><a name="multi"></a>{@code android:multiprocess}</dt>
<dd>Whether an instance of the activity can be launched into the process of the component
that started it &mdash; "{@code true}" if it can be, and "{@code false}" if not.
The default value is "{@code false}".
<p>
Normally, a new instance of an activity is launched into the process of the
application that defined it, so all instances of the activity run in the same
process. However, if this flag is set to "{@code true}", instances of the
activity can run in multiple processes, allowing the system to create instances
wherever they are used (provided permissions allow it), something that is almost
never necessary or desirable.
</p></dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the class that implements the activity, a subclass of
{@link android.app.Activity}. The attribute value should be a fully qualified
class name (such as, "{@code com.example.project.ExtracurricularActivity}").
However, as a shorthand, if the first character of the name is a period
(for example, "{@code .ExtracurricularActivity}"), it is appended to the
package name specified in the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element.
<p>
There is no default. The name must be specified.
</p></dd>
<!-- ##api level 3## -->
<dt><a name="nohist"></a>{@code android:noHistory}</dt>
<dd>Whether or not the activity should be removed from the activity stack and
finished (its <code>{@link android.app.Activity#finish finish()}</code>
method called) when the user navigates away from it and it's no longer
visible on screen &mdash; "{@code true}" if it should be finished, and
"{@code false}" if not. The default value is "{@code false}".
<p>
A value of "{@code true}" means that the activity will not leave a
historical trace. It will not remain in the activity stack for the task,
so the user will not be able to return to it.
</p>
<p>
This attribute was introduced in API Level 3.
</p>
<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that clients must have to launch the activity
or otherwise get it to respond to an intent. If a caller of
<code>{@link android.content.Context#startActivity startActivity()}</code> or
<code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code>
has not been granted the specified permission, its intent will not be
delivered to the activity.
<p>
If this attribute is not set, the permission set by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code>
attribute applies to the activity. If neither attribute is set, the activity is
not protected by a permission.
</p>
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
section in the introduction and another document,
<a href="{@docRoot}guide/topics/security/security.html">Security and
Permissions</a>.
</p></dd>
<dt><a name="proc"></a>{@code android:process}</dt>
<dd>The name of the process in which the activity should run. Normally,
all components of an application run in the default process created for the
application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code>
attribute can set a different default for all components. But each component
can override the default, allowing you to spread your application across
multiple processes.
<p>
If the name assigned to this attribute begins with a colon (':'), a new
process, private to the application, is created when it's needed and
the activity runs in that process.
If the process name begins with a lowercase character, the activity will run
in a global process of that name, provided that it has permission to do so.
This allows components in different applications to share a process, reducing
resource usage.
</p></dd>
<dt><a name="screen"></a>{@code android:screenOrientation}</dt>
<dd>The orientation of the activity's display on the device.
The value can be any one of the following strings:
<table>
<tr>
<td>"{@code unspecified}"</td>
<td>The default value. The system chooses the orientation. The policy it
uses, and therefore the choices made in specific contexts, may differ
from device to device.</td>
</tr><tr>
<td>"{@code landscape}"</td>
<td>Landscape orientation (the display is wider than it is tall).</td>
</tr><tr>
<td>"{@code portrait}"</td>
<td>Portrait orientation (the display is taller than it is wide).</td>
</tr><tr>
<td>"{@code user}"</td>
<td>The user's current preferred orientation.</td>
</tr><tr>
<td>"{@code behind}"</td>
<td>The same orientation as the activity that's immediately beneath it in
the activity stack.</td>
</tr><tr>
<td>"{@code sensor}"</td>
<td>The orientation determined by a physical orientation sensor. The
orientation of the display depends on how the user is holding the device;
it changes when the user rotates the device.</td>
</tr><tr>
<td>"{@code nosensor}"</td>
<td>An orientation determined without reference to a physical orientation sensor.
The sensor is ignored, so the display will not rotate based on how the user
moves the device. Except for this distinction, the system chooses the
orientation using the same policy as for the "{@code unspecified}" setting.</td>
</tr>
</table></dd>
<dt><a name="state"></a>{@code android:stateNotNeeded}</dt>
<dd>Whether or not the activity can be killed and successfully restarted
without having saved its state &mdash; "{@code true}" if it can be restarted
without reference to its previous state, and "{@code false}" if its previous
state is required. The default value is "{@code false}".
<p>
Normally, before an activity is temporarily shut down to save resources, its
<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code>
method is called. This method stores the current state of the activity in a
{@link android.os.Bundle} object, which is then passed to
<code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity
is restarted. If this attribute is set to "{@code true}",
{@code onSaveInstanceState()} may not be called and {@code onCreate()} will
be passed {@code null} instead of the Bundle &mdash; just as it was when the
activity started for the first time.
</p>
<p>
A "{@code true}" setting ensures that the activity can be restarted in the
absence of retained state. For example, the activity that displays the
home screen uses this setting to make sure that it does not get removed if it
crashes for some reason.
</p></dd>
<dt><a name="aff"></a>{@code android:taskAffinity}</dt>
<dd>The task that the activity has an affinity for. Activities with
the same affinity conceptually belong to the same task (to the same
"application" from the user's perspective). The affinity of a task
is determined by the affinity of its root activity.
<p>
The affinity determines two things &mdash; the task that the activity is re-parented
to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
attribute) and the task that will house the activity when it is launched
with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code>
flag.
</p>
<p>
By default, all activities in an application have the same affinity. You
can set this attribute to group them differently, and even place
activities defined in different applications within the same task. To
specify that the activity does not have an affinity for any task, set
it to an empty string.
<p>
If this attribute is not set, the activity inherits the affinity set
for the application (see the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code>
attribute). The name of the default affinity for an application is
the package name set by the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element.
</p>
<dt><a name="theme"></a>{@code android:theme}</dt>
<dd>A reference to a style resource defining an overall theme for the activity.
This automatically sets the activity's context to use this theme (see
<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also
cause "starting" animations prior to the activity being launched (to better
match what the activity actually looks like).
<p>
If this attribute is not set, the activity inherits the theme set for the
application as a whole &mdash; see the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code>
attribute. If that attribute is also not set, the default system theme is used.
</p>
<dd>
<!-- ##api level 3## -->
<dt><a name="wsoft"></a>{@code android:windowSoftInputMode}</dt>
<dd>How the main window of the activity interacts with the window containing
the on-screen soft keyboard. The setting for this attribute affects two
things:
<ul>
<li>The state of the soft keyboard &mdash; whether it is hidden or visible
&mdash; when the activity becomes the focus of user attention.</li>
<li>The adjustment made to the activity's main window &mdash; whether it is
resized smaller to make room for the soft keyboard or whether its contents
pan to make the current focus visible when part of the window is covered by
the soft keyboard.</li>
</ul>
<p>
The setting must be one of the values listed in the following table, or a
combination of one "{@code state...}" value plus one "{@code adjust...}"
value. Setting multiple values in either group &mdash; multiple
"{@code state...}" values, for example &mdash has undefined results.
Individual values are separated by a vertical bar ({@code |}). For example:
</p>
<pre>&lt;activity android:windowSoftInputMode="stateVisible|adjustResize" . . . &gt;</pre>
<p>
Values set here (other than "{@code stateUnspecified}" and
"{@code adjustUnspecified}") override values set in the theme.
</p>
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code stateUnspecified}"</td>
<td>The state of the soft keyboard (whether it is hidden or visible)
is not specified. The system will choose an appropriate state or
rely on the setting in the theme.
<p>
This is the default setting for the behavior of the soft keyboard.
</p></td>
</tr></tr>
<td>"{@code stateUnchanged}"</td>
<td>The soft keyboard is kept in whatever state it was last in,
whether visible or hidden, when the activity comes to the fore.</td>
</tr></tr>
<td>"{@code stateHidden}"</td>
<td>The soft keyboard is hidden when the user chooses the activity
&mdash; that is, when the user affirmatively navigates forward to the
activity, rather than backs into it because of leaving another activity.</td>
</tr></tr>
<td>"{@code stateAlwaysHidden}"</td>
<td>The soft keyboard is always hidden when the activity's main window
has input focus.</td>
</tr></tr>
<td>"{@code stateVisible}"</td>
<td>The soft keyboard is visible when that's normally appropriate
(when the user is navigating forward to the activity's main window).</td>
</tr></tr>
<td>"{@code stateAlwaysVisible}"</td>
<td>The soft keyboard is made visible when the user chooses the
activity &mdash; that is, when the user affirmatively navigates forward
to the activity, rather than backs into it because of leaving another
activity.</td>
</tr></tr>
<td>"{@code adjustUnspecified}"</td>
<td>It is unspecified whether the activity's main window resizes
to make room for the soft keyboard, or whether the contents
of the window pan to make the currentfocus visible on-screen.
The system will automatically select one of these modes depending
on whether the content of the window has any layout views that
can scroll their contents. If there is such a view, the window
will be resized, on the assumption that scrolling can make all
of the window's contents visible within a smaller area.
<p>
This is the default setting for the behavior of the main window.
</p></td>
</tr></tr>
<td>"{@code adjustResize}"</td>
<td>The activity's main window is always resized to make room for
the soft keyboard on screen.</td>
</tr></tr>
<td>"{@code adjustPan}"</td>
<td>The activity's main window is not resized to make room for the soft
keyboard. Rather, the contents of the window are automatically
panned so that the current focus is never obscured by the keyboard
and users can always see what they are typing. This is generally less
desirable than resizing, because the user may need to close the soft
keyboard to get at and interact with obscured parts of the window.</td>
</tr>
</table>
<p>
This attribute was introduced in API Level 3.
</p></dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1 for all attributes except for
<code><a href="#nohist">noHistory</a></code> and
<code><a href="#wsoft">windowSoftInputMode</a></code>, which were added in API
Level 3.</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code></dd>
</dl>

265
base/docs/html/guide/topics/manifest/application-element.jd Normal file
View File

@ -0,0 +1,265 @@
page.title=&lt;application&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;application android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"]
android:<a href="#agent">backupAgent</a>="<i>string</i>"
android:<a href="#debug">debuggable</a>=["true" | "false"]
android:<a href="#desc">description</a>="<i>string resource</i>"
android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#code">hasCode</a>=["true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#killrst">killAfterRestore</a>=["true" | "false"]
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#space">manageSpaceActivity</a>="<i>string</i>"
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#persistent">persistent</a>=["true" | "false"]
android:<a href="#proc">process</a>="<i>string</i>"
android:<a href="#restoreany">restoreAnyVersion</a>=["true" | "false"]
android:<a href="#aff">taskAffinity</a>="<i>string</i>"
android:<a href="#theme">theme</a>="<i>resource or theme</i>" &gt;
. . .
&lt;/application&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></code></dd>
<dt>description:</dt>
<dd>The declaration of the application. This element contains subelements
that declare each of the application's components and has attributes
that can affect all the components. Many of these attributes (such as
{@code icon}, {@code label}, {@code permission}, {@code process},
{@code taskAffinity}, and {@code allowTaskReparenting}) set default values
for corresponding attributes of the component elements. Others (such as
{@code debuggable}, {@code enabled}, {@code description}, and
{@code allowClearUserData}) set values for the application as a whole and
cannot be overridden by the components.</dd>
<dt>attributes</dt>
<dd><dl class="attr">
<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt>
<dd>Whether or not activities that the application defines can move from
the task that started them to the task they have an affinity for when that task
is next brought to the front &mdash; "{@code true}" if they can move, and
"{@code false}" if they must remain with the task where they started.
The default value is "{@code false}".
<p>
The
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element has its own
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
attribute that can override the value set here. See that attribute for more
information.
</p></dd>
<dt><a name="agent"></a>{@code android:backupAgent}</dt>
<dd>The name of the class that implement's the application's backup agent,
a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be
a fully qualified class name (such as, "{@code com.example.project.MyBackupAgent}").
However, as a shorthand, if the first character of the name is a period
(for example, "{@code .MyBackupAgent}"), it is appended to the
package name specified in the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element.
<p>
There is no default. The name must be specified.
</p></dd>
<dt><a name="debug"></a>{@code android:debuggable}</dt>
<dd>Whether or not the application can be debugged, even when running
on a device in user mode &mdash; "{@code true}" if it can be, and "{@code false}"
if not. The default value is "{@code false}".</dd>
<dt><a name="desc"></a>{@code android:description}</dt>
<dd>User-readable text about the application, longer and more descriptive than the application label. The value must be set as a reference to a string resource. Unlike the label, it cannot be a raw string. There is no default value.</dd>
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the Android system can instantiate components of
the application &mdash; "{@code true}" if it can, and "{@code false}"
if not. If the value is "{@code true}", each component's
{@code enabled} attribute determines whether that component is enabled
or not. If the value is "{@code false}", it overrides the
component-specific values; all components are disabled.
<p>
The default value is "{@code true}".
</p></dd>
<dt><a name="code"></a>{@code android:hasCode}</dt>
<dd>Whether or not the application contains any code &mdash; "{@code true}"
if it does, and "{@code false}" if not. When the value is "{@code false}",
the system does not try to load any application code when launching components.
The default value is "{@code true}".
<p>
An application would not have any code of its own only if it's using nothing
but built-in component classes, such as an activity that uses the {@link
android.app.AliasActivity} class, a rare occurrence.
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon for the application as whole, and the default icon for
each of the application's components. See the individual
{@code icon} attributes for
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>, and
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code> elements.
<p>
This attribute must be set as a reference to a drawable resource containing
the image definition. There is no default icon.
</p></dd>
<dt><a name="killrst"></a>{@code android:killAfterRestore}</dt>
<dd>Whether the application in question should be terminated after its
settings have been restored during a full-system restore operation.
Single-package restore operations will never cause the application to
be shut down. Full-system restore operations typically only occur once,
when the phone is first set up. Third-party applications will not normally
need to use this attribute.
<p>The default is {@code true}, which means that after the application
has finished processing its data during a full-system restore, it will be
terminated.
</p></dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the application as a whole, and a default
label for each of the application's components. See the individual
{@code label} attributes for
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>, and
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code> elements.
<p>
The label should be set as a reference to a string resource, so that
it can be localized like other strings in the user interface.
However, as a convenience while you're developing the application,
it can also be set as a raw string.
</p></dd>
<dt><a name="space"></a>{@code android:manageSpaceActivity}</dt>
<dd>The fully qualified name of an Activity subclass that the system
can launch to let users manage the memory occupied by the application
on the device. The activity should also be declared with an
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> element.
</dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The fully qualified name of an {@link android.app.Application}
subclass implemented for the application. When the application process
is started, this class is instantiated before any of the application's
components.
<p>
The subclass is optional; most applications won't need one.
In the absence of a subclass, Android uses an instance of the base
Application class.
</p></dd>
<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that clients must have in order to interact
with the application. This attribute is a convenient way to set a
permission that applies to all of the application's components. It can
be overwritten by setting the {@code permission} attributes of individual
components.
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
section in the introduction and another document,
<a href="{@docRoot}guide/topics/security/security.html">Security and
Permissions</a>.
</p></dd>
<dt><a name="persistent"></a>{@code android:persistent}</dt>
<dd>Whether or not the application should remain running at all times &mdash;
"{@code true}" if it should, and "{@code false}" if not. The default value
is "{@code false}". Applications should not normally set this flag;
persistence mode is intended only for certain system applications.</dd>
<dt><a name="proc"></a>{@code android:process}</dt>
<dd>The name of a process where all components of the application should run.
Each component can override this default by setting its own {@code process}
attribute.
<p>
By default, Android creates a process for an application when the first
of its components needs to run. All components then run in that process.
The name of the default process matches the package name set by the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.
</p>
<p>By setting this attribute to a process name that's shared with another
application, you can arrange for components of both applications to run in
the same process &mdash; but only if the two applications also share a
user ID and be signed with the same certificate.
</p>
<p>
If the name assigned to this attribute begins with a colon (':'), a new
process, private to the application, is created when it's needed.
If the process name begins with a lowercase character, a global process
of that name is created. A global process can be shared with other
applications, reducing resource usage.
</p></dd>
<dt><a href name="restoreany"></a>{@code android:restoreAnyVersion}</dt>
<dd>Indicate that the application is prepared to attempt a restore of any
backed-up data set, even if the backup was stored by a newer version
of the application than is currently installed on the device. Setting
this attribute to {@code true} will permit the Backup Manager to
attempt restore even when a version mismatch suggests that the data are
incompatible. <em>Use with caution!</em>
<p>The default value of this attribute is {@code false}.
</p></dd>
<dt><a href name="aff"></a>{@code android:taskAffinity}</dt>
<dd>An affinity name that applies to all activities within the application,
except for those that set a different affinity with their own
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code>
attributes. See that attribute for more information.
<p>
By default, all activities within an application share the same
affinity. The name of that affinity is the same as the package name
set by the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.
</p></dd>
<dt><a name="theme"></a>{@code android:theme}</dt>
<dd>A reference to a style resource defining a default theme for all
activities in the application. Individual activities can override
the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code>
attributes; see that attribute for more information.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code></dd>
</dl>

42
base/docs/html/guide/topics/manifest/category-element.jd Normal file
View File

@ -0,0 +1,42 @@
page.title=&lt;category&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;category android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code></dd>
<dt>description:</dt>
<dd>Adds a category name to an intent filter. See
<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
Intent Filters</a> for details on intent filters and the role of category
specifications within a filter.</dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the category. Standard categories are defined in the
{@link android.content.Intent} class as {@code CATEGORY_<i>name</i>}
constants. The name assigned here can be derived from those constants
by prefixing "{@code android.intent.category.}" to the
{@code <i>name</i>} that follows {@code CATEGORY_}. For example,
the string value for {@code CATEGORY_LAUNCHER} is
"{@code android.intent.category.LAUNCHER}".
<p>
Custom categories should use the package name as a prefix, to ensure
that they are unique.
</p></dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data&gt;</a></code></dd>
</dl>

166
base/docs/html/guide/topics/manifest/data-element.jd Normal file
View File

@ -0,0 +1,166 @@
page.title=&lt;data&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;data android:<a href="#host">host</a>="<i>string</i>"
android:<a href="#mime">mimeType</a>="<i>string</i>"
android:<a href="#path">path</a>="<i>string</i>"
android:<a href="#path">pathPattern</a>="<i>string</i>"
android:<a href="#path">pathPrefix</a>="<i>string</i>"
android:<a href="#port">port</a>="<i>string</i>"
android:<a href="#scheme">scheme</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code></dd>
<dt>description:</dt>
<dd>Adds a data specification to an intent filter. The specification can
be just a data type (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code> attribute),
just a URI, or both a data type and a URI. A URI is specified by separate
attributes for each of its parts:
<p style="margin-left: 2em">{@code scheme://host:port/path} <i>or</i>
{@code pathPrefix} <i>or</i> {@code pathPattern}</p>
<p>
These attributes are optional, but also mutually dependent:
If a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> is not specified for the
intent filter, all the other URI attributes are ignored. If a
<code><a href="{@docRoot}guide/topics/manifest/data-element.html#host">host</a></code> is not specified for the filter,
the {@code port} attribute and all the path attributes are ignored.
</p>
<p>
All the {@code &lt;data&gt;} elements contained within the same
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element contribute to
the same filter. So, for example, the following filter specification,
</p>
<pre>&lt;intent-filter . . . &gt;
&lt;data android:scheme="something" android:host="project.example.com" /&gt;
. . .
&lt;/intent-filter&gt;</pre>
<p>is equivalent to this one:</p>
<pre>&lt;intent-filter . . . &gt;
&lt;data android:scheme="something" /&gt
&lt;data android:host="project.example.com" /&gt;
. . .
&lt;/intent-filter&gt;</pre>
<p>
You can place any number of &lt;data&gt; elements inside an
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> to give it multiple data
options. None of its attributes have default values.
</p>
<p>
Information on how intent filters work, including the rules for how Intent objects
are matched against filters, can be found in another document,
<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and
Intent Filters</a>. See also the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intent Filters</a>
section in the introduction.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="host"></a>{@code android:host}</dt>
<dd>The host part of a URI authority. This attribute is meaningless
unless a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> attribute is also
specified for the filter.
<p class="note">Note: host name matching in the Android framework is
case-sensitive, unlike the formal RFC. As a result, you should always specify
host names using lowercase letters.</p>
</dd>
<dt><a name="mime"></a>{@code android:mimeType}</dt>
<dd>A MIME media type, such as {@code image/jpeg} or {@code audio/mpeg4-generic}.
The subtype can be the asterisk wildcard ({@code *}) to indicate that any
subtype matches.
<p class="note">Note: MIME type matching in the Android framework is
case-sensitive, unlike formal RFC MIME types. As a result, you should always
specify MIME types using lowercase letters.</p>
</dd>
<dt><a name="path"></a>{@code android:path}
<br/>{@code android:pathPrefix}
<br/>{@code android:pathPattern}</dt>
<dd>The path part of a URI. The {@code path} attribute specifies a complete
path that is matched against the complete path in an Intent object. The
{@code pathPrefix} attribute specifies a partial path that is matched against
only the initial part of the path in the Intent object. The {@code pathPattern}
attribute specifies a complete path that is matched against the complete path
in the Intent object, but it can contain the following wildcards:
<ul>
<li>An asterisk ('{@code *}') matches a sequence of 0 to many occurrences of
the immediately preceding character.</li>
<li>A period followed by an asterisk ("{@code .*}") matches any sequence of
0 to many characters.</li>
</ul>
<p>
Because '{@code \}' is used as an escape character when the string is read
from XML (before it is parsed as a pattern), you will need to double-escape:
For example, a literal '{@code *}' would be written as "{@code \\*}" and a
literal '{@code \}' would be written as "{@code \\\\}". This is basically
the same as what you would need to write if constructing the string in Java code.
</p>
<p>
For more information on these three types of patterns, see the descriptions of
{@link android.os.PatternMatcher#PATTERN_LITERAL},
{@link android.os.PatternMatcher#PATTERN_PREFIX}, and
{@link android.os.PatternMatcher#PATTERN_SIMPLE_GLOB} in the
{@link android.os.PatternMatcher} class.
</p>
<p>These attributes are meaningful only if the
<code><a href="#scheme">scheme</a></code> and <code><a href="#host">host</a></code>
attributes are also specified for the filter.
</p></dd>
<dt><a name="port"></a>{@code android:port}</dt>
<dd>The port part of a URI authority. This attribute is meaningful only
if the <code><a href="#scheme">scheme</a></code> and
<code><a href="#host">host</a></code> attributes are also specified for
the filter.</dd>
<dt><a name="scheme"></a>{@code android:scheme}</dt>
<dd>The scheme part of a URI. This is the minimal essential attribute for
specifying a URI; at least one {@code scheme} attribute must be set
for the filter, or none of the other URI attributes are meaningful.
<p>
A scheme is specified without the trailing colon (for example,
{@code http}, rather than {@code http:}).
</p>
<p>
If the filter has a data type set (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code>
attribute) but no scheme, the {@code content:} and {@code file:} schemes are
assumed.
</p>
<p class="note">Note: scheme matching in the Android framework is
case-sensitive, unlike the RFC. As a result, you should always specify schemes
using lowercase letters.</p>
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code></dd>
</dl>

89
base/docs/html/guide/topics/manifest/grant-uri-permission-element.jd Normal file
View File

@ -0,0 +1,89 @@
page.title=&lt;grant-uri-permission&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;grant-uri-permission android:<a href="#path">path</a>="<i>string</i>"
android:<a href="#path">pathPattern</a>="<i>string</i>"
android:<a href="#path">pathPrefix</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code></dd>
<dt>description:</dt>
<dd>Specifies which data subsets of the parent content provider permission
can be granted for. Data subsets are indicated by the path part of a
{@code content:} URI. (The authority part of the URI identifies the
content provider.)
Granting permission is a way of enabling clients of the provider that don't
normally have permission to access its data to overcome that restriction on
a one-time basis.
<p>
If a content provider's <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code>
attribute is "{@code true}", permission can be granted for any the data under
the provider's purview. However, if that attribute is "{@code false}", permission
can be granted only to data subsets that are specified by this element.
A provider can contain any number of {@code &lt;grant-uri-permission&gt;} elements.
Each one can specify only one path (only one of the three possible attributes).
</p>
<p>
For information on how permission is granted, see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">grantUriPermissions</a></code> attribute.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="path"></a>{@code android:path}
<br/>{@code android:pathPrefix}
<br/>{@code android:pathPattern}</dt>
<dd>A path identifying the data subset or subsets that permission can be
granted for. The {@code path} attribute specifies a complete path;
permission can be granted only to the particular data subset identified
by that path.
The {@code pathPrefix} attribute specifies the initial part of a path;
permission can be granted to all data subsets with paths that share that
initial part.
The {@code pathPattern} attribute specifies a complete path, but one
that can contain the following wildcards:
<ul>
<li>An asterisk ('{@code *}') matches a sequence of 0 to many occurrences of
the immediately preceding character.</li>
<li><p>A period followed by an asterisk ("{@code .*}") matches any sequence of
0 to many characters.</p></li>
</ul>
<p>
Because '{@code \}' is used as an escape character when the string is read
from XML (before it is parsed as a pattern), you will need to double-escape:
For example, a literal '{@code *}' would be written as "{@code \\*}" and a
literal '{@code \}' would be written as "{@code \\\\}". This is basically
the same as what you would need to write if constructing the string in Java code.
</p>
<p>
For more information on these types of patterns, see the descriptions of
{@link android.os.PatternMatcher#PATTERN_LITERAL},
{@link android.os.PatternMatcher#PATTERN_PREFIX}, and
{@link android.os.PatternMatcher#PATTERN_SIMPLE_GLOB} in the
{@link android.os.PatternMatcher} class.
</p></dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd>the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code>
attribute of the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>
element</dd>
</dl>

65
base/docs/html/guide/topics/manifest/instrumentation-element.jd Normal file
View File

@ -0,0 +1,65 @@
page.title=&lt;instrumentation&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;instrumentation android:<a href="#ftest">functionalTest</a>=["true" | "false"]
android:<a href="#hprof">handleProfiling</a>=["true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#trgt">targetPackage</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares an {@link android.app.Instrumentation} class that enables you
to monitor an application's interaction with the system. The Instrumentation
object is instantiated before any of the application's components.</dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="ftest"></a>{@code android:functionalTest}</dt>
<dd>Whether or not the Instrumentation class should run as a functional test
&mdash; "{@code true}" if it should, and "{@code false}" if not. The
default value is "{@code false}".</dd>
<dt><a name="hprof"></a>{@code android:handleProfiling}</dt>
<dd>Whether or not the Instrumentation object will turn profiling on and
off &mdash; "{@code true}" if it determines when profiling starts and
stops, and "{@code false}" if profiling continues the entire time it is
running. A value of "{@code true}" enables the object to target profiling
at a specific set of operations. The default value is "{@code false}".</dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon that represents the Instrumentation class. This attribute must
be set as a reference to a drawable resource.</dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the Instrumentation class. The label can
be set as a raw string or a reference to a string resource.</dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the {@link android.app.Instrumentation} subclass.
This should be a fully qualified class name (such as,
"{@code com.example.project.StringInstrumentation}"). However, as a shorthand,
if the first character of the name is a period, it is appended to the package
name specified in the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.
<p>
There is no default. The name must be specified.
</p></dd>
<dt><a name="trgt"></a>{@code android:targetPackage}</dt>
<dd>The application that the Instrumentation object will run against.
An application is identified by the package name assigned in its manifest
file by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
</dl>

134
base/docs/html/guide/topics/manifest/intent-filter-element.jd Normal file
View File

@ -0,0 +1,134 @@
page.title=&lt;intent-filter&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;intent-filter android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#priority">priority</a>="<i>integer</i>" &gt;
. . .
&lt;/intent-filter&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code></dd>
<dt>must contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data&gt;</a></code></dd>
<dt>description:</dt>
<dd>Specifies the types of intents that an activity, service, or broadcast
receiver can respond to. An intent filter declares the capabilities of its
parent component &mdash; what an activity or service can do and what types
of broadcasts a receiver can handle. It opens the component to receiving
intents of the advertised type, while filtering out those that are not
meaningful for the component.
<p>
Most of the contents of the filter are described by its
<code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code>, and
<code><a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data&gt;</a></code> subelements.
</p>
<p>
For a more detailed discussion of filters, see the separate
<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents
and Intent Filters</a> document, as well as the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intents Filters</a>
section in the introduction.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon that represents the parent activity, service, or broadcast
receiver when that component is presented to the user as having the
capability described by the filter.
<p>
This attribute must be set as a reference to a drawable resource
containing the image definition. The default value is the icon set
by the parent component's {@code icon} attribute. If the parent
does not specify an icon, the default is the icon set by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element.
</p>
<p>
For more on intent filter icons, see
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#iconlabel">Icons and Labels</a>
in the introduction.
</p></dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the parent component. This label, rather than
the one set by the parent component, is used when the component is presented
to the user as having the capability described by the filter.
<p>
The label should be set as a reference to a string resource, so that
it can be localized like other strings in the user interface.
However, as a convenience while you're developing the application,
it can also be set as a raw string.
</p>
<p>
The default value is the label set by the parent component. If the
parent does not specify a label, the default is the label set by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label"> label</a></code> attribute.
</p>
<p>
For more on intent filter labels, see
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#iconlabel">Icons and Labels</a>
in the introduction.
</p></dd>
<dt><a name="priority"></a>{@code android:priority}</dt>
<dd>The priority that should be given to the parent component with regard
to handling intents of the type described by the filter. This attribute has
meaning for both activities and broadcast receivers:
<ul>
<li>It provides information about how able an activity is to respond to
an intent that matches the filter, relative to other activities that could
also respond to the intent. When an intent could be handled by multiple
activities with different priorities, Android will consider only those with
higher priority values as potential targets for the intent.</li>
<li><p>It controls the order in which broadcast receivers are executed to
receive broadcast messages. Those with higher priority
values are called before those with lower values. (The order applies only
to synchronous messages; it's ignored for asynchronous messages.)</p></li>
</ul>
<p>
Use this attribute only if you really need to impose a specific order in
which the broadcasts are received, or want to force Android to prefer
one activity over others.
</p>
<p>
The value must be an integer, such as "{@code 100}". Higher numbers have a
higher priority.
</p></dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data&gt;</a></code></dd>
</dl>

182
base/docs/html/guide/topics/manifest/manifest-element.jd Normal file
View File

@ -0,0 +1,182 @@
page.title=&lt;manifest&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;manifest xmlns:<a href="#nspace">android</a>="http://schemas.android.com/apk/res/android"
<a href="#package">package</a>="<i>string</i>"
android:<a href="#uid">sharedUserId</a>="<i>string</i>"
android:<a href="#uidlabel">sharedUserLabel</a>="<i>string resource</i>" <!-- ##api level 3## -->
android:<a href="#vcode">versionCode</a>="<i>integer</i>"
android:<a href="#vname">versionName</a>="<i>string</i>"
android:<a href="#install">installLocation</a>=["auto" | "internalOnly" | "preferExternal"] &gt;
. . .
&lt;/manifest&gt;</pre></dd>
<p>
<dt>contained in:</dt>
<dd><i>none</i></dd>
<p>
<p>
<dt>must contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">&lt;instrumentation&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></code> <!-- ##api level 3## -->
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code></dd>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></code></dd>
<p>
<dt>description:</dt>
<dd>The root element of the AndroidManifest.xml file. It must
contain an <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element
and specify {@code xlmns:android} and {@code package} attributes.</dd>
<dt>attributes:</dt>
<dd>
<dl class="attr">
<dt><a name="nspace"></a>{@code xmlns:android}</dt>
<dd>Defines the Android namespace. This attribute should always be set
to "{@code http://schemas.android.com/apk/res/android}".</dd>
<dt><a name="package"></a>{@code package}</dt>
<dd>A full Java package name for the application. The name should
be unique. The name may contain uppercase or lowercase letters ('A'
through 'Z'), numbers, and underscores ('_'). However, individual
package name parts may only start with letters. For example, applications
published by Google could have names in the form
<code>com.google.app.<i>application_name</i></code>.
<p>
The package name serves as a unique identifier for the application.
It's also the default name for the application process (see the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">process</a></code>
process</a></code> attribute) and the default task affinity of an activity
(see the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attribute).
</p>
</dd>
<dt><a name="uid"></a>{@code android:sharedUserId}</dt>
<dd>The name of a Linux user ID that will be shared with other applications.
By default, Android assigns each application its own unique user ID.
However, if this attribute is set to the same value for two or more applications,
they will all share the same ID &mdash; provided that they are also signed
by the same certificate. Application with the same user ID can access each
other's data and, if desired, run in the same process.</dd>
<dt><a name="uidlabel"></a>{@code android:sharedUserLabel}</dt>
<dd>A user-readable label for the shared user ID. The label must be set as
a reference to a string resource; it cannot be a raw string.
<p>
<!-- ##api level indication## -->
This attribute was introduced in API Level 3. It is meaningful only if the
<code><a href="#uid">sharedUserId</a></code> attribute is also set.
</p>
</dd>
<dt><a name="vcode"></a>{@code android:versionCode}</dt>
<dd>An internal version number. This number is used only to determine whether
one version is more recent than another, with higher numbers indicating more
recent versions. This is not the version number shown to users; that number
is set by the {@code versionName} attribute.
<p>
The value must be set as an integer, such as "100". You can define it however
you want, as long as each successive version has a higher number. For example,
it could be a build number. Or you could translate a version number in "x.y"
format to an integer by encoding the "x" and "y" separately in the lower and
upper 16 bits. Or you could simply increase the number by one each time a new
version is released.
</p>
</dd>
<dt><a name="vname"></a>{@code android:versionName}</dt>
<dd>The version number shown to users. This attribute can be set as a raw
string or as a reference to a string resource. The string has no other purpose
than to be displayed to users. The {@code versionCode} attribute holds
the significant version number used internally.
</dd>
<dt><a name="install"></a>{@code android:installLocation}</dt>
<dd>The default install location for the application.
<p>The following keyword strings are accepted:</p>
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code internalOnly}"</td>
<td>The application must be installed on the internal device storage only. If this is set,
the application will never be installed on the external storage. If the internal
storage is full, then the system will not install the application. This is also the default behavior
if you do not define {@code android:installLocation}.</td>
</tr><tr>
<td>"{@code auto}"</td>
<td>The application may be installed on the external storage, but the system will install the
application on the internal storage by default. If the internal storage is full, then the system
will install it on the external storage. Once installed, the user can move the application
to either internal or external storage through the system settings.</td>
</tr><tr>
<td>"{@code preferExternal}"</td>
<td>The application prefers to be installed on the external storage (SD card). There is no
guarantee that the system will honor this request. The application might be installed on internal
storage if the external media is unavailable or full, or if the application uses the forward-locking
mechanism (not supported on external storage). Once installed, the user can move the application to
either internal or external storage through the system settings.</td>
</tr>
</table>
<p class="note"><strong>Note:</strong> By default, your application will be installed on the
internal storage and cannot be installed on the external storage unless you define this attribute
to be either "{@code auto}" or "{@code preferExternal}".</p>
<p>When an application is installed on the external storage:</p>
<ul>
<li>The {@code .apk} file is saved
to the external storage, but any application data (such as databases) is still saved on
the internal device memory.</li>
<li>The container in which the {@code .apk} file is saved is encrypted with a key that allows
the application to operate only on the device that installed it. (A user cannot
transfer the SD card to another device and use applications installed on the card.) Though,
multiple SD cards can be used with the same device.</li>
<li>At the user's request, the application can be moved to the internal storage.</li>
</ul>
<p>The user may also request to move an application from the internal storage to the external
storage. However, the system will not allow the user to move the application to external storage if
this attribute is set to {@code internalOnly}, which is the default setting.</p>
<p>Read <a href="{@docRoot}guide/appendix/install-location.html">App Install Location</a> for
more information about using this attribute (including how to maintain backward compatibility).</p>
<p>Introduced in: API Level 8.</p>
</dd>
</dl>
</dd><!-- end attributes -->
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1 for all attributes, unless noted otherwise in the attribute description.</dd>
<p>
<dt>see also:</dt>
<dd>
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
</dl>

514
base/docs/html/guide/topics/manifest/manifest-intro.jd Normal file
View File

@ -0,0 +1,514 @@
page.title=The AndroidManifest.xml File
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#filestruct">Structure of the Manifest File</a></li>
<li><a href="#filec">File Conventions</a>
<li><a href="#filef">File Features</a>
<ol>
<li><a href="#ifs">Intent Filters</a></li>
<li><a href="#iconlabel">Icons and Labels</a></li>
<li><a href="#perms">Permissions</a></li>
<li><a href="#libs">Libraries</a></li>
</ol></li>
</ol>
</div>
</div>
<p>
Every application must have an AndroidManifest.xml file (with precisely that
name) in its root directory. The manifest presents essential information about
the application to the Android system, information the system must have before
it can run any of the application's code. Among other things, the manifest
does the following:
</p>
<ul>
<li>It names the Java package for the application.
The package name serves as a unique identifier for the application.</li>
<li>It describes the components of the application &mdash; the activities,
services, broadcast receivers, and content providers that the application is
composed of. It names the classes that implement each of the components and
publishes their capabilities (for example, which {@link android.content.Intent
Intent} messages they can handle). These declarations let the Android system
know what the components are and under what conditions they can be launched.</li>
<li>It determines which processes will host application components.</li>
<li>It declares which permissions the application must have in order to
access protected parts of the API and interact with other applications.</li>
<li>It also declares the permissions that others are required to have in
order to interact with the application's components.</li>
<li>It lists the {@link android.app.Instrumentation} classes that provide
profiling and other information as the application is running. These declarations
are present in the manifest only while the application is being developed and
tested; they're removed before the application is published.</li>
<li>It declares the minimum level of the Android API that the application
requires.</li>
<li>It lists the libraries that the application must be linked against.</li>
</ul>
<h2 id="filestruct">Structure of the Manifest File</h2>
<p>
The diagram below shows the general structure of the manifest file and
every element that it can contain. Each element, along with all of its
attributes, is documented in full in a separate file. To view detailed
information about any element, click on the element name in the diagram,
in the alphabetical list of elements that follows the diagram, or on any
other mention of the element name.
</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
<a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">&lt;instrumentation /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration /&gt;</a> <!-- ##api level 3## -->
<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature /&gt;</a> <!-- ##api level 4## -->
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens /&gt;</a> <!-- ##api level 4## -->
<a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;/activity&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;/activity-alias&gt;</a>
<a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data/&gt;</a>
<a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;/service&gt;</a>
<a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;/receiver&gt;</a>
<a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a>
<a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;/provider&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;/application&gt;</a>
<a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;/manifest&gt;</a>
</pre>
<p>
All the elements that can appear in the manifest file are listed below
in alphabetical order. These are the only legal elements; you cannot
add your own elements or attributes.
</p>
<p style="margin-left: 2em">
<code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">&lt;instrumentation&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code> <!-- ##api level 4## -->
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></code> <!-- ##api level 3## -->
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></code> <!-- ##api level 4## -->
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></code>
</p>
<h2 id="filec">File Conventions</h2>
<p>
Some conventions and rules apply generally to all elements and attributes
in the manifest:
</p>
<dl>
<dt><b>Elements</b></dt>
<dd>Only the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> and
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
elements are required, they each must be present and can occur only once.
Most of the others can occur many times or not at all &mdash; although at
least some of them must be present for the manifest to accomplish anything
meaningful.
<p>
If an element contains anything at all, it contains other elements.
All values are set through attributes, not as character data within an element.
</p>
<p>
Elements at the same level are generally not ordered. For example,
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>, and
<code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
elements can be intermixed in any sequence. (An
<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>
element is the exception to this rule: It must follow the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
it is an alias for.)
</p></dd>
<dt><b>Attributes</b></dt>
<dd>In a formal sense, all attributes are optional. However, there are some
that must be specified for an element to accomplish its purpose. Use the
documentation as a guide. For truly optional attributes, it mentions a default
value or states what happens in the absence of a specification.
<p>Except for some attributes of the root
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element, all attribute names begin with an {@code android:} prefix &mdash;
for example, {@code android:alwaysRetainTaskState}. Because the prefix is
universal, the documentation generally omits it when referring to attributes
by name.</p></dd>
<dt><b>Declaring class names</b></dt>
<dd>Many elements correspond to Java objects, including elements for the
application itself (the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element) and its principal components &mdash; activities
(<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>),
services
(<code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>),
broadcast receivers
(<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>),
and content providers
(<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>).
<p>
If you define a subclass, as you almost always would for the component classes
({@link android.app.Activity}, {@link android.app.Service},
{@link android.content.BroadcastReceiver}, and {@link android.content.ContentProvider}),
the subclass is declared through a {@code name} attribute. The name must include
the full package designation.
For example, an {@link android.app.Service} subclass might be declared as follows:
</p>
<pre>&lt;manifest . . . &gt;
&lt;application . . . &gt;
&lt;service android:name="com.example.project.SecretService" . . . &gt;
. . .
&lt;/service&gt;
. . .
&lt;/application&gt;
&lt;/manifest&gt;</pre>
<p>
However, as a shorthand, if the first character of the string is a period, the
string is appended to the application's package name (as specified by the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code>
attribute). The following assignment is the same as the one above:
</p>
<pre>&lt;manifest package="com.example.project" . . . &gt;
&lt;application . . . &gt;
&lt;service android:name=".SecretService" . . . &gt;
. . .
&lt;/service&gt;
. . .
&lt;/application&gt;
&lt;/manifest&gt;</pre>
<p>
When starting a component, Android creates an instance of the named subclass.
If a subclass isn't specified, it creates an instance of the base class.
</p></dd>
<dt><b>Multiple values</b></dt>
<dd>If more than one value can be specified, the element is almost always
repeated, rather than listing multiple values within a single element.
For example, an intent filter can list several actions:
<pre>&lt;intent-filter . . . &gt;
&lt;action android:name="android.intent.action.EDIT" /&gt;
&lt;action android:name="android.intent.action.INSERT" /&gt;
&lt;action android:name="android.intent.action.DELETE" /&gt;
. . .
&lt;/intent-filter&gt;</pre></dd>
<dt><b>Resource values</b></dt>
<dd>Some attributes have values that can be displayed to users &mdash; for
example, a label and an icon for an activity. The values of these attributes
should be localized and therefore set from a resource or theme. Resource
values are expressed in the following format,</p>
<p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>:<i>name</i>}</p>
<p>
where the <i>package</i> name can be omitted if the resource is in the same package
as the application, <i>type</i> is a type of resource &mdash; such as "string" or
"drawable" &mdash; and <i>name</i> is the name that identifies the specific resource.
For example:
</p>
<pre>&lt;activity android:icon="@drawable/smallPic" . . . &gt</pre>
<p>
Values from a theme are expressed in a similar manner, but with an initial '{@code ?}'
rather than '{@code @}':
</p>
<p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>:<i>name</i>}
</p></dd>
<dt><b>String values</b></dt>
<dd>Where an attribute value is a string, double backslashes ('{@code \\}')
must be used to escape characters &mdash; for example, '{@code \\n}' for
a newline or '{@code \\uxxxx}' for a Unicode character.</dd>
</dl>
<h2 id="filef">File Features</h2>
<p>
The following sections describe how some Android features are reflected
in the manifest file.
</p>
<h3 id="ifs">Intent Filters</h3>
<p>
The core components of an application (its activities, services, and broadcast
receivers) are activated by <i>intents</i>. An intent is a
bundle of information (an {@link android.content.Intent} object) describing a
desired action &mdash; including the data to be acted upon, the category of
component that should perform the action, and other pertinent instructions.
Android locates an appropriate component to respond to the intent, launches
a new instance of the component if one is needed, and passes it the
Intent object.
</p>
<p>
Components advertise their capabilities &mdash; the kinds of intents they can
respond to &mdash; through <i>intent filters</i>. Since the Android system
must learn which intents a component can handle before it launches the component,
intent filters are specified in the manifest as
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
elements. A component may have any number of filters, each one describing
a different capability.
</p>
<p>
An intent that explicitly names a target component will activate that component;
the filter doesn't play a role. But an intent that doesn't specify a target by
name can activate a component only if it can pass through one of the component's
filters.
</p>
<p>
For information on how Intent objects are tested against intent filters,
see a separate document,
<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents
and Intent Filters</a>.
</p>
<h3 id="iconlabel">Icons and Labels</h3>
<p>
A number of elements have {@code icon} and {@code label} attributes for a
small icon and a text label that can be displayed to users. Some also have a
{@code description} attribute for longer explanatory text that can also be
shown on-screen. For example, the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element has all three of these attributes, so that when the user is asked whether
to grant the permission to an application that has requested it, an icon representing
the permission, the name of the permission, and a description of what it
entails can all be presented to the user.
</p>
<p>
In every case, the icon and label set in a containing element become the default
{@code icon} and {@code label} settings for all of the container's subelements.
Thus, the icon and label set in the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element are the default icon and label for each of the application's components.
Similarly, the icon and label set for a component &mdash; for example, an
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element &mdash; are the default settings for each of the component's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
elements. If an
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element sets a label, but an activity and its intent filter do not,
the application label is treated as the label for both the activity and
the intent filter.
</p>
<p>
The icon and label set for an intent filter are used to represent a component
whenever the component is presented to the user as fulfilling the function
advertised by the filter. For example, a filter with
"{@code android.intent.action.MAIN}" and
"{@code android.intent.category.LAUNCHER}" settings advertises an activity
as one that initiates an application &mdash; that is, as
one that should be displayed in the application launcher. The icon and label
set in the filter are therefore the ones displayed in the launcher.
</p>
<h3 id="perms">Permissions</h3>
<p>
A <i>permission</i> is a restriction limiting access to a part of the code
or to data on the device. The limitation is imposed to protect critical
data and code that could be misused to distort or damage the user experience.
</p>
<p>
Each permission is identified by a unique label. Often the label indicates
the action that's restricted. For example, here are some permissions defined
by Android:
</p>
<p style="margin-left: 2em">{@code android.permission.CALL_EMERGENCY_NUMBERS}
<br/>{@code android.permission.READ_OWNER_DATA}
<br/>{@code android.permission.SET_WALLPAPER}
<br/>{@code android.permission.DEVICE_POWER}</p>
<p>
A feature can be protected by at most one permission.
</p>
<p>
If an application needs access to a feature protected by a permission,
it must declare that it requires that permission with a
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
element in the manifest. Then, when the application is installed on
the device, the installer determines whether or not to grant the requested
permission by checking the authorities that signed the application's
certificates and, in some cases, asking the user.
If the permission is granted, the application is able to use the protected
features. If not, its attempts to access those features will simply fail
without any notification to the user.
</p>
<p>
An application can also protect its own components (activities, services,
broadcast receivers, and content providers) with permissions. It can employ
any of the permissions defined by Android (listed in
{@link android.Manifest.permission android.Manifest.permission}) or declared
by other applications. Or it can define its own. A new permission is declared
with the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element. For example, an activity could be protected as follows:
</p>
<pre>
&lt;manifest . . . &gt;
&lt;permission android:name="com.example.project.DEBIT_ACCT" . . . /&gt;
&lt;uses-permission android:name="com.example.project.DEBIT_ACCT" /&gt;
. . .
&lt;application . . .&gt;
&lt;activity android:name="com.example.project.FreneticActivity"
android:permission="com.example.project.DEBIT_ACCT"
. . . &gt;
. . .
&lt;/activity&gt;
&lt;/application&gt;
&lt;/manifest&gt;
</pre>
<p>
Note that, in this example, the {@code DEBIT_ACCT} permission is not only
declared with the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element, its use is also requested with the
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
element. Its use must be requested in order for other components of the
application to launch the protected activity, even though the protection
is imposed by the application itself.
</p>
<p>
If, in the same example, the {@code permission} attribute was set to a
permission declared elsewhere
(such as {@code android.permission.CALL_EMERGENCY_NUMBERS}, it would not
have been necessary to declare it again with a
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element. However, it would still have been necessary to request its use with
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>.
</p>
<p>
The
<code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
element declares a namespace for a group of permissions that will be defined in
code. And
<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
defines a label for a set of permissions (both those declared in the manifest with
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
elements and those declared elsewhere). It affects only how the permissions are
grouped when presented to the user. The
<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
element does not specify which permissions belong to the group;
it just gives the group a name. A permission is placed in the group
by assigning the group name to the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code>
attribute.
</p>
<h3 id="libs">Libraries</h3>
<p>
Every application is linked against the default Android library, which
includes the basic packages for building applications (with common classes
such as Activity, Service, Intent, View, Button, Application, ContentProvider,
and so on).
</p>
<p>
However, some packages reside in their own libraries. If your application
uses code from any of these packages, it must explicitly asked to be linked
against them. The manifest must contain a separate
<code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></code>
element to name each of the libraries. (The library name can be found in the
documentation for the package.)
</p>

94
base/docs/html/guide/topics/manifest/meta-data-element.jd Normal file
View File

@ -0,0 +1,94 @@
page.title=&lt;meta-data&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;meta-data android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#rsrc">resource</a>="<i>resource specification</i>"
android:<a href="#val">value</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code></dd>
<dt>description:</dt>
<dd>A name-value pair for an item of additional, arbitrary data that can
be supplied to the parent component. A component element can contain any
number of {@code &lt;meta-data&gt;} subelements. The values from all of
them are collected in a single {@link android.os.Bundle} object and made
available to the component as the
{@link android.content.pm.PackageItemInfo#metaData
PackageItemInfo.metaData} field.
<p>
Ordinary values are specified through the <code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#value">value</a></code>
attribute. However, to assign a resource ID as the value, use the
<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#resource">resource</a></code> attribute instead. For example,
the following code assigns whatever value is stored in the {@code @string/kangaroo}
resource to the "{@code zoo}" name:
</p>
<pre>&lt;meta-data android:name="zoo" android:value="@string/kangaroo" /&gt;</pre>
<p>
On the other hand, using the {@code resource} attribute would assign "{@code zoo}"
the numeric ID of the resource, not the value stored in the resource:
</p>
<pre>&lt;meta-data android:name="zoo" android:resource="@string/kangaroo" /&gt;</pre>
<p>
It is highly recommended that you avoid supplying related data as
multiple separate {@code &lt;meta-data&gt;} entries. Instead, if you
have complex data to associate with a component, store it as a resource and
use the {@code resource} attribute to inform the component of its ID.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>A unique name for the item. To ensure that the name is unique, use a
Java-style naming convention &mdash; for example,
"{@code com.example.project.activity.fred}".</dd>
<dt><a name="rsrc"></a>{@code android:resource}</dt>
<dd>A reference to a resource. The ID of the resource is the value assigned
to the item. The ID can be retrieved from the meta-data Bundle by the
{@link android.os.Bundle#getInt Bundle.getInt()} method.</dd>
<dt><a name="val"></a>{@code android:value}</dt>
<dd>The value assigned to the item. The data types that can be assigned as values and the Bundle methods that components use to retrieve those values are listed in the following table:
<table>
<tr>
<th>Type</th>
<th>Bundle method</th>
</tr><tr>
<td>String value, using double backslashes ({@code \\}) to escape characters
&mdash; such as "{@code \\n}" and "{@code \\uxxxxx}" for a Unicode character.</td>
<td>{@link android.os.Bundle#getString(String) getString()}</td>
</tr><tr>
<td>Integer value, such as "{@code 100}"</td>
<td>{@link android.os.Bundle#getInt(String) getInt()}</td>
</tr><tr>
<td>Boolean value, either "{@code true}" or "{@code false}"</td>
<td>{@link android.os.Bundle#getBoolean(String) getBoolean()}</td>
</tr><tr>
<td>Color value, in the form "{@code #rgb}", "{@code #argb}",
"{@code #rrggbb}", or "{@code #aarrggbb}"</td>
<td>{@link android.os.Bundle#getString(String) getString()}</td>
</tr><tr>
<td>Float value, such as "{@code 1.23}"</td>
<td>{@link android.os.Bundle#getFloat(String) getFloat()}</td>
</tr>
</table>
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
</dl>

104
base/docs/html/guide/topics/manifest/path-permission-element.jd Normal file
View File

@ -0,0 +1,104 @@
page.title=&lt;path-permission&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">
&lt;path-permission android:<a href="#path">path</a>="<i>string</i>"
android:<a href="#pathPrefix">pathPrefix</a>="<i>string</i>"
android:<a href="#pathPattern">pathPattern</a>="<i>string</i>"
android:<a href="#permission">permission</a>="<i>string</i>"
android:<a href="#readPermission">readPermission</a>="<i>string</i>"
android:<a href="#writePermission">writePermission</a>="<i>string</i>" /&gt;
</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code></dd>
<!--
<dt>can contain:</dt>
</dd>
-->
<dt>description:</dt>
<dd>Defines the path and required permissions for a specific subset of data
within a content provider. This element can be
specified multiple times to supply multiple paths.
</dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="path"></a>{@code android:path}</dt>
<dd>A complete URI path for a subset of content provider data.
Permission can be granted only to the particular data identified by this path.
When used to provide search suggestion content, it must be appended
with "/search_suggest_query".
</dd>
<dt><a name="pathPrefix"></a>{@code android:pathPrefix}</dt>
<dd>The initial part of a URI path for a subset of content provider data.
Permission can be granted to all data subsets with paths that share this initial part.
</dd>
<dt><a name="pathPattern"></a>{@code android:pathPattern}</dt>
<dd>A complete URI path for a subset of content provider data,
but one that can use the following wildcards:
<ul>
<li>An asterisk ('<code class="Code prettyprint">*</code>'). This matches a sequence of 0 to many occurrences of
the immediately preceding character.</li>
<li>A period followed by an asterisk ("<code class="Code prettyprint">.*</code>"). This matches any sequence of
0 or more characters.</li>
</ul>
<p>
Because '<code class="Code prettyprint">\</code>' is used as an escape character when the string is read
from XML (before it is parsed as a pattern), you will need to double-escape.
For example, a literal '<code class="Code prettyprint">*</code>' would be written as "<code class="Code prettyprint">\\*</code>" and a
literal '<code class="Code prettyprint">\</code>' would be written as "<code class="Code prettyprint">\\</code>". This is basically
the same as what you would need to write if constructing the string in Java code.
</p>
<p>
For more information on these types of patterns, see the descriptions of
<a href="/reference/android/os/PatternMatcher.html#PATTERN_LITERAL">PATTERN_LITERAL</a>,
<a href="/reference/android/os/PatternMatcher.html#PATTERN_PREFIX">PATTERN_PREFIX</a>, and
<a href="/reference/android/os/PatternMatcher.html#PATTERN_SIMPLE_GLOB">PATTERN_SIMPLE_GLOB</a> in the
<a href="/reference/android/os/PatternMatcher.html">PatternMatcher</a> class.
</p>
</dd>
<dt><a name="permission"></a>{@code android:permission}</dt>
<dd>The name of a permission that clients must have in order to read or write the
content provider's data. This attribute is a convenient way of setting a
single permission for both reading and writing. However, the
<code>readPermission</code> and
<code>writePermission</code> attributes take precedence
over this one.
</dd>
<dt><a name="readPermission"></a>{@code android:readPermission}</dt>
<dd>A permission that clients must have in order to query the content provider.
</dd>
<dt><a name="writePermission"></a>{@code android:writePermission}</dt>
<dd>A permission that clients must have in order to make changes to the data controlled by the content provider.
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 4</dd>
<dt>see also:</dt>
<dd>{@link android.app.SearchManager}</dd>
<dd>{@link android.Manifest.permission}</dd>
<dd><a href="/guide/topics/security/security.html">Security and
Permissions</a></dd>
</dl>

135
base/docs/html/guide/topics/manifest/permission-element.jd Normal file
View File

@ -0,0 +1,135 @@
page.title=&lt;permission&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt></dt>
<dd><pre class="stx">&lt;permission android:<a href="#desc">description</a>="<i>string resource</i>"
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#pgroup">permissionGroup</a>="<i>string</i>"
android:<a href="#plevel">protectionLevel</a>=["normal" | "dangerous" |
"signature" | "signatureOrSystem"] /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares a security permission that can be used to limit access
to specific components or features of this or other applications.
See the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a>
section in the introduction,
and the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>
document for more information on how permissions work.</dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="desc"></a>{@code android:description}</dt>
<dd>A user-readable description of the permission, longer and more
informative than the label. It may be displayed to explain the
permission to the user &mdash; for example, when the user is asked
whether to grant the permission to another application.
<p>
This attribute must be set as a reference to a string resource;
unlike the {@code label} attribute, it cannot be a raw string.
</p></dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>A reference to a drawable resource for an icon that represents the
permission.</dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A name for the permission, one that can be displayed to users.
<p>
As a convenience, the label can be directly set
as a raw string while you're developing the application. However,
when the application is ready to be published, it should be set as a
reference to a string resource, so that it can be localized like other
strings in the user interface.
</p></dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the permission. This is the name that will be used in
code to refer to the permission &mdash; for example, in a
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code> element and the
{@code permission} attributes of application components.
<p>
The name must be unique, so it should use Java-style scoping &mdash;
for example, "{@code com.example.project.PERMITTED_ACTION}".
</p></dd>
<dt><a name="pgroup"></a>{@code android:permissionGroup}</dt>
<dd>Assigns this permission to a group. The value of this attribute is
the name of the group, which must be declared with the
<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code> element in this
or another application. If this attribute is not set, the permission
does not belong to a group.</dd>
<dt><a name="plevel"></a>{@code android:protectionLevel}</dt>
<dd>Characterizes the potential risk implied in the permission and
indicates the procedure the system should follow when determining
whether or not to grant the permission to an application requesting it.
The value can be set to one of the following strings:
<table>
<tr>
<th>Value</th>
<th>Meaning</th>
</tr><tr>
<td>"{@code normal}"</td>
<td>The default value. A lower-risk permission that gives requesting
applications access to isolated application-level features, with
minimal risk to other applications, the system, or the user.
The system automatically grants this type
of permission to a requesting application at installation, without
asking for the user's explicit approval (though the user always
has the option to review these permissions before installing).
</tr><tr>
<td>"{@code dangerous}"</td>
<td>A higher-risk permission that would give a requesting application
access to private user data or control over the device that can
negatively impact the user. Because this type of permission
introduces potential risk, the system may not automatically
grant it to the requesting application. For example, any dangerous
permissions requested by an application may be displayed to the
user and require confirmation before proceeding, or some other
approach may be taken to avoid the user automatically allowing
the use of such facilities.
</tr><tr>
<td>"{@code signature}"</td>
<td>A permission that the system grants only if the requesting
application is signed with the same certificate as the application
that declared the permission. If the certificates match, the system
automatically grants the permission without notifying the user or
asking for the user's explicit approval.
</tr><tr>
<td>"{@code signatureOrSystem}"</td>
<td>A permission that the system grants only to applications that are
in the Android system image <em>or</em> that are signed with the same
certificates as those in the system image. Please avoid using this
option, as the {@code signature} protection level should be sufficient
for most needs and works regardless of exactly where applications are
installed. The "{@code signatureOrSystem}"
permission is used for certain special situations where multiple
vendors have applications built into a system image and need
to share specific features explicitly because they are being built
together.
</tr>
</table>
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code></dd>
</dd>
</dl>

63
base/docs/html/guide/topics/manifest/permission-group-element.jd Normal file
View File

@ -0,0 +1,63 @@
page.title=&lt;permission-group&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;permission-group android:<a href="#desc">description</a>="<i>string resource</i>"
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares a name for a logical grouping of related permissions. Individual
permission join the group through the {@code permissionGroup} attribute of the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code> element. Members of a group are
presented together in the user interface.
<p>
Note that this element does not declare a permission itself, only a category in
which permissions can be placed. See the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code> element for element for information
on declaring permissions and assigning them to groups.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="desc"></a>{@code android:description}</dt>
<dd>User-readable text that describes the group. The text should be
longer and more explanatory than the label. This attribute must be
set as a reference to a string resource. Unlike the {@code label}
attribute, it cannot be a raw string.</dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon representing the permission. This attribute must be set
as a reference to a drawable resource containing the image definition.</dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable name for the group. As a convenience, the label can
be directly set as a raw string while you're developing the application.
However, when the application is ready to be published, it should be set
as a reference to a string resource, so that it can be localized like other
strings in the user interface.</dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the group. This is the name that can be assigned to a
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">&lt;permissionGroup&gt;</a></code>
attribute.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code></dd>
</dl>

64
base/docs/html/guide/topics/manifest/permission-tree-element.jd Normal file
View File

@ -0,0 +1,64 @@
page.title=&lt;permission-tree&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;permission-tree android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>" ]
android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares the base name for a tree of permissions. The application takes
ownership of all names within the tree. It can dynamically add new permissions
to the tree by calling <code>{@link android.content.pm.PackageManager#addPermission PackageManager.addPermission()}</code>. Names within the tree are separated by
periods ('{@code .}'). For example, if the base name is
{@code com.example.project.taxes}, permissions like the following might be
added:
<p style="margin-left: 2em">{@code com.example.project.taxes.CALCULATE}
<br/>{@code com.example.project.taxes.deductions.MAKE_SOME_UP}
<br/>{@code com.example.project.taxes.deductions.EXAGGERATE}</p>
<p>
Note that this element does not declare a permission itself, only a
namespace in which further permissions can be placed. See the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element for information on declaring permissions.
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon representing all the permissions in the tree. This attribute
must be set as a reference to a drawable resource containing the image
definition.</dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable name for the group. As a convenience, the label can
be directly set as a raw string for quick and dirty programming. However,
when the application is ready to be published, it should be set as a
reference to a string resource, so that it can be localized like other
strings in the user interface.</dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name that's at the base of the permission tree. It serves as
a prefix to all permission names in the tree. Java-style scoping should
be used to ensure that the name is unique. The name must have more than
two period-separated segments in its path &mdash; for example,
{@code com.example.base} is OK, but {@code com.example} is not.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
</dd>
</dl>

270
base/docs/html/guide/topics/manifest/provider-element.jd Normal file
View File

@ -0,0 +1,270 @@
page.title=&lt;provider&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;provider android:<a href="#auth">authorities</a>="<i>list</i>"
android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#exported">exported</a>=["true" | "false"]
android:<a href="#gprmsn">grantUriPermissions</a>=["true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#init">initOrder</a>="<i>integer</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#multi">multiprocess</a>=["true" | "false"]
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#proc">process</a>="<i>string</i>"
android:<a href="#rprmsn">readPermission</a>="<i>string</i>"
android:<a href="#sync">syncable</a>=["true" | "false"]
android:<a href="#wprmsn">writePermission</a>="<i>string</i>" &gt;
. . .
&lt;/provider&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares a content provider &mdash; a subclass of
{@link android.content.ContentProvider} &mdash; that supplies structured
access to data managed by the application. All content providers that
are part of the application must be represented by {@code &lt;provider&gt;}
elements in the manifest file. The system cannot see, and therefore will
not run, any that are not declared. (You need to declare only
those content providers that you develop as part of your application,
not those developed by others that your application uses.)
<p>
The Android system identifies content providers by the authority part
of a {@code content:} URI. For example, suppose that the following URI
is passed to <code>{@link android.content.ContentResolver#query
ContentResolver.query()}</code>:
<p style="margin-left: 2em">{@code content://com.example.project.healthcareprovider/nurses/rn}</p>
<p>
The {@code content:} scheme identifies the data as belonging to a content
provider and the authority ({@code com.example.project.healthcareprovider})
identifies the particular provider. The authority therefore must be unique.
Typically, as in this example, it's the fully qualified name of a
ContentProvider subclass. The path part of a URI may be used by a content
provider to identify particular data subsets, but those paths are not
declared in the manifest.
</p>
<p>
For information on using and developing content providers, see a separate document,
<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="auth"></a>{@code android:authorities}</dt>
<dd>A list of one or more URI authorities that identify data under the purview
of the content provider.
Multiple authorities are listed by separating their names with a semicolon.
To avoid conflicts, authority names should use a Java-style naming convention
(such as {@code com.example.provider.cartoonprovider}). Typically, it's the name
of the ContentProvider subclass.
<p>
There is no default. At least one authority must be specified.
</p></dd>
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the content provider can be instantiated by the system &mdash;
"{@code true}" if it can be, and "{@code false}" if not. The default value
is "{@code true}".
<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element has its own
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all
application components, including content providers. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> and {@code &lt;provider&gt;}
attributes must both be "{@code true}" (as they both
are by default) for the content provider to be enabled. If either is
"{@code false}", the provider is disabled; it cannot be instantiated.
</p></dd>
<dt><a name="exported"></a>{@code android:exported}</dt>
<dd>Whether or not the content provider can be used by components of other
applications &mdash; "{@code true}" if it can be, and "{@code false}" if not.
If "{@code false}", the provider is available only to components of the
same application or applications with the same user ID. The default value
is "{@code true}".
<p>
You can export a content provider but still limit access to it with the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attribute.
</p></dd>
<dt><a name="gprmsn"></a>{@code android:grantUriPermissions}</dt>
<dd>Whether or not those who ordinarily would not have permission to
access the content provider's data can be granted permission to do so,
temporarily overcoming the restriction imposed by the
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attributes
&mdash;
"{@code true}" if permission can be granted, and "{@code false}" if not.
If "{@code true}", permission can be granted to any of the content
provider's data. If "{@code false}", permission can be granted only
to the data subsets listed in
<code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></code> subelements,
if any. The default value is "{@code false}".
<p>
Granting permission is a way of giving an application component one-time
access to data protected by a permission. For example, when an e-mail
message contains an attachment, the mail application may call upon the
appropriate viewer to open it, even though the viewer doesn't have general
permission to look at all the content provider's data.
</p>
<p>
In such cases, permission is granted by
<code>{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}</code>
and <code>{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}</code>
flags in the Intent object that activates the component. For example, the
mail application might put {@code FLAG_GRANT_READ_URI_PERMISSION} in the
Intent passed to {@code Context.startActivity()}. The permission is specific
to the URI in the Intent.
</p>
<p>
If you enable this feature, either by setting this attribute to "{@code true}"
or by defining <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></code>
subelements, you must call
<code>{@link android.content.Context#revokeUriPermission
Context.revokeUriPermission()}</code> when a covered URI is deleted from
the provider.
</p>
<p>
See also the <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></code>
element.
</p></dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon representing the content provider.
This attribute must be set as a reference to a drawable resource containing
the image definition. If it is not set, the icon specified for the application
as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).</dd>
<dt><a name="init"></a>{@code android:initOrder}</dt>
<dd>The order in which the content provider should be instantiated,
relative to other content providers hosted by the same process.
When there are dependencies among content providers, setting this
attribute for each of them ensures that they are created in the order
required by those dependencies. The value is a simple integer,
with higher numbers being initialized first.</dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the content provided.
If this attribute is not set, the label set for the application as a whole is
used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute).
<p>
The label should be set as a reference to a string resource, so that
it can be localized like other strings in the user interface.
However, as a convenience while you're developing the application,
it can also be set as a raw string.
</p></dd>
<dt><a name="multi"></a>{@code android:multiprocess}</dt>
<dd>Whether or not an instance of the content provider can be created in
every client process &mdash; "{@code true}" if instances can run in multiple
processes, and "{@code false}" if not. The default value is "{@code false}".
<p>
Normally, a content provider is instantiated in the process of the
application that defined it. However, if this flag is set to "{@code true}",
the system can create an instance in every process where there's a client
that wants to interact with it, thus avoiding the overhead of interprocess
communication.
</p></dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the class that implements the content provider, a subclass of
{@link android.content.ContentProvider}. This should be a fully qualified
class name (such as, "{@code com.example.project.TransportationProvider}").
However, as a shorthand, if the first character of the name is a period,
it is appended to the package name specified in the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.
<p>
There is no default. The name must be specified.
</p></dd>
<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that clients must have to read or write the
content provider's data. This attribute is a convenient way of setting a
single permission for both reading and writing. However, the
<code><a href="#rprmsn">readPermission</a></code> and
<code><a href="#wprmsn">writePermission</a></code> attributes take precedence
over this one. If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code>
attribute is also set, it controls access for querying the content provider.
And if the <code><a href="#wprmsn">writePermission</a></code> attribute is set,
it controls access for modifying the provider's data.
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
section in the introduction and a separate document,
<a href="{@docRoot}guide/topics/security/security.html">Security and
Permissions</a>.
</p></dd>
<dt><a name="proc"></a>{@code android:process}</dt>
<dd>The name of the process in which the content provider should run. Normally,
all components of an application run in the default process created for the
application. It has the same name as the application package. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code>
attribute can set a different
default for all components. But each component can override the default
with its own {@code process} attribute, allowing you to spread your
application across multiple processes.
<p>
If the name assigned to this attribute begins with a colon (':'), a new
process, private to the application, is created when it's needed and
the activity runs in that process.
If the process name begins with a lowercase character, the activity will run
in a global process of that name, provided that it has permission to do so.
This allows components in different applications to share a process, reducing
resource usage.
</p></dd>
<dt><a name="rprmsn"></a>{@code android:readPermission}</dt>
<dd>A permission that clients must have to query the content provider.
See also the <code><a href="#prmsn">permission</a></code> and
<code><a href="#wprmsn">writePermission</a></code> attributes.</dd>
<dt><a name="sync"></a>{@code android:syncable}</dt>
<dd>Whether or not the data under the content provider's control
is to be synchronized with data on a server &mdash; "{@code true}"
if it is to be synchronized, and "{@ code false}" if not.</dd>
<dt><a name="wprmsn"></a>{@code android:writePermission}</dt>
<dd>A permission that clients must have to make changes to the data
controlled by the content provider.
See also the <code><a href="#prmsn">permission</a></code> and
<code><a href="#rprmsn">readPermission</a></code> attributes.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd><a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a></dd>
</dl>

168
base/docs/html/guide/topics/manifest/receiver-element.jd Normal file
View File

@ -0,0 +1,168 @@
page.title=&lt;receiver&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;receiver android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#exported">exported</a>=["true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#proc">process</a>="<i>string</i>" &gt;
. . .
&lt;/receiver&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares a broadcast receiver (a {@link android.content.BroadcastReceiver}
subclass) as one of the application's components. Broadcast receivers enable
applications to receive intents that are broadcast by the system or by other
applications, even when other components of the application are not running.
<p>
There are two ways to make a broadcast receiver known to the system: One is
declare it in the manifest file with this element. The other is to create
the receiver dynamically in code and register it with the <code>{@link
android.content.Context#registerReceiver Context.registerReceiver()}</code>
method. See the {@link android.content.BroadcastReceiver} class description
for more on dynamically created receivers.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the broadcast receiver can be instantiated by the system &mdash;
"{@code true}" if it can be, and "{@code false}" if not. The default value
is "{@code true}".
<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element has its own
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all
application components, including broadcast receivers. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> and
{@code &lt;receiver&gt;} attributes must both be "{@code true}" for
the broadcast receiver to be enabled. If either is "{@code false}", it is
disabled; it cannot be instantiated.
</p></dd>
<dt><a name="exported"></a>{@code android:exported}</dt>
<dd>Whether or not the broadcast receiver can receive messages from sources
outside its application &mdash; "{@code true}" if it can, and "{@code false}"
if not. If "{@code false}", the only messages the broadcast receiver can
receive are those sent by components of the same application or applications
with the same user ID.
<p>
The default value depends on whether the broadcast receiver contains intent filters.
The absence of any filters means that it can be invoked only by Intent objects that
specify its exact class name. This implies that the receiver is intended only for
application-internal use (since others would not normally know the class name).
So in this case, the default value is "{@code false}".
On the other hand, the presence of at least one filter implies that the broadcast
receiver is intended to receive intents broadcast by the system or other applications,
so the default value is "{@code true}".
</p>
<p>
This attribute is not the only way to limit a broadcast receiver's external exposure.
You can also use a permission to limit the external entities that can send it messages
(see the <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html#prmsn">permission</a></code> attribute).
</p></dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon representing the broadcast receiver. This attribute must be set
as a reference to a drawable resource containing the image definition.
If it is not set, the icon specified for the application as a whole is used
instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).
<p>
The broadcast receiver's icon &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element &mdash; is also the
default icon for all the receiver's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute).
</p></dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the broadcast receiver. If this attribute is not
set, the label set for the application as a whole is
used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute).
<p>
The broadcast receiver's label &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element &mdash; is also the
default label for all the receiver's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute).
</p>
<p>
The label should be set as a reference to a string resource, so that
it can be localized like other strings in the user interface.
However, as a convenience while you're developing the application,
it can also be set as a raw string.
</p></dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the class that implements the broadcast receiver, a subclass of
{@link android.content.BroadcastReceiver}. This should be a fully qualified
class name (such as, "{@code com.example.project.ReportReceiver}"). However,
as a shorthand, if the first character of the name is a period (for example,
"{@code . ReportReceiver}"), it is appended to the package name specified in
the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.
<p>
There is no default. The name must be specified.
</p></dd>
<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that broadcasters must have to send a
message to the broadcast receiver.
If this attribute is not set, the permission set by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies
to the broadcast receiver. If neither attribute is set, the receiver
is not protected by a permission.
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
section in the introduction and a separate document,
<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>.
</p></dd>
<dt><a name="proc"></a>{@code android:process}</dt>
<dd>The name of the process in which the broadcast receiver should run.
Normally, all components of an application run in the default process created
for the application. It has the same name as the application package. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different
default for all components. But each component can override the default
with its own {@code process} attribute, allowing you to spread your
application across multiple processes.
<p>
If the name assigned to this attribute begins with a colon (':'), a new
process, private to the application, is created when it's needed and
the broadcast receiver runs in that process.
If the process name begins with a lowercase character, the receiver will run
in a global process of that name, provided that it has permission to do so.
This allows components in different applications to share a process, reducing
resource usage.
</p></dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
</dl>

180
base/docs/html/guide/topics/manifest/service-element.jd Normal file
View File

@ -0,0 +1,180 @@
page.title=&lt;service&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;service android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#exported">exported[</a>="true" | "false"]
android:<a href="#icon">icon</a>="<i>drawable resource</i>"
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#proc">process</a>="<i>string</i>" &gt;
. . .
&lt;/service&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>
<dt>description:</dt>
<dd>Declares a service (a {@link android.app.Service} subclass) as one
of the application's components. Unlike activities, services lack a
visual user interface. They're used to implement long-running background
operations or a rich communications API that can be called by other
applications.
<p>
All services must be represented by {@code &lt;service&gt;} elements in
the manifest file. Any that are not declared there will not be seen
by the system and will never be run.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the service can be instantiated by the system &mdash;
"{@code true}" if it can be, and "{@code false}" if not. The default value
is "{@code true}".
<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element has its own
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all
application components, including services. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> and {@code &lt;service&gt;}
attributes must both be "{@code true}" (as they both
are by default) for the service to be enabled. If either is
"{@code false}", the service is disabled; it cannot be instantiated.
</p></dd>
<dt><a name="exported"></a>{@code android:exported}</dt>
<dd>Whether or not components of other applications can invoke
the service or interact with it &mdash; "{@code true}" if they can, and
"{@code false}" if not. When the value is "{@code false}", only
components of the same application or applications
with the same user ID can start the service or bind to it.
<p>
The default value depends on whether the service contains intent filters. The
absence of any filters means that it can be invoked only by specifying
its exact class name. This implies that the service is intended only for
application-internal use (since others would not know the class name). So in
this case, the default value is "{@code false}".
On the other hand, the presence of at least one filter implies that the service
is intended for external use, so the default value is "{@code true}".
</p>
<p>
This attribute is not the only way to limit the exposure of a service to other
applications. You can also use a permission to limit the external entities that
can interact with the service (see the <code><a href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">permission</a></code>
attribute).
</p></dd>
<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>An icon representing the service. This attribute must be set as a
reference to a drawable resource containing the image definition.
If it is not set, the icon specified for the application
as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).
</p>
<p>
The service's icon &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element &mdash; is also the
default icon for all the service's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute).
</p></dd>
<dt><a name="label"></a>{@code android:label}</dt>
<dd>A name for the service that can be displayed to users.
If this attribute is not set, the label set for the application as a whole is
used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute).
<p>
The service's label &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element &mdash; is also the
default label for all the service's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute).
</p>
<p>
The label should be set as a reference to a string resource, so that
it can be localized like other strings in the user interface.
However, as a convenience while you're developing the application,
it can also be set as a raw string.
</p></dd>
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the {@link android.app.Service} subclass that implements
the service. This should be a fully qualified class name (such as,
"{@code com.example.project.RoomService}"). However, as a shorthand, if
the first character of the name is a period (for example, "{@code .RoomService}"),
it is appended to the package name specified in the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> element.
<p>
There is no default. The name must be specified.
</p></dd>
<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that that an entity must have in order to
launch the service or bind to it. If a caller of
<code>{@link android.content.Context#startService startService()}</code>,
<code>{@link android.content.Context#bindService bindService()}</code>, or
<code>{@link android.content.Context#stopService stopService()}</code>,
has not been granted this permission, the method will not work and the
Intent object will not be delivered to the service.
<p>
If this attribute is not set, the permission set by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code>
attribute applies to the service. If neither attribute is set, the service is
not protected by a permission.
</p>
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
section in the introduction and a separate document,
<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>.
</p></dd>
<dt><a name="proc"></a>{@code android:process}</dt>
<dd>The name of the process where the service is to run. Normally,
all components of an application run in the default process created for the
application. It has the same name as the application package. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code>
attribute can set a different
default for all components. But component can override the default
with its own {@code process} attribute, allowing you to spread your
application across multiple processes.
<p>
If the name assigned to this attribute begins with a colon (':'), a new
process, private to the application, is created when it's needed and
the service runs in that process.
If the process name begins with a lowercase character, the service will run
in a global process of that name, provided that it has permission to do so.
This allows components in different applications to share a process, reducing
resource usage.
</p></dd>
</dl></dd>
<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
<br><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
</dl>

114
base/docs/html/guide/topics/manifest/supports-screens-element.jd Normal file
View File

@ -0,0 +1,114 @@
page.title=&lt;supports-screens&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd>
<pre class="stx">
&lt;supports-screens android:<a href="#small">smallScreens</a>=["true" | "false"]
android:<a href="#normal">normalScreens</a>=["true" | "false"]
android:<a href="#large">largeScreens</a>=["true" | "false"]
android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"]
android:<a href="#any">anyDensity</a>=["true" | "false"] /&gt;
</pre>
</dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Lets you specify the screen dimensions the
application supports. By default a modern application (using API Level 4 or higher) supports all
screen sizes and must explicitly disable certain screen sizes here;
older applications are assumed to support only the "normal"
screen size. Note that screen size is a separate axis from
density. Screen size is determined as the available pixels to an application
after density scaling has been applied.
<p>Based on the target device screen density, the Android
framework will scale down assets by a factor of 0.75 (low dpi screens)
or scale them up by a factor of 1.5 (high dpi screens).
The screen density is expressed as dots-per-inch (dpi).</p>
<p>For more information, see
<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>
<dt>attributes:</dt>
<dd>
<dl class="attr"><dt><a name="small"></a>{@code android:smallScreens}</dt>
<dd>Indicates whether the application supports smaller screen form-factors.
A small screen is defined as one with a smaller aspect ratio than
the "normal" (traditional HVGA) screen. An application that does
not support small screens <em>will not be available</em> for
small screen devices, because there is little the platform can do
to make such an application work on a smaller screen. If the application has set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
the default value for this is "true", any value less than "4" results in this set to "false".
</dd>
<dt><a name="normal"></a>{@code android:normalScreens}</dt>
<dd>Indicates whether an application supports the "normal" screen
form-factors. Traditionally this is an HVGA medium density
screen, but WQVGA low density and WVGA high density are also
considered to be normal. This attribute is "true" by default,
and applications currently should leave it that way.
</dd>
<dt><a name="large"></a>{@code android:largeScreens}</dt>
<dd>Indicates whether the application supports larger screen form-factors.
A large screen is defined as a screen that is significantly larger
than a "normal" phone screen, and thus may require some special care
on the application's part to make good use of it. An application that
does not support large screens (declares this "false")&mdash;but does support "normal" or
"small" screens&mdash;will be placed as a "postage stamp" on
a large screen, so that it retains the dimensions it was originally
designed for. If the application has set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
the default value for this is "true", any value less than "4" results in this set to "false".
</dd>
<dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>
<dd>Indicates whether the application supports extra large screen form-factors.
An xlarge screen is defined as a screen that is significantly larger
than a "large" screen, such as a tablet (or something larger) and may require special care
on the application's part to make good use of it. An application that
does not support xlarge screens (declares this "false")&mdash;but does support "large",
"normal", or "small" screens&mdash;will be placed as a "postage stamp" on
an xlarge screen, so that it retains the dimensions it was originally
designed for. If the application has set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
the default value for this is "true", any value less than "4" results in this set to "false".
<p>This attribute was introduced in API Level 9.</p>
</dd>
<dt><a name="any"></a>{@code android:anyDensity}</dt>
<dd>Indicates whether the application includes resources to accommodate any screen
density. Older applications (before API Level 4) are assumed unable to
accomodate all densities and this is "false" by default. Applications using
API Level 4 or higher are assumed able to and this is "true" by default.
You can explicitly supply your abilities here.
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 4</dd>
<dt>see also:</dt>
<dd>
<ul>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a></li>
<li>{@link android.util.DisplayMetrics}</li>
</ul>
</dd>
</dl>

181
base/docs/html/guide/topics/manifest/uses-configuration-element.jd Executable file
View File

@ -0,0 +1,181 @@
page.title=&lt;uses-configuration&gt;
@jd:body
<!-- ##api level 3## see comment below -->
<!-- the "no___" values are nonsensical if they mean "doesn't work on devices with a
keyboard / navigation control / touch screen." Dianne says that that's what they mean and
that they therefore should be eliminated. Suchi says that they mean "doesn't require a
keyboard / navigation control / touch screen to work." But then what does "undefined" mean?
Seems like some API change is in the works, either eliminating the "no___" values or
"undefined". Since it's unclear what the change will be, I've chosen to document the "no___"
and "undefined" attributes using the same language, which is surely wrong but may make it
easier to update the doc when the change is made. -->
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;uses-configuration android:<a href="#five">reqFiveWayNav</a>=["true" | "false"]
android:<a href="#hard">reqHardKeyboard</a>=["true" | "false"]
android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" |
"twelvekey"]
android:<a href="#nav">reqNavigation</a>=["undefined" | "nonav" | "dpad" |
"trackball" | "wheel"]
android:<a href="#touch">reqTouchScreen</a>=["undefined" | "notouch" | "stylus" |
"finger"] /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Indicates what hardware and software features the application requires.
For example, an application might specify that it requires a physical keyboard
or a particular navigation device, like a trackball. The specification is
used to avoid installing the application on devices where it will not work.
<p>
If an application can work with different device configurations, it
should include separate {@code &lt;uses-configuration&gt;} declarations for
each one. Each declaration must be complete. For example, if an application
requires a five-way navigation control, a touch screen that can be operated
with a finger, and either a standard QWERTY keyboard or a numeric 12-key
keypad like those found on most phones, it would specify these requirements
with two {@code &lt;uses-configuration&gt;} elements as follows:
</p>
<pre>&lt;uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
android:reqKeyboardType="qwerty" /&gt;
&lt;uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
android:reqKeyboardType="twelvekey" /&gt;</pre></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="five"></a>{@code android:reqFiveWayNav}</dt>
<dd>Whether or not the application requires a five-way navigation control
&mdash; "{@code true}" if it does, and "{@code false}" if not. A five-way
control is one that can move the selection up, down, right, or left, and
also provides a way of invoking the current selection. It could be a
D-pad (directional pad), trackball, or other device.
<p>
If an application requires a directional control, but not a control of a
particular type, it can set this attribute to "{@code true}" and ignore
the <code><a href="#nav">reqNavigation</a></code> attribute. However,
if it requires a particular type of directional control, it can ignore
this attribute and set {@code reqNavigation} instead.
</p></dd>
<dt><a name="hard"></a>{@code android:reqHardKeyboard}</dt>
<dd>Whether or not the application requires a hardware keyboard &mdash;
"{@code true}" if it does, and "{@code false}" if not.</dd>
<dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt>
<dd>The type of keyboard the application requires, if any at all.
This attribute does not distinguish between hardware and software
keyboards. If a hardware keyboard of a certain type is required,
specify the type here and also set the {@code reqHardKeyboard} attribute
to "{@code true}".
<p>
The value must be one of the following strings:
</p>
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code undefined}"</td>
<td>The application does not require a keyboard.
(A keyboard requirement is not defined.)
This is the default value.</td>
</tr><tr>
<td>"{@code nokeys}"</td>
<td>The application does not require a keyboard.</td>
</tr><tr>
<td>"{@code qwerty}"</td>
<td>The application requires a standard QWERTY keyboard.</td>
</tr><tr>
<td>"{@code twelvekey}"</td>
<td>The application requires a twelve-key keypad, like those on most
phones &mdash; with keys for the digits from {@code 0} through
{@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td>
</tr>
</table></dd>
<dt><a name="nav"></a>{@code android:reqNavigation}</dt>
<dd>The navigation device required by the application, if any. The value
must be one of the following strings:
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code undefined}"</td>
<td>The application does not require any type of navigation control.
(The navigation requirement is not defined.)
This is the default value.</td>
</tr><tr>
<td>"{@code nonav}"</td>
<td>The application does not require a navigation control.</td>
</tr><tr>
<td>"{@code dpad}"</td>
<td>The application requires a D-pad (directional pad) for navigation.</td>
</tr><tr>
<td>"{@code trackball}"</td>
<td>The application requires a trackball for navigation.</td>
</tr><tr>
<td>"{@code wheel}"</td>
<td>The application requires a navigation wheel.</td>
</tr>
</table>
<p>
If an application requires a navigational control, but the exact type of
control doesn't matter, it can set the
<code><a href="#five">reqFiveWayNav</a></code> attribute to "{@code true}"
rather than set this one.
</p></dd>
<dt><a name="touch"></a>{@code android:reqTouchScreen}</dt>
<dd>The type of touch screen the application requires, if any at all.
The value must be one of the following strings:
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code undefined}"</td>
<td>The application doesn't require a touch screen.
(The touch screen requirement is undefined.)
This is the default value.</td>
</tr><tr>
<td>"{@code notouch}"</td>
<td>The application doesn't require a touch screen.</td>
</tr><tr>
<td>"{@code stylus}"</td>
<td>The application requires a touch screen that's operated with a stylus.</td>
</tr><tr>
<td>"{@code finger}"</td>
<td>The application requires a touch screen that can be operated with a finger.</td>
</tr>
</table></dd>
</dl></dd>
<!-- ##api level 3## -->
<dt>introduced in:</dt>
<dd>API Level 3</dd>
<dt>see also:</dt>
<dd>
<ul>
<li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code>
attribute of the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element</dd></li>
<li>{@link android.content.pm.ConfigurationInfo}</li>
</ul>
</dd>
</dl>

898
base/docs/html/guide/topics/manifest/uses-feature-element.jd Normal file
View File

@ -0,0 +1,898 @@
page.title=&lt;uses-feature&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd>
<pre class="stx">&lt;uses-feature android:<a href="#name">name</a>="<em>string</em>"
android:<a href="#required">required</a>=["true" | "false"]
android:<a href="#glEsVersion">glEsVersion</a>="<em>integer</em>" /&gt;</pre>
</dd>
<dt>contained in:</dt>
<dd><code><a
href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<div class="sidebox-wrapper">
<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
<div id="qv-sub-rule">
<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
<p style="color:#669999;">Android Market and <code style="color:#669999;">&lt;uses-feature&gt;</code> elements</p>
<p style="margin-top:1em;">Android Market filters the applications that are visible to users, so
that users can see and download only those applications that are compatible with their
devices. One of the ways Market filters applications is by feature compatibility.</p>
<p style="margin-top:1em;">To do this, Market checks the
<code>&lt;uses-feature&gt;</code> elements in each application's manifest, to
establish the app's feature needs. Market then shows or hides the application to
each user, based on a comparison with the features available on the user's
device. </p>
<p style="margin-top:1em;">By specifying the features that your application requires,
you enable Android Market to present your application only to users whose
devices meet the application's feature requirements, rather than presenting it
to all users. </p>
<p style="margin-top:1em;" class="caution">For important information about how
Android Market uses features as the basis for filtering, please read <a
href="#market-feature-filtering">Android Market and Feature-Based Filtering</a>,
below.</p>
</div>
</div>
<dt>description:</dt>
<dd>Declares a single hardware or software feature that is used by the
application.
<p>The purpose of a <code>&lt;uses-feature&gt;</code> declaration is to inform
any external entity of the set of hardware and software features on which your
application depends. The element offers a <code>required</code> attribute that
lets you specify whether your application requires and cannot function without
the declared feature, or whether it prefers to have the feature but can function
without it. Because feature support can vary across Android devices, the
<code>&lt;uses-feature&gt;</code> element serves an important role in letting an
application describe the device-variable features that it uses.</p>
<p>The set of available features that your application declares corresponds to
the set of feature constants made available by the Android {@link
android.content.pm.PackageManager}, which are listed for
convenience in the <a href="#features-reference">Features Reference</a> tables
at the bottom of this document.
<p>You must specify each feature in a separate <code>&lt;uses-feature&gt;</code>
element, so if your application requires multiple features, it would declare
multiple <code>&lt;uses-feature&gt;</code> elements. For example, an application
that requires both Bluetooth and camera features in the device would declare
these two elements:</p>
<pre>
&lt;uses-feature android:name="android.hardware.bluetooth" />
&lt;uses-feature android:name="android.hardware.camera" />
</pre>
<p>In general, you should always make sure to declare
<code>&lt;uses-feature&gt;</code> elements for all of the features that your
application requires.</p>
<p>Declared <code>&lt;uses-feature></code> elements are informational only, meaning
that the Android system itself does not check for matching feature support on
the device before installing an application. However, other services
(such as Android Market) or applications may check your application's
<code>&lt;uses-feature></code> declarations as part of handling or interacting
with your application. For this reason, it's very important that you declare all of
the features (from the list below) that your application uses. </p>
<p>For some features, there may exist a specfic attribute that allows you to define
a version of the feature, such as the version of Open GL used (declared with
<a href="#glEsVersion"><code>glEsVersion</code></a>). Other features that either do or do not
exist for a device, such as a camera, are declared using the
<a href="#name"><code>name</code></a> attribute.</p>
<p>Although the <code>&lt;uses-feature></code> element is only activated for
devices running API Level 4 or higher, it is recommended to include these
elements for all applications, even if the <a href="uses-sdk-element.html#min"><code>minSdkVersion</code></a>
is "3" or lower. Devices running older versions of the platform will simply
ignore the element.</p>
<p class="note"><strong>Note:</strong> When declaring a feature, remember
that you must also request permissions as appropriate. For example, you must
still request the {@link android.Manifest.permission#CAMERA}
permission before your application can access the camera API. Requesting the
permission grants your application access to the appropriate hardware and
software, while declaring the features used by your application ensures proper
device compatibility.</p>
</dd>
<dt>attributes:</dt>
<dd>
<dl class="attr">
<dt><a name="name"></a><code>android:name</code></dt>
<dd>Specifies a single hardware or software feature used by the application,
as a descriptor string. Valid descriptor values are listed in the <a
href="#hw-features">Hardware features</a> and <a href="#sw-features">Software
features</a> tables, below. </dd>
<dt><a name="required"></a><code>android:required</code></dt> <!-- added in api level 5 -->
<dd>Boolean value that indicates whether the application requires
the feature specified in <code>android:name</code>.
<ul>
<li>When you declare <code>"android:required="true"</code> for a feature,
you are specifying that the application <em>cannot function, or is not
designed to function</em>, when the specified feature is not present on the
device. </li>
<li>When you declare <code>"android:required="false"</code> for a feature, it
means that the application <em>prefers to use the feature</em> if present on
the device, but that it <em>is designed to function without the specified
feature</em>, if necessary. </li>
</ul>
<p>The default value for <code>android:required</code> if not declared is
<code>"true"</code>.</p>
</dd>
<dt><a name="glEsVersion"></a><code>android:glEsVersion</code></dt>
<dd>The OpenGL ES version required by the application. The higher 16 bits
represent the major number and the lower 16 bits represent the minor number. For
example, to specify OpenGL ES version 2.0, you would set the value as
"0x00020000". To specify OpenGL ES 2.1, if/when such a version were made
available, you would set the value as "0x00020001".
<p>An application should specify at most one <code>android:glEsVersion</code>
attribute in its manifest. If it specifies more than one, the
<code>android:glEsVersion</code> with the numerically highest value is used and
any other values are ignored.</p>
<p>If an application does not specify an <code>android:glEsVersion</code>
attribute, then it is assumed that the application requires only OpenGL ES 1.0,
which is supported by all Android-powered devices.</p>
<p>An application can assume that if a platform supports a given OpenGL ES
version, it also supports all numerically lower OpenGL ES versions. Therefore,
an application that requires both OpenGL ES 1.0 and OpenGL ES 2.0 must specify
that it requires OpenGL ES 2.0.</p>
<p>An application that can work with any of several OpenGL ES versions should
only specify the numerically lowest version of OpenGL ES that it requires. (It
can check at run-time whether a higher level of OpenGL ES is available.)</p>
</dd>
</dl>
</dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 4</dd>
<dt>see also:</dt>
<dd>
<ul>
<li>{@link android.content.pm.PackageManager}</li>
<li>{@link android.content.pm.FeatureInfo}</li>
<li>{@link android.content.pm.ConfigurationInfo}</li>
<li><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code>&lt;uses-permission&gt;</code></a></li>
<li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li>
</ul>
</dd>
</dl>
<h2 id="market-feature-filtering">Android Market and Feature-Based Filtering</h2>
<p>Android Market filters the applications that are visible to users, so that
users can see and download only those applications that are compatible with
their devices. One of the ways Market filters applications is by feature
compatibility.</p>
<p>To determine an application's feature compatibility with a given user's
device, the Android Market service compares:</p>
<ul>
<li>Features required by the application &mdash; an application declares features in
<code>&lt;uses-feature&gt;</code> elements in its manifest <br/>with...</li>
<li>Features available on the device, in hardware or software &mdash;
a device reports the features it supports as read-only system properties.</li>
</ul>
<p>To ensure an accurate comparison of features, the Android Package Manager
provides a shared set of feature constants that both applications and devices
use to declare feature requirements and support. The available feature constants
are listed in the <a href="#features-reference">Features Reference</a> tables at
the bottom of this document, and in the class documentation for {@link
android.content.pm.PackageManager}.</p>
<p>When the user launches the Market application, the application queries the
Package Manager for the list of features available on the device by calling
{@link android.content.pm.PackageManager#getSystemAvailableFeatures()}. The
Market application then passes the features list up to the Android Market
service when establishing the session for the user.</p>
<p>Each time you upload an application to the Android Market Publisher Site,
Android Market scans the application's manifest file. It looks for
<code>&lt;uses-feature&gt;</code> elements and evaluates them in combination
with other elements, in some cases, such as <code>&lt;uses-sdk&gt;</code> and
<code>&lt;uses-permission&gt;</code> elements. After establishing the
application's set of required features, it stores that list internally as
metadata associated with the application <code>.apk</code> and the application
version. </p>
<p>When a user searches or browses for applications using the Android Market
application, the service compares the features needed by each application with
the features available on the user's device. If all of an application's required
features are present on the device, Android Market allows the user to see the
application and potentially download it. If any required feature is not
supported by the device, Android Market filters the application so that it is
not visible to the user and not available for download. </p>
<p>Because the features you declare in <code>&lt;uses-feature&gt;</code>
elements directly affect how Android Market filters your application, it's
important to understand how Android Market evaluates the application's manifest
and establishes the set of required features. The sections below provide more
information. </p>
<h3 id="declared">Filtering based on explicitly declared features</h3>
<p>An explicitly declared feature is one that your application declares in a
<code>&lt;uses-feature&gt;</code> element. The feature declaration can include
an <code>android:required=["true" | "false"]</code> attribute (if you are
compiling against API level 5 or higher), which lets you specify whether the
application absolutely requires the feature and cannot function properly without
it (<code>"true"</code>), or whether the application prefers to use the feature
if available, but is designed to run without it (<code>"false"</code>).</p>
<p>Android Market handles explictly declared features in this way: </p>
<ul>
<li>If a feature is explicitly declared as being required, Android Market adds
the feature to the list of required features for the application. It then
filters the application from users on devices that do not provide that feature.
For example:
<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="true" /&gt;</pre></li>
<li>If a feature is explicitly declared as <em>not</em> being required, Android
Market <em>does not</em> add the feature to the list of required features. For
that reason, an explicity declared non-required feature is never considered when
filtering the application. Even if the device does not provide the declared
feature, Android Market will still consider the application compatible with the
device and will show it to the user, unless other filtering rules apply. For
example:
<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre></li>
<li>If a feature is explicitly declared, but without an
<code>android:required</code> attribute, Android Market assumes that the feature
is required and sets up filtering on it. </li>
</ul>
<p>In general, if your application is designed to run on Android 1.6 and earlier
versions, the <code>android:required</code> attribute is not available in the
API and Android Market assumes that any and all
<code>&lt;uses-feature&gt;</code> declarations are required. </p>
<p class="note"><strong>Note:</strong> By declaring a feature explicitly and
including an <code>android:required="false"</code> attribute, you can
effectively disable all filtering on Android Market for the specified feature.
</p>
<h3 id="implicit">Filtering based on implicit features</h3>
<p>An <em>implicit</em> feature is one that an application requires in order to
function properly, but which is <em>not</em> declared in a
<code>&lt;uses-feature&gt;</code> element in the manifest file. Strictly
speaking, every application should <em>always</em> declare all features that it
uses or requires, so the absence of a declaration for a feature used by an
application should be considered an error. However, as a safeguard for users and
developers, Android Market looks for implicit features in each application and
sets up filters for those features, just as it would do for an explicitly
declared feature. </p>
<p>An application might require a feature but not declare it because: </p>
<ul>
<li>The application was compiled against an older version of the Android library
(Android 1.5 or earlier) and the <code>&lt;uses-feature&gt;</code> element was
not available.</li>
<li>The developer incorrectly assumed that the feature would be present on all
devices and a declaration was unnecessary.</li>
<li>The developer omitted the feature declaration accidentally.</li>
<li>The developer declared the feature explicitly, but the declaration was not
valid. For example, a spelling error in the <code>&lt;uses-feature&gt;</code>
element name or an unrecognized string value for the
<code>android:name</code> attribute would invalidate the feature declaration.
</li>
</ul>
<p>To account for the cases above, Android Market attempts to discover an
application's implied feature requirements by examining <em>other elements</em>
declared in the manifest file, specifically,
<code>&lt;uses-permission&gt;</code> elements.</p>
<p>If an application requests hardware-related permissions, Android Market
<em>assumes that the application uses the underlying hardware features and
therefore requires those features</em>, even though there might be no
corresponding to <code>&lt;uses-feature&gt;</code> declarations. For such
permissions, Android Market adds the underlying hardware features to the
metadata that it stores for the application and sets up filters for them.</p>
<p>For example, if an application requests the <code>CAMERA</code> permission
but does not declare a <code>&lt;uses-feature&gt;</code> element for
<code>android.hardware.camera</code>, Android Market considers that the
application requires a camera and should not be shown to users whose devices do
not offer a camera.</p>
<p>If you don't want Android Market to filter based on a specific implied
feature, you can disable that behavior. To do so, declare the feature explicitly
in a <code>&lt;uses-feature&gt;</code> element and include an
<code>android:required="false"</code> attribute. For example, to disable
filtering derived from the <code>CAMERA</code> permission, you would declare
the feature as shown below.</p>
<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>
<p class="caution">It's important to understand that the permissions that you
request in <code>&lt;uses-permission&gt;</code> elements can directly affect how
Android Market filters your application. The reference section <a
href="#permissions">Permissions that Imply Feature Requirements</a>,
below, lists the full set of permissions that imply feature requirements and
therefore trigger filtering.</p>
<h3 id="bt-permission-handling">Special handling for Bluetooth feature</h3>
<p>Android Market applies slightly different rules than described above, when
determining filtering for Bluetooth.</p>
<p>If an application declares a Bluetooth permission in a
<code>&lt;uses-permission&gt;</code> element, but does not explicitly declare
the Bluetooth feature in a <code>&lt;uses-feature&gt;</code> element, Android
Market checks the version(s) of the Android platform on which the application is
designed to run, as specified in the <code>&lt;uses-sdk&gt;</code> element. </p>
<p>As shown in the table below, Android Market enables filtering for the
Bluetooth feature only if the application declares its lowest or targeted
platform as Android 2.0 (API level 5) or higher. However, note that Android
market applies the normal rules for filtering when the application explicitly
declares the Bluetooth feature in a <code>&lt;uses-feature&gt;</code> element.
</p>
<p class="caption"><strong>Table 1.</strong> How Android Market determines the
Bluetooth feature requirement for an application that requests a Bluetooth
permission but does not declare the Bluetooth feature in a
<code>&lt;uses-feature&gt;</code> element.</p>
<table style="margin-top:1em;">
<tr>
<th><nobr>If <code>minSdkVersion</code> is ...</nobr></th>
<th><nobr>or <code>targetSdkVersion</code> is</nobr></th>
<th>Result</th>
</tr>
<tr>
<td><nobr>&lt;=4 (or uses-sdk is not declared)</nobr></td>
<td>&lt;=4</td>
<td>Android Market <em>will not</em> filter the application from any devices
based on their reported support for the <code>android.hardware.bluetooth</code>
feature.</td>
</tr>
<tr>
<td>&lt;=4</td>
<td>&gt;=5</td>
<td rowspan="2">Android Market filters the application from any devices that
do not support the <code>android.hardware.bluetooth</code> feature (including
older releases).</td>
</tr>
<tr>
<td>&gt;=5</td>
<td>&gt;=5</td>
</tr>
</table>
<p>The examples below illustrate the different filtering effects, based on how
Android Market handles the Bluetooth feature. </p>
<dl>
<dt>In first example, an application that is designed to run on older API levels
declares a Bluetooth permission, but does not declare the Bluetooth feature in a
<code>&lt;uses-feature&gt;</code> element.</dt>
<dd><em>Result:</em> Android Market does not filter the application from any device.</dd>
</dl>
<pre>&lt;manifest ...>
&lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
&lt;uses-sdk android:minSdkVersion="3" />
...
&lt;/manifest></pre>
<dl>
<dt>In the second example, below, the same application also declares a target
API level of "5". </dt>
<dd><em>Result:</em> Android Market now assumes that the feature is required and
will filter the application from all devices that do not report Bluetooth support,
including devices running older versions of the platform. </dd>
</dl>
<pre>&lt;manifest ...>
&lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
&lt;uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
...
&lt;/manifest></pre>
<dl>
<dt>Here the same application now specifically declares the Bluetooth feature.</dt>
<dd><em>Result:</em> Identical to the previous example (filtering is applied).</dd>
</dl>
<pre>&lt;manifest ...>
&lt;uses-feature android:name="android.hardware.bluetooth" />
&lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
&lt;uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
...
&lt;/manifest></pre>
<dl>
<dt>Finally, in the case below, the same application adds an
<code>android:required="false"</code> attribute.</dt>
<dd><em>Result:</em> Android Market disables filtering based on Bluetooth
feature support, for all devices.</dd>
</dl>
<pre>&lt;manifest ...>
&lt;uses-feature android:name="android.hardware.bluetooth" android:required="false" />
&lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
&lt;uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
...
&lt;/manifest></pre>
<h3>Testing the features required by your application</h3>
<p>You can use the <code>aapt</code> tool, included in the Android SDK, to
determine how Android Market will filter your application, based on its declared
features and permissions. To do so, run <code>aapt</code> with the <code>dump
badging</code> command. This causes <code>aapt</code> to parse your
application's manifest and apply the same rules as used by Android Market to
determine the features that your application requires. </p>
<p>To use the tool, follow these steps: </p>
<ol>
<li>First, build and export your application as an unsigned <code>.apk</code>.
If you are developing in Eclipse with ADT, right-click the project and select
<strong>Android Tools</strong> &gt; <strong>Export Unsigned Application
Package</strong>. Select a destination filename and path and click
<strong>OK</strong>. </li>
<li>Next, locate the <code>aapt</code> tool, if it is not already in your PATH.
If you are using SDK Tools r8 or higher, you can find <code>aapt</code> in the
<code>&lt;<em>SDK</em>&gt;/platform-tools/</code> directory.
<p class="note"><strong>Note:</strong> You must use the version of
<code>aapt</code> that is provided for the latest Platform-Tools component available. If
you do not have the latest Platform-Tools component, download it using the <a
href="{@docRoot}sdk/adding-components.html">Android SDK and AVD Manager</a>.
</p></li>
<li>Run <code>aapt</code> using this syntax: </li>
</ol>
<pre>$ aapt dump badging &lt;<em>path_to_exported_.apk</em>&gt;</pre>
<p>Here's an example of the command output for the second Bluetooth example, above: </p>
<pre>$ ./aapt dump badging BTExample.apk
package: name='com.example.android.btexample' versionCode='' versionName=''
<strong>uses-permission:'android.permission.BLUETOOTH_ADMIN'</strong>
<strong>uses-feature:'android.hardware.bluetooth'</strong>
sdkVersion:'3'
targetSdkVersion:'5'
application: label='BT Example' icon='res/drawable/app_bt_ex.png'
launchable activity name='com.example.android.btexample.MyActivity'label='' icon=''
uses-feature:'android.hardware.touchscreen'
main
supports-screens: 'small' 'normal' 'large'
locales: '--_--'
densities: '160'
</pre>
<h2 id=features-reference>Features Reference</h2>
<p>The tables below provide reference information about hardware and software
features and the permissions that can imply them on Android Market. </p>
<h3 id="hw-features">Hardware features</h3>
<p>The table below describes the hardware feature descriptors supported by the
most current platform release. To signal that your application uses or requires
a hardware feature, declare each value in a <code>android:name</code> attribute
in a separate <code>&lt;uses-feature&gt;</code> element. </p>
<table>
<tr>
<th>Feature Type</th>
<th>Feature Descriptor</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td>Audio</td>
<td><code>android.hardware.audio.low_latency</td>
<td>The application uses a low-latency audio pipeline on the device and
is sensitive to delays or lag in sound input or output.</td>
<td>
</td>
</tr>
<tr>
<td>Bluetooth</td>
<td><code>android.hardware.bluetooth</td>
<td>The application uses Bluetooth radio features in the device.</td>
<td>
</td>
</tr>
<tr>
<td rowspan="4">Camera</td>
<td><code>android.hardware.camera</code></td>
<td>The application uses the device's camera. If the device supports
multiple cameras, the application uses the camera that facing
away from the screen.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.camera.autofocus</code></td>
<td>Subfeature. The application uses the device camera's autofocus capability.</td>
<td rowspan="3">If declared with the <code>"android:required="true"</code>
attribute, these subfeatures implicitly declare the
<code>android.hardware.camera</code> parent feature. </td>
</tr>
<tr>
<td><code>android.hardware.camera.flash</code></td>
<td>Subfeature. The application uses the device camera's flash.</td>
</tr>
<tr>
<td><code>android.hardware.camera.front</code></td>
<td>Subfeature. The application uses a front-facing camera on the device.</td>
</tr>
<tr>
<td rowspan="3">Location</td>
<td><code>android.hardware.location</code></td>
<td>The application uses one or more features on the device for determining
location, such as GPS location, network location, or cell location.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.location.network</code></td>
<td>Subfeature. The application uses coarse location coordinates obtained from
a network-based geolocation system supported on the device.</td>
<td rowspan="2">If declared with the <code>"android:required="true"</code>
attribute, these subfeatures implicitly declare the
<code>android.hardware.location</code> parent feature. </td>
</tr>
<tr>
<td><code>android.hardware.location.gps</code></td>
<td>Subfeature. The application uses precise location coordinates obtained
from a Global Positioning System receiver on the device. </td>
</tr>
<tr>
<td>Microphone</td>
<td><code>android.hardware.microphone</code></td>
<td>The application uses a microphone on the device.
</td>
<td></td>
</tr>
<tr>
<td>Near Field Communications</td>
<td><code>android.hardware.nfc</td>
<td>The application uses NFC radio features in the device.</td>
<td></td>
</tr>
<tr>
<td rowspan="6">Sensors</td>
<td><code>android.hardware.sensor.accelerometer</code></td>
<td>The application uses motion readings from an accelerometer on the
device.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.sensor.barometer</code></td>
<td>The application uses the device's barometer.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.sensor.compass</code></td>
<td>The application uses directional readings from a magnetometer (compass) on
the device.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.sensor.gyroscope</code></td>
<td>The application uses the device's gyroscope sensor.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.sensor.light</code></td>
<td>The application uses the device's light sensor.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.sensor.proximity</code></td>
<td>The application uses the device's proximity sensor.</td>
<td></td>
</tr>
<tr>
<td rowspan="3">Telephony</td>
<td><code>android.hardware.telephony</code></td>
<td>The application uses telephony features on the device, such as telephony
radio with data communication services.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.telephony.cdma</code></td>
<td>Subfeature. The application uses CDMA telephony radio features on the
device. </td>
<td rowspan="2">If declared with the <code>"android:required="true"</code>
attribute, these subfeatures implicitly declare the
<code>android.hardware.telephony</code> parent feature. </td>
</tr>
<tr>
<td><code>android.hardware.telephony.gsm</code></td>
<td>Subfeature. The application uses GSM telephony radio features on the
device.</td>
</tr>
<tr>
<td rowspan="4">Touchscreen</td>
<td><code>android.hardware.touchscreen</code></td>
<td>The application uses touchscreen capabilities on the device.</td>
<td></td>
</tr>
<tr>
<td><code>android.hardware.touchscreen.multitouch</code></td>
<td>Subfeature. The application uses basic two-point multitouch capabilities on the device
screen.</td>
<td>If declared with the <code>"android:required="true"</code> attribute, this
subfeature implicitly declares the <code>android.hardware.touchscreen</code>
parent feature. </td>
</tr>
<tr>
<td><code>android.hardware.touchscreen.multitouch.distinct</code></td>
<td>Subfeature. The application uses advanced multipoint multitouch
capabilities on the device screen, such as for tracking two or more points fully
independently.</td>
<td rowspan="2">If declared with the <code>"android:required="true"</code> attribute, this
subfeature implicitly declares the
<code>android.hardware.touchscreen.multitouch</code> parent feature. </td>
</tr>
<tr>
<td><code>android.hardware.touchscreen.multitouch.jazzhand</code></td>
<td>Subfeature. The application uses advanced multipoint multitouch
capabilities on the device screen, for tracking up to five points fully
independently.</td>
</tr>
<tr>
<td>Wifi</td>
<td><code>android.hardware.wifi</code></td>
<td>The application uses 802.11 networking (wifi) features on the device.</td>
<td></td>
</tr>
</table>
<h3 id="sw-features">Software features</h3>
<p>The table below describes the software feature descriptors supported by the
most current platform release. To signal that your application uses or requires
a software feature, declare each value in a <code>android:name</code> attribute
in a separate <code>&lt;uses-feature&gt;</code> element. </p>
<table>
<tr>
<th>Feature</th>
<th>Attribute Value</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td>Live Wallpaper</td>
<td><code>android.software.live_wallpaper</code></td>
<td>The application uses or provides Live Wallpapers.</td>
<td></td>
</tr>
<tr>
<td rowspan="2">SIP/VOIP</td>
<td><code>android.software.sip</code></td>
<td>The application uses SIP service on the device.
</td>
<td></td>
</tr>
<tr>
<td><code>android.software.sip.voip</code></td>
<td>Subfeature. The application uses SIP-based VOIP service on the device.
</td>
<td>If declared with the <code>"android:required="true"</code> attribute, this
subfeature implicitly declares the <code>android.software.sip</code>
parent feature.</td>
</tr>
</table>
<h3 id="permissions">Permissions that Imply Feature Requirements</h3>
<p>Some feature constants listed in the tables above were made available to
applications <em>after</em> the corresponding API; for example, the
<code>android.hardware.bluetooth</code> feature was added in Android 2.2 (API
level 8), but the bluetooth API that it refers to was added in Android 2.0 (API
level 5). Because of this, some apps were able to use the API before they had
the ability to declare that they require the API via the
<code>&lt;uses-feature&gt;</code> system. </p>
<p>To prevent those apps from being made available unintentionally, Android
Market assumes that certain hardware-related permissions indicate that the
underlying hardware features are required by default. For instance, applications
that use Bluetooth must request the <code>BLUETOOTH</code> permission in a
<code>&lt;uses-permission&gt;</code> element &mdash; for legacy apps, Android
Market assumes that the permission declaration means that the underlying
<code>android.hardware.bluetooth</code> feature is required by the application
and sets up filtering based on that feature. </p>
<p>The table below lists permissions that imply feature requirements
equivalent to those declared in <code>&lt;uses-feature&gt;</code> elements. Note
that <code>&lt;uses-feature&gt;</code> declarations, including any declared
<code>android:required</code> attribute, always take precedence over features
implied by the permissions below. </p>
<p>For any of the permissions below, you can disable filtering based on the
implied feature by explicitly declaring the implied feature explicitly, in a
<code>&lt;uses-feature&gt;</code> element, with an
<code>android:required="false"</code> attribute. For example, to disable any
filtering based on the <code>CAMERA</code> permission, you would add this
<code>&lt;uses-feature&gt;</code> declaration to the manifest file:</p>
<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>
<table id="permissions-features" >
<tr>
<th>Category</th>
<th>This Permission...</th>
<th>Implies This Feature Requirement</th>
<!-- <th>Comments</th> -->
</tr>
<tr>
<td rowspan="2">Bluetooth</td>
<td><code>BLUETOOTH</code></td>
<td><code>android.hardware.bluetooth</code>
<p>(See <a href="#bt-permission-handling">Special handling for Bluetooth feature</a> for details.)</p></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>BLUETOOTH_ADMIN</code></td>
<td><code>android.hardware.bluetooth</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td>Camera</td>
<td><code>CAMERA</code></td>
<td><code>android.hardware.camera</code> <em>and</em>
<br><code>android.hardware.camera.autofocus</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td rowspan="5">Location</td>
<td><code>ACCESS_MOCK_LOCATION</code></td>
<td><code>android.hardware.location</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>ACCESS_LOCATION_EXTRA_COMMANDS</code></td>
<td><code>android.hardware.location</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>INSTALL_LOCATION_PROVIDER</code></td>
<td><code>android.hardware.location</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>ACCESS_COARSE_LOCATION</code></td>
<td><code>android.hardware.location.network</code> <em>and</em>
<br><code>android.hardware.location</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>ACCESS_FINE_LOCATION</code></td>
<td><code>android.hardware.location.gps</code> <em>and</em>
<br><code>android.hardware.location</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td>Microphone</td>
<td><code>RECORD_AUDIO</code></td>
<td><code>android.hardware.microphone</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td rowspan="11">Telephony</td>
<td><code>CALL_PHONE</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>CALL_PRIVILEGED</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>MODIFY_PHONE_STATE</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>PROCESS_OUTGOING_CALLS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>READ_SMS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>RECEIVE_SMS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>RECEIVE_MMS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>RECEIVE_WAP_PUSH</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>SEND_SMS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>WRITE_APN_SETTINGS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>WRITE_SMS</code></td>
<td><code>android.hardware.telephony</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td rowspan="3">Wifi</td>
<td><code>ACCESS_WIFI_STATE</code></td>
<td><code>android.hardware.wifi</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>CHANGE_WIFI_STATE</code></td>
<td><code>android.hardware.wifi</code></td>
<!-- <td></td> -->
</tr>
<tr>
<td><code>CHANGE_WIFI_MULTICAST_STATE</code></td>
<td><code>android.hardware.wifi</code></td>
<!-- <td></td> -->
</tr>
</table>

36
base/docs/html/guide/topics/manifest/uses-library-element.jd Normal file
View File

@ -0,0 +1,36 @@
page.title=&lt;uses-library&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre>&lt;uses-library android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>
<dt>description:</dt>
<dd>Specifies a shared library that the application must be linked against.
This element tells the system to include the library's code in the class
loader for the package.
<p>
All of the {@code android} packages (such as {@link android.app},
{@link android.content}, {@link android.view}, and {@link android.widget})
are in the default library that all applications are automatically linked
against. However, some packages (such as {@code maps} and {@code awt} are
in separate libraries that are not automatically linked. Consult the
documentation for the packages you're using to determine which library
contains the package code.
</p></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the library.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
</dl>

80
base/docs/html/guide/topics/manifest/uses-permission-element.jd Normal file
View File

@ -0,0 +1,80 @@
page.title=&lt;uses-permission&gt;
@jd:body
<dl class="xml">
<div class="sidebox-wrapper">
<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
<div id="qv-sub-rule">
<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
<p style="color:#669999;"><code style="color:#669999;">&lt;uses-permission&gt;</code> and filtering on Android Market. </p>
<p style="margin-top:1em;">In some cases, the permissions that you request
through <code>&lt;uses-permission&gt;</code> can affect how
your application is filtered by Android Market.</p>
<p style="margin-top:1em;">If you request a hardware-related permission &mdash;
<code>CAMERA</code>, for example &mdash; Android Market assumes that your
application requires the underlying hardware feature and filters the application
from devices that do not offer it.</p>
<p style="margin-top:1em;">To control filtering, always explicitly declare
hardware features in <code>&lt;uses-feature&gt;</code> elements, rather than
relying on Android Market to "discover" the requirements in
<code>&lt;uses-permission&gt;</code> elements. Then, if you want to disable
filtering for a particular feature, you can add a
<code>android:required="false"</code> attribute to the
<code>&lt;uses-feature&gt;</code> declaration.</p>
<p style="margin-top:1em;" class="caution">For a list of permissions that imply
hardware features, see the documentation for the <a
href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features">
<code>&lt;uses-feature&gt;</code></a> element.</p>
</div>
</div>
<dt>syntax:</dt>
<dd><pre class="stx">&lt;uses-permission android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Requests a permission that the application must be granted in
order for it to operate correctly. Permissions are granted by the user when the
application is installed, not while it's running.
<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a></code>
section in the introduction and the separate
<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> document.
A list of permissions defined by the base platform can be found at
{@link android.Manifest.permission android.Manifest.permission}.
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the permission. It can be a permission defined by the
application with the <code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element, a permission defined by another application, or one of the
standard system permissions, such as "{@code android.permission.CAMERA}"
or "{@code android.permission.READ_CONTACTS}". As these examples show,
a permission name typically includes the package name as a prefix.</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
<dt>see also:</dt>
<dd>
<ul>
<li><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></code></li>
</ul>
</dd>
</dl>

142
base/docs/html/guide/topics/manifest/uses-sdk-element.jd Normal file
View File

@ -0,0 +1,142 @@
page.title=&lt;uses-sdk&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd><pre>
&lt;uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>"
android:<a href="#target">targetSdkVersion</a>="<i>integer</i>"
android:<a href="#max">maxSdkVersion</a>="<i>integer</i>" /&gt;</pre></dd>
<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Lets you express an application's compatibility with one or more versions of the Android platform,
by means of an API Level integer. The API Level expressed by an application will be compared to the
API Level of a given Android system, which may vary among different Android devices.
</p>
<p>Despite its name, this element is used to specify the API Level, <em>not</em>
the version number of the SDK (software development kit) or Android platform.
The API Level is always a single integer. You cannot derive the API Level from
its associated Android version number (for example, it is not the same as the
major version or the sum of the major and minor versions).</p>
<p>For more information, read about
<a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> and
<a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a>.
</p></dd>
<div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;">
<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
<div id="qv-sub-rule">
<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
<p style="color:#669999;">Android Market and &lt;uses-sdk&gt; attributes</p>
<p>Android Market filters the applications that are visible to users, so
that users can only see and download applications that are compatible with their
devices. One of the ways Market filters applications is by Android
version-compatibility. To do this, Market checks the <code>&lt;uses-sdk&gt;</code>
attributes in each application's manifest to establish its version-compatibility
range, then shows or hides the application based on a comparison with the API
Level of the user's Android system version. For more information, see <a
href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
</div>
</div>
<dt>attributes:</dt>
<dd>
<dl class="attr">
<dt><a name="min"></a>{@code android:minSdkVersion}</dt>
<dd>An integer designating the minimum API Level required
for the application to run. The Android system will prevent the user from installing
the application if the system's API Level is lower than the value specified in
this attribute. You should always declare this attribute.
<p class="caution"><strong>Caution:</strong> If you do not declare this
attribute, the system assumes a default value of "1", which indicates that your
application is compatible with all versions of Android. If your application is
<em>not</em> compatible with all versions (for instance, it uses APIs introduced
in API Level 3) and you have not declared the proper <code>android:minSdkVersion</code>,
then when installed on a system with an API Level less than 3, the application
will crash during runtime when attempting to access the unavailable APIs. For
this reason, be certain to declare the appropriate API Level in the
<code>minSdkVersion</code> attribute.</p>
</dd>
<dt><a name="target"></a>{@code android:targetSdkVersion}</dt>
<dd>An integer designating the API Level that the application is targetting.
<p>With this attribute set, the application says that it is able to run on
older versions (down to {@code minSdkVersion}), but was explicitly tested to
work with the version specified here. Specifying this target version allows the
platform to disable compatibility settings that are not required for the target
version (which may otherwise be turned on in order to maintain
forward-compatibility) or enable newer features that are not available to older
applications. This does not mean that you can program different features for
different versions of the platform&mdash;it simply informs the platform that you
have tested against the target version and the platform should not perform any
extra work to maintain forward-compatibility with the target version.</p>
<p>Introduced in: API Level 4</p>
</dd>
<dt><a name="max"></a>{@code android:maxSdkVersion}</dt>
<dd>An integer designating the maximum API Level on which the application is
designed to run.
<p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this
attribute when installing an application and when revalidating the application
after a system update. In either case, if the application's
<code>android:maxSdkVersion</code> attribute is lower than the API Level used by
the system itself, then the system will not allow the application to be
installed. In the case of revalidation after system update, this effectively
removes your application from the device.
<p>To illustrate how this attribute can affect your application after system
updates, consider the following example: </p>
<p>An application declaring <code>android:maxSdkVersion="5"</code> in its
manifest is published on Android Market. A user whose device is running Android
1.6 (API Level 4) downloads and installs the app. After a few weeks, the user
receives an over-the-air system update to Android 2.0 (API Level 5). After the
update is installed, the system checks the application's
<code>android:maxSdkVersion</code> and successfully revalidates it. The
application functions as normal. However, some time later, the device receives
another system update, this time to Android 2.0.1 (API Level 6). After the
update, the system can no longer revalidate the application because the system's
own API Level (6) is now higher than the maximum supported by the application
(5). The system prevents the application from being visible to the user, in
effect removing it from the device.</p>
<p class="warning"><strong>Warning:</strong> Declaring this attribute is not
recommended. First, there is no need to set the attribute as means of blocking
deployment of your application onto new versions of the Android platform as they
are released. By design, new versions of the platform are fully
backward-compatible. Your application should work properly on new versions,
provided it uses only standard APIs and follows development best practices.
Second, note that in some cases, declaring the attribute can <strong>result in
your application being removed from users' devices after a system
update</strong> to a higher API Level. Most devices on which your appplication
is likely to be installed will receive periodic system updates over the air, so
you should consider their effect on your application before setting this
attribute.</p>
<p style="margin-bottom:1em;">Introduced in: API Level 4</p>
<div class="special">Future versions of Android (beyond Android 2.0.1) will no
longer check or enforce the <code>android:maxSdkVersion</code> attribute during
installation or revalidation. Android Market will continue to use the attribute
as a filter, however, when presenting users with applications available for
download. </div>
</dd>
</dl></dd>
<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>
</dl>