android_manifest/receiver.rs
1use crate::VarOrBool;
2
3use super::intent_filter::IntentFilter;
4use super::meta_data::MetaData;
5use super::resources::{MipmapOrDrawableResource, StringResourceOrString};
6use serde::{Deserialize, Serialize};
7
8/// Declares a broadcast receiver (a [`BroadcastReceiver`] subclass) as one of the
9/// application's components.
10///
11/// Broadcast receivers enable applications to receive intents that are broadcast by the
12/// system or by other applications, even when other components of the application are not
13/// running.
14///
15/// There are two ways to make a broadcast receiver known to the system: One is declare it
16/// in the manifest file with this element. The other is to create the receiver
17/// dynamically in code and register it with the [`Context.registerReceiver()`]
18/// method. For more information about how to dynamically create receivers, see
19/// the [`BroadcastReceiver`] class description.
20///
21/// ## Warning
22/// Limit how many broadcast receivers you set in your app. Having too many broadcast
23/// receivers can affect your app's performance and the battery life of users' devices.
24/// For more information about APIs you can use instead of the BroadcastReceiver class for
25/// scheduling background work, see Background Optimizations.
26///
27/// ## XML Syntax
28/// ```xml
29/// <receiver android:directBootAware=["true" | "false"]
30/// android:enabled=["true" | "false"]
31/// android:exported=["true" | "false"]
32/// android:icon="drawable resource"
33/// android:label="string resource"
34/// android:name="string"
35/// android:permission="string"
36/// android:process="string" >
37/// ...
38/// </receiver>
39/// ```
40///
41/// ## Contained in
42/// * [`<application>`]
43///
44/// ## Can contain
45/// * [`<intent-filter>`]
46/// * [`<meta-data>`]
47///
48/// ## Introduced in
49/// API Level 1
50///
51/// [`BroadcastReceiver`]: https://developer.android.com/reference/android/content/BroadcastReceiver
52/// [`Context.registerReceiver()`]: https://developer.android.com/reference/android/content/Context#registerReceiver(android.content.BroadcastReceiver,%20android.content.IntentFilter)
53/// [`<application>`]: crate::Application
54/// [`<intent-filter>`]: crate::IntentFilter
55/// [`<meta-data>`]: crate::MetaData
56#[derive(
57 Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Default, Clone,
58)]
59pub struct Receiver {
60 /// Whether or not the broadcast `receiver` is direct-boot aware; that is,
61 /// whether or not it can run before the user unlocks the device.
62 ///
63 /// ## Note
64 /// During [`Direct Boot`], a broadcast `receiver` in your application
65 /// can only access the data that is stored in device protected storage.
66 ///
67 /// The default value is "false".
68 ///
69 /// [`Direct Boot`]: https://developer.android.com/training/articles/direct-boot
70 #[yaserde(attribute, prefix = "android", rename = "directBootAware")]
71 pub direct_boot_aware: Option<VarOrBool>,
72 /// Whether or not the broadcast receiver can be instantiated by the system — `"true"`
73 /// if it can be, and `"false"` if not. The default value is `"true"`.
74 ///
75 /// The [`<application>`] element has its own [`enabled`] attribute that applies to
76 /// all application components, including broadcast receivers. The
77 /// [`<application>`] and <receiver> attributes must both be `"true"` for the
78 /// broadcast receiver to be enabled. If either is `"false`", it is disabled; it
79 /// cannot be instantiated.
80 ///
81 /// [`<application>`]: crate::Application
82 /// [`enabled`]: crate::Application#structfield.enabled
83 #[yaserde(attribute, prefix = "android")]
84 pub enabled: Option<VarOrBool>,
85 /// Whether the broadcast receiver can receive messages from non-system sources
86 /// outside its application — `"true"` if it can, and `"false"` if
87 /// not. If `"false"`, the only messages the broadcast receiver can
88 /// receive are those sent by the system, components of the same
89 /// application, or applications with the same user ID.
90 ///
91 /// If unspecified, the default value depends on whether the broadcast receiver
92 /// contains intent filters. If the receiver contains at least one intent filter,
93 /// then the default value is `"true"` Otherwise, the default value is
94 /// `"false"`.
95 ///
96 /// This attribute is not the only way to limit a broadcast receiver's external
97 /// exposure. You can also use a permission to limit the external entities that
98 /// can send it messages (see the [`permission`] attribute).
99 ///
100 /// [`permission`]: crate::Receiver#structfield.permission
101 #[yaserde(attribute, prefix = "android")]
102 pub exported: Option<VarOrBool>,
103 /// An icon representing the service. This attribute must be set as a reference to a
104 /// drawable resource containing the image definition. If it is not set, the icon
105 /// specified for the application as a whole is used instead (see the
106 /// [`<application>`] element's [`icon`](crate::Application#structfield.icon)
107 /// attribute).
108 ///
109 /// The service's icon — whether set here or by the [`<application>`]
110 /// element — is also the default icon for all the service's intent filters (see
111 /// the [`<intent-filter>`] element's [`icon`](crate::IntentFilter#structfield.icon)
112 /// attribute).
113 ///
114 /// [`<application>`]: crate::Application
115 /// [`<intent-filter>`]: crate::IntentFilter
116 #[yaserde(attribute, prefix = "android")]
117 pub icon: Option<MipmapOrDrawableResource>,
118 /// A name for the service that can be displayed to users. If this attribute is not
119 /// set, the label set for the application as a whole is used instead
120 /// (see the [`<application>`] element's
121 /// [`label`](crate::Application#structfield.label) attribute).
122 ///
123 /// The service's label — whether set here or by the [`<application>`] element — is
124 /// also the default label for all the service's intent filters (see the
125 /// [`<intent-filter>`] element's [`label`](crate::IntentFilter#structfield.label)
126 /// attribute).
127 ///
128 /// The label should be set as a reference to a string resource, so that it can be
129 /// localized like other strings in the user interface. However, as a convenience
130 /// while you're developing the application, it can also be set as a raw string.
131 ///
132 /// [`<application>`]: crate::Application
133 /// [`<intent-filter>`]: crate::IntentFilter
134 #[yaserde(attribute, prefix = "android")]
135 pub label: Option<StringResourceOrString>,
136 /// The name of the class that implements the broadcast receiver, a subclass of
137 /// [`BroadcastReceiver`]. This should be a fully qualified class name (such as,
138 /// `"com.example.project.ReportReceiver"`). However, as a shorthand, if the first
139 /// character of the name is a period (for example, "`. ReportReceiver`"), it is
140 /// appended to the package name specified in the [`<manifest>`] element.
141 ///
142 /// Once you publish your application, you [`should not change this name`] (unless
143 /// you've set [`android:exported="false"`]).
144 ///
145 /// There is no default. The name must be specified.
146 ///
147 /// [`BroadcastReceiver`]: https://developer.android.com/reference/android/content/BroadcastReceiver
148 /// [`<manifest>`]: crate::AndroidManifest
149 /// [`should not change this name`]: https://android-developers.googleblog.com/2011/06/things-that-cannot-change.html
150 /// [`android:exported="false"`]: crate::Receiver#structfield.exported
151 #[yaserde(attribute, prefix = "android")]
152 pub name: String,
153 /// The name of a permission that broadcasters must have to send a message to the
154 /// broadcast receiver. If this attribute is not set, the permission set by the
155 /// [`<application>`] element's [`permission`] attribute applies to the broadcast
156 /// receiver. If neither attribute is set, the receiver is not protected by a
157 /// permission.
158 ///
159 /// For more information on permissions, see the [`Permissions`] section in the
160 /// introduction and a separate document, [`Security and Permissions`].
161 ///
162 /// [`<application>`]: crate::Application
163 /// [`permission`]: crate::Application#structfield.permission
164 /// [`Permissions`]: https://developer.android.com/guide/topics/manifest/manifest-intro#perms
165 /// [`Security and Permissions`]: https://developer.android.com/training/articles/security-tipss
166 #[yaserde(attribute, prefix = "android")]
167 pub permission: Option<String>,
168 /// The name of the process where the service is to run. Normally, all components of
169 /// an application run in the default process created for the application. It has
170 /// the same name as the application package. The [`<application>`] element's
171 /// [`process`] attribute can set a different default for all components. But
172 /// component can override the default with its own process attribute, allowing
173 /// you to spread your application across multiple processes.
174 ///
175 /// If the name assigned to this attribute begins with a colon `(':')`, a new process,
176 /// private to the application, is created when it's needed and the service runs
177 /// in that process. If the process name begins with a lowercase character, the
178 /// service will run in a global process of that name, provided that it has
179 /// permission to do so. This allows components in different applications to share
180 /// a process, reducing resource usage.
181 ///
182 /// [`<application>`]: crate::Application
183 /// [`process`]: crate::Application#structfield.process
184 #[yaserde(attribute, prefix = "android")]
185 pub process: Option<String>,
186 #[serde(
187 rename = "intent-filter",
188 skip_serializing_if = "Vec::is_empty",
189 default
190 )]
191 #[yaserde(rename = "intent-filter")]
192 pub intent_filter: Vec<IntentFilter>,
193 #[serde(rename = "meta-data", skip_serializing_if = "Vec::is_empty", default)]
194 #[yaserde(rename = "meta-data")]
195 pub meta_data: Vec<MetaData>,
196}