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