1 page.title=<receiver> 2 parent.title=The AndroidManifest.xml File 3 parent.link=manifest-intro.html 4 @jd:body 5 6 <dl class="xml"> 7 <dt>syntax:</dt> 8 <dd><pre class="stx"><receiver android:<a href="#enabled">enabled</a>=["true" | "false"] 9 android:<a href="#exported">exported</a>=["true" | "false"] 10 android:<a href="#icon">icon</a>="<i>drawable resource</i>" 11 android:<a href="#label">label</a>="<i>string resource</i>" 12 android:<a href="#nm">name</a>="<i>string</i>" 13 android:<a href="#prmsn">permission</a>="<i>string</i>" 14 android:<a href="#proc">process</a>="<i>string</i>" > 15 . . . 16 </receiver></pre></dd> 17 18 <dt>contained in:</dt> 19 <dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> 20 21 <dt>can contain:</dt> 22 <dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 23 <br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> 24 25 <dt>description:</dt> 26 <dd itemprop="description">Declares a broadcast receiver (a {@link android.content.BroadcastReceiver} 27 subclass) as one of the application's components. Broadcast receivers enable 28 applications to receive intents that are broadcast by the system or by other 29 applications, even when other components of the application are not running. 30 31 <p> 32 There are two ways to make a broadcast receiver known to the system: One is 33 declare it in the manifest file with this element. The other is to create 34 the receiver dynamically in code and register it with the <code>{@link 35 android.content.Context#registerReceiver Context.registerReceiver()}</code> 36 method. See the {@link android.content.BroadcastReceiver} class description 37 for more on dynamically created receivers. 38 </p></dd> 39 40 <dt>attributes:</dt> 41 <dd><dl class="attr"> 42 <dt><a name="enabled"></a>{@code android:enabled}</dt> 43 <dd>Whether or not the broadcast receiver can be instantiated by the system — 44 "{@code true}" if it can be, and "{@code false}" if not. The default value 45 is "{@code true}". 46 47 <p> 48 The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own 49 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all 50 application components, including broadcast receivers. The 51 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and 52 {@code <receiver>} attributes must both be "{@code true}" for 53 the broadcast receiver to be enabled. If either is "{@code false}", it is 54 disabled; it cannot be instantiated. 55 </p></dd> 56 57 <dt><a name="exported"></a>{@code android:exported}</dt> 58 <dd>Whether or not the broadcast receiver can receive messages from sources 59 outside its application — "{@code true}" if it can, and "{@code false}" 60 if not. If "{@code false}", the only messages the broadcast receiver can 61 receive are those sent by components of the same application or applications 62 with the same user ID. 63 64 <p> 65 The default value depends on whether the broadcast receiver contains intent filters. 66 The absence of any filters means that it can be invoked only by Intent objects that 67 specify its exact class name. This implies that the receiver is intended only for 68 application-internal use (since others would not normally know the class name). 69 So in this case, the default value is "{@code false}". 70 On the other hand, the presence of at least one filter implies that the broadcast 71 receiver is intended to receive intents broadcast by the system or other applications, 72 so the default value is "{@code true}". 73 </p> 74 75 <p> 76 This attribute is not the only way to limit a broadcast receiver's external exposure. 77 You can also use a permission to limit the external entities that can send it messages 78 (see the <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html#prmsn">permission</a></code> attribute). 79 </p></dd> 80 81 <dt><a name="icon"></a>{@code android:icon}</dt> 82 <dd>An icon representing the broadcast receiver. This attribute must be set 83 as a reference to a drawable resource containing the image definition. 84 If it is not set, the icon specified for the application as a whole is used 85 instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 86 element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). 87 88 <p> 89 The broadcast receiver's icon — whether set here or by the 90 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the 91 default icon for all the receiver's intent filters (see the 92 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's 93 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). 94 </p></dd> 95 96 <dt><a name="label"></a>{@code android:label}</dt> 97 <dd>A user-readable label for the broadcast receiver. If this attribute is not 98 set, the label set for the application as a whole is 99 used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 100 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). 101 102 <p> 103 The broadcast receiver's label — whether set here or by the 104 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the 105 default label for all the receiver's intent filters (see the 106 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's 107 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). 108 </p> 109 110 <p> 111 The label should be set as a reference to a string resource, so that 112 it can be localized like other strings in the user interface. 113 However, as a convenience while you're developing the application, 114 it can also be set as a raw string. 115 </p></dd> 116 117 <dt><a name="nm"></a>{@code android:name}</dt> 118 <dd>The name of the class that implements the broadcast receiver, a subclass of 119 {@link android.content.BroadcastReceiver}. This should be a fully qualified 120 class name (such as, "{@code com.example.project.ReportReceiver}"). However, 121 as a shorthand, if the first character of the name is a period (for example, 122 "{@code . ReportReceiver}"), it is appended to the package name specified in 123 the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 124 125 <p>Once you publish your application, you <a 126 href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not 127 change this name</a> (unless you've set <code><a 128 href="#exported">android:exported</a>="false"</code>).</p> 129 130 <p> 131 There is no default. The name must be specified. 132 </p></dd> 133 134 <dt><a name="prmsn"></a>{@code android:permission}</dt> 135 <dd>The name of a permission that broadcasters must have to send a 136 message to the broadcast receiver. 137 If this attribute is not set, the permission set by the 138 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 139 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies 140 to the broadcast receiver. If neither attribute is set, the receiver 141 is not protected by a permission. 142 143 <p> 144 For more information on permissions, see the 145 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 146 section in the introduction and a separate document, 147 <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. 148 </p></dd> 149 150 <dt><a name="proc"></a>{@code android:process}</dt> 151 <dd>The name of the process in which the broadcast receiver should run. 152 Normally, all components of an application run in the default process created 153 for the application. It has the same name as the application package. The 154 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 155 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different 156 default for all components. But each component can override the default 157 with its own {@code process} attribute, allowing you to spread your 158 application across multiple processes. 159 160 <p> 161 If the name assigned to this attribute begins with a colon (':'), a new 162 process, private to the application, is created when it's needed and 163 the broadcast receiver runs in that process. 164 If the process name begins with a lowercase character, the receiver will run 165 in a global process of that name, provided that it has permission to do so. 166 This allows components in different applications to share a process, reducing 167 resource usage. 168 </p></dd> 169 </dl></dd> 170 171 <!-- ##api level indication## --> 172 <dt>introduced in:</dt> 173 <dd>API Level 1</dd> 174 175 </dl> 176
