android_manifest/uses_feature.rs
1use serde::{Deserialize, Serialize};
2
3use crate::VarOrBool;
4
5/// Declares a single hardware or software feature that is used by the
6/// application.
7///
8/// The purpose of a <uses-feature> declaration is to inform any external entity
9/// of the set of hardware and software features on which your application
10/// depends. The element offers a required attribute that lets you specify
11/// whether your application requires and cannot function without the declared
12/// feature, or whether it prefers to have the feature but can function without
13/// it. Because feature support can vary across Android devices, the
14/// <uses-feature> element serves an important role in letting an application
15/// describe the device-variable features that it uses.
16
17/// The set of available features that your application declares corresponds to
18/// the set of feature constants made available by the Android [`PackageManager`],
19/// which are listed for convenience in the [`Features Reference`] sections at the
20/// bottom of this document.
21
22/// You must specify each feature in a separate `<uses-feature>` element, so if
23/// your application requires multiple features, it would declare multiple
24/// `<uses-feature>` elements. For example, an application that requires both
25///
26/// Bluetooth and camera features in the device would declare these two
27/// elements:
28///
29/// ```xml
30/// <uses-feature android:name="android.hardware.bluetooth" />
31/// <uses-feature android:name="android.hardware.camera" />
32/// ```
33/// In general, you should always make sure to declare `<uses-feature>` elements
34/// for all of the features that your application requires.
35
36/// Declared `<uses-feature>` elements are informational only, meaning that the
37/// Android system itself does not check for matching feature support on the
38/// device before installing an application. However, other services (such as
39/// Google Play) or applications may check your application's `<uses-feature>`
40/// declarations as part of handling or interacting with your application. For
41/// this reason, it's very important that you declare all of the features (from
42/// the list below) that your application uses.
43
44/// For some features, there may exist a specific attribute that allows you to
45/// define a version of the feature, such as the version of Open GL used
46/// (declared with [`glEsVersion`]). Other features that either do or do not exist
47/// for a device, such as a camera, are declared using the [`name`] attribute.
48
49/// Although the <uses-feature> element is only activated for devices running
50/// API Level 4 or higher, it is recommended to include these elements for all
51/// applications, even if the [`minSdkVersion`] is "3" or lower. Devices running
52/// older versions of the platform will simply ignore the element.
53///
54/// ## Note
55/// When declaring a feature, remember that you must also request permissions as
56/// appropriate. For example, you must still request the [`CAMERA`] permission
57/// before your application can access the camera API. Requesting the permission
58/// grants your application access to the appropriate hardware and software,
59/// while declaring the features used by your application ensures proper device
60/// compatibility.
61///
62/// ## Important
63/// Google Play uses the <uses-feature> elements declared in your app manifest to filter
64/// your app from devices that do not meet its hardware and software feature requirements.
65///
66/// By specifying the features that your application requires, you enable Google Play to
67/// present your application only to users whose devices meet the application's feature
68/// requirements, rather than presenting it to all users.s
69///
70/// For important information about how Google Play uses features as the basis for
71/// filtering, please read [`Google Play and Feature-Based Filtering`], below.
72///
73/// ## XML Syntax
74/// ```xml
75/// <uses-feature android:name="string"
76/// android:required=["true" | "false"]
77/// android:glEsVersion="integer" />
78/// ```
79///
80/// ## Contained in
81/// * [`<manifest>`]
82///
83/// ## Introduced in
84/// API Level 4
85///
86/// [`PackageManager`]: https://developer.android.com/reference/android/content/pm/PackageManagers
87/// [`Features Reference`]: https://developer.android.com/guide/topics/manifest/uses-feature-element#features-reference
88/// [`glEsVersion`]: crate::UsesFeature#structfield.gl_es_version
89/// [`name`]: crate::UsesFeature#structfield.name
90/// [`CAMERA`]: https://developer.android.com/reference/android/Manifest.permission#CAMERA
91/// [`minSdkVersion`]: crate::UsesSdk#structfield.min_sdk_version
92/// [`Google Play and Feature-Based Filtering`]: https://developer.android.com/guide/topics/manifest/uses-feature-element#market-feature-filtering
93/// [`<manifest>`]: crate::AndroidManifest
94#[derive(
95 Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Default, Clone,
96)]
97pub struct UsesFeature {
98 /// Specifies a single hardware or software feature used by the application,
99 /// as a descriptor string. Valid attribute values are listed in the
100 /// [`Hardware features`] and [`Software features`] sections. These attribute
101 /// values are case-sensitive.
102 ///
103 /// [`Hardware features`]: https://developer.android.com/guide/topics/manifest/uses-feature-element#hw-features
104 /// [`Software features`]: https://developer.android.com/guide/topics/manifest/uses-feature-element#sw-features
105 #[yaserde(attribute, prefix = "android")]
106 pub name: Option<String>,
107 /// Boolean value that indicates whether the application requires the feature
108 /// specified in `android:name`.
109 ///
110 /// * When you declare `android:required="true"` for a feature, you are specifying
111 /// that the
112 /// application cannot function, or is not designed to function, when the
113 /// specified feature is not present on the device.
114 /// * When you declare `android:required="false"` for a feature, it means that the
115 /// application
116 /// prefers to use the feature if present on the device, but that it is designed to
117 /// function without the specified feature, if necessary.
118 ///
119 /// The default value for android:required if not declared is `"true"`.
120 #[yaserde(attribute, prefix = "android")]
121 pub required: Option<VarOrBool>,
122 /// The OpenGL ES version required by the application. The higher 16 bits represent
123 /// the major number and the lower 16 bits represent the minor number. For
124 /// example, to specify OpenGL ES version 2.0, you would set the value as
125 /// "0x00020000", or to specify OpenGL ES 3.2, you would set the value as
126 /// "0x00030002". An application should specify at most one `android:glEsVersion`
127 /// attribute in its manifest. If it specifies more than one, the android:
128 /// glEsVersion` with the numerically highest value is used and any other values
129 /// are ignored.
130 ///
131 /// If an application does not specify an android:glEsVersion
132 /// attribute, then it is assumed that the application requires only OpenGL ES
133 /// 1.0, which is supported by all Android-powered devices.
134 ///
135 /// An application can assume that if a platform supports a given OpenGL ES version,
136 /// it also supports all numerically lower OpenGL ES versions. Therefore, an
137 /// application that requires both OpenGL ES 1.0 and OpenGL ES 2.0 must specify
138 /// that it requires OpenGL ES 2.0.
139 ///
140 /// An application that can work with any of several OpenGL ES versions should only
141 /// specify the numerically lowest version of OpenGL ES that it requires.
142 ///
143 /// For more information about using OpenGL ES, including how to check the
144 /// supported OpenGL ES version at runtime, see the [`OpenGL ES API guide`].
145 ///
146 /// [`OpenGL ES API guide`]: https://developer.android.com/guide/topics/graphics/opengl
147 #[yaserde(attribute, prefix = "android", rename = "glEsVersion")]
148 pub gl_es_version: Option<String>,
149}