android_manifest/uses_sdk.rs
1use serde::{Deserialize, Serialize};
2
3/// Lets you express an application's compatibility with one or more versions of the
4/// Android platform, by means of an API Level integer.
5///
6/// The API Level expressed by an application will be compared to the API Level of a given
7/// Android system, which may vary among different Android devices.
8/// Despite its name, this element is used to specify the API Level, not the version
9/// number of the SDK (software development kit) or Android platform. The API Level is
10/// always a single integer. You cannot derive the API Level from its associated Android
11/// version number (for example, it is not the same as the major version or the sum of the
12/// major and minor versions). [`Versioning Your Applications.`]
13///
14/// ## Note
15/// Google Play uses the <uses-sdk> attributes declared in your app manifest to filter
16/// your app from devices that do not meet its platform version requirements. Before
17/// setting these attributes, make sure that you understand [`Google Play filters`].
18///
19/// ## XML Syntax
20/// ```xml
21/// <uses-sdk android:minSdkVersion="integer"
22/// android:targetSdkVersion="integer"
23/// android:maxSdkVersion="integer" />
24/// ```
25///
26/// ## Contained in
27/// [`<manifest>`]
28///
29/// ## introduced in
30/// API Level 1
31///
32/// [`Versioning Your Applications.`]: https://developer.android.com/studio/publish/versioning
33/// [`Google Play filters`]: https://developer.android.com/google/play/filters
34/// [`<manifest>`]: crate::AndroidManifest
35#[derive(
36 Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Default, Clone,
37)]
38pub struct UsesSdk {
39 /// An integer designating the minimum API Level required for the application to run.
40 /// The Android system will prevent the user from installing the application if
41 /// the system's API Level is lower than the value specified in this attribute.
42 /// You should always declare this attribute.
43 ///
44 /// ## Caution
45 /// If you do not declare this attribute, the system assumes a default value of "1",
46 /// which indicates that your application is compatible with all versions of
47 /// Android. If your application is not compatible with all versions (for
48 /// instance, it uses APIs introduced in API Level 3) and you have not declared
49 /// the proper `minSdkVersion`, then when installed on a system with an API Level
50 /// less than 3, the application will crash during runtime when attempting to
51 /// access the unavailable APIs. For this reason, be certain to declare the
52 /// appropriate API Level in the `minSdkVersion` attribute.
53 #[yaserde(attribute, prefix = "android", rename = "minSdkVersion")]
54 pub min_sdk_version: Option<u32>,
55 /// An integer designating the API Level that the application targets. If not set, the
56 /// default value equals that given to `minSdkVersion`. This attribute informs the
57 /// system that you have tested against the target version and the system should
58 /// not enable any compatibility behaviors to maintain your app's
59 /// forward-compatibility with the target version. The application is still able
60 /// to run on older versions (down to minSdkVersion). As Android evolves with each
61 /// new version, some behaviors and even appearances might change. However, if the
62 /// API level of the platform is higher than the version declared by your app's
63 /// targetSdkVersion the system may enable compatibility behaviors to
64 /// ensure that your app continues to work the way you expect.You can
65 /// disable such compatibility behaviors by specifying targetSdkVersion
66 /// to match the API level of the platform on which it's running. For
67 /// example, setting this value to "11" or higher allows the system to apply
68 /// a new default theme (Holo) to your app when running on Android 3.0
69 /// or higher and also disables [`screen compatibility mode`] when running on
70 /// larger screens (because support for API level 11 implicitly supports
71 /// larger screens).
72 ///
73 /// There are many compatibility behaviors that the system may enable based on the
74 /// value you set for this attribute. Several of these behaviors are described by
75 /// the corresponding platform versions in the [`Build.VERSION_CODES`] reference.
76 ///
77 /// To maintain your application along with each Android release, you should increase
78 /// the value of this attribute to match the latest API level, then thoroughly
79 /// test your application on the corresponding platform version.
80 ///
81 /// Introduced in: API Level 4
82 ///
83 /// [`screen compatibility mode`]: https://developer.android.com/guide/topics/manifest/supports-screens-element#compat-mode
84 /// [`Build.VERSION_CODES`]: https://developer.android.com/reference/android/os/Build.VERSION_CODES
85 #[yaserde(attribute, prefix = "android", rename = "targetSdkVersion")]
86 pub target_sdk_version: Option<u32>,
87 /// An integer designating the maximum API Level on which the application is designed
88 /// to run. In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of
89 /// this attribute when installing an application and when re-validating the
90 /// application after a system update. In either case, if the application's
91 /// maxSdkVersion attribute is lower than the API Level used by the system itself,
92 /// then the system will not allow the application to be installed. In the case of
93 /// re-validation after system update, this effectively removes your application
94 /// from the device.
95 ///
96 /// To illustrate how this attribute can affect your application
97 /// after system updates, consider the following example:
98 ///
99 /// An application declaring maxSdkVersion="5" in its manifest is published on Google
100 /// Play. A user whose device is running Android 1.6 (API Level 4) downloads and
101 /// installs the app. After a few weeks, the user receives an
102 /// over-the-air system update to Android 2.0 (API Level 5). After the
103 /// update is installed, the system checks the application's maxSdkVersion
104 /// and successfully re-validates it. The application functions as
105 /// normal. However, some time later, the device receives another system
106 /// update, this time to Android 2.0.1 (API Level 6). After the update, the
107 /// system can no longer re-validate the application because the system's
108 /// own API Level (6) is now higher than the maximum supported by the
109 /// application (5). The system prevents the application from being
110 /// visible to the user, in effect removing it from the device.
111 ///
112 /// ## Warning
113 /// Declaring this attribute is not recommended. First, there is no need to set the
114 /// attribute as means of blocking deployment of your application onto new
115 /// versions of the Android platform as they are released. By design, new versions
116 /// of the platform are fully backward-compatible. Your application should work
117 /// properly on new versions, provided it uses only standard APIs and follows
118 /// development best practices. Second, note that in some cases, declaring
119 /// the attribute can result in your application being removed from users'
120 /// devices after a system update to a higher API Level. Most devices on
121 /// which your application is likely to be installed will receive periodic
122 /// system updates over the air, so you should consider their effect on your
123 /// application before setting this attribute.
124 ///
125 /// Introduced in: API Level 4
126 ///
127 /// ## Important
128 /// Future versions of Android (beyond Android 2.0.1) will no longer check or enforce
129 /// the `maxSdkVersion` attribute during installation or re-validation. Google Play
130 /// will continue to use the attribute as a filter, however, when presenting users
131 /// with applications available for download.
132 #[yaserde(attribute, prefix = "android", rename = "maxSdkVersion")]
133 pub max_sdk_version: Option<u32>,
134}