diff options
Diffstat (limited to 'docs/html/guide/topics/manifest/receiver-element.jd')
| -rw-r--r-- | docs/html/guide/topics/manifest/receiver-element.jd | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd new file mode 100644 index 0000000..777d016 --- /dev/null +++ b/docs/html/guide/topics/manifest/receiver-element.jd @@ -0,0 +1,164 @@ +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-filer></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> + +</dl> |