docs/html/guide/topics/manifest/receiver-element.jd

page.title=<receiver>
@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;} elements must both set {@code android:enabled} equal to
"{@code true}" for the broadcast receiver to be enabled.  If either is "{@code false}",
the receiver is disabled and cannot be instantiated.
</p>

<p>
The default value depends on whether the broadcast receiver contains intent filters.
If any intent filters are specified, the default value is "{@code true}".  If no
filters are specified, the default value is "{@code false}".
</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>The {@link android.content.BroadcastReceiver} subclass can be a static inner
class, although it cannot be an ordinary (non-static) inner class.

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

</dl>