169 lines
8.7 KiB
Plaintext
169 lines
8.7 KiB
Plaintext
page.title=<receiver>
|
|
@jd:body
|
|
|
|
<dl class="xml">
|
|
<dt>syntax:</dt>
|
|
<dd><pre class="stx"><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>" >
|
|
. . .
|
|
</receiver></pre></dd>
|
|
|
|
<dt>contained in:</dt>
|
|
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd>
|
|
|
|
<dt>can contain:</dt>
|
|
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code>
|
|
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></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 —
|
|
"{@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"><application></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"><application></a></code> and
|
|
{@code <receiver>} 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 — "{@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"><application></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 — whether set here or by the
|
|
<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — 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"><intent-filter></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"><application></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 — whether set here or by the
|
|
<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — 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"><intent-filter></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"><manifest></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"><application></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"><application></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>
|