The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame^] | 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-filer></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 | </dl> |