android_manifest/data.rs
1use serde::{Deserialize, Serialize};
2
3/// Adds a data specification to an intent filter.
4///
5/// The specification can be just a data type (the mimeType attribute),
6/// just a URI, or both a data type and a URI. A URI is specified
7/// by separate attributes for each of its parts:
8///
9/// ```xml
10/// <scheme>://<host>:<port>[<path>|<pathPrefix>|<pathPattern>]
11/// ```
12///
13/// ## XML Examples
14/// These attributes that specify the URL format are optional, but also mutually
15/// dependent:
16/// * If a [`scheme`] is not specified for the intent filter, all the other URI attributes
17/// are ignored.
18/// * If a [`host`] is not specified for the filter, the port attribute and all the path
19/// attributes are ignored.
20///
21/// All the `<data>` elements contained within the same [`<intent-filter>`]
22/// element contribute to the same filter. So, for example, the following filter
23/// specification,
24///
25/// ```xml
26/// <intent-filter ...>
27/// <data android:scheme="something" android:host="project.example.com" />
28/// ...
29/// </intent-filter>
30/// ```
31///
32/// is equivalent to this one:
33///
34/// ```xml
35/// <intent-filter ...>
36/// <data android:scheme="something" />
37/// <data android:host="project.example.com" />
38/// ...
39/// </intent-filter>
40/// ```
41///
42/// You can place any number of <data> elements inside an [`<intent-filter>`] to
43/// give it multiple data options. None of its attributes have default values.
44///
45/// Information on how intent filters work, including the rules for how Intent objects are
46/// matched against filters, can be found in another document, [`Intents and Intent
47/// Filters`]. See also the [`Intent Filters`] section in the manifest file overview.
48///
49/// ## XML Syntax
50/// ```xml
51/// <data android:scheme="string"
52/// android:host="string"
53/// android:port="string"
54/// android:path="string"
55/// android:pathPattern="string"
56/// android:pathPrefix="string"
57/// android:mimeType="string" />
58/// ```
59///
60/// ## Contained in
61/// * [`<intent-filter>`]
62///
63/// ## Introduced in
64/// API Level 1
65///
66/// [`scheme`]: crate::Data#structfield.scheme
67/// [`host`]: crate::Data#structfield.host
68/// [`<intent-filter>`]: crate::IntentFilter
69/// [`Intents and Intent Filters`]: https://developer.android.com/guide/components/intents-filters
70/// [`Intent Filters`]: https://developer.android.com/guide/topics/manifest/manifest-intro#ifs
71#[derive(
72 Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Default, Clone,
73)]
74pub struct Data {
75 /// The scheme part of a URI. This is the minimal essential attribute for specifying a
76 /// URI; at least one scheme attribute must be set for the filter, or none of the
77 /// other URI attributes are meaningful.
78 ///
79 /// A scheme is specified without the trailing colon (for example, http, rather than
80 /// http:).
81 ///
82 /// If the filter has a data type set (the [`mimeType`] attribute) but no scheme, the
83 /// `content:` and `file:` schemes are assumed.
84 ///
85 /// ## Note
86 /// Scheme matching in the Android framework is case-sensitive, unlike the RFC. As a
87 /// result, you should always specify schemes using lowercase letters.
88 ///
89 /// [`mimeType`]: crate::Data#structfield.mime_type
90 #[yaserde(attribute, prefix = "android")]
91 pub scheme: Option<String>,
92 /// The host part of a URI authority. This attribute is meaningless unless a
93 /// [`scheme`] attribute is also specified for the filter. To match multiple
94 /// subdomains, use an asterisk (*) to match zero or more characters in the
95 /// host. For example, the host `*.google.com` matches `www.google.com`,
96 /// `.google.com`, and `developer.google.com.`
97 ///
98 /// The asterisk must be the first character of the host attribute. For example, the
99 /// host `google.co.` is invalid because the asterisk wildcard is not the first
100 /// character.
101 ///
102 /// ## Note
103 /// host name matching in the Android framework is case-sensitive,
104 /// unlike the formal RFC. As a result, you should always specify host names
105 /// using lowercase letters.
106 ///
107 /// [`scheme`]: crate::Data#structfield.scheme
108 #[yaserde(attribute, prefix = "android")]
109 pub host: Option<String>,
110 /// The port part of a URI authority. This attribute is meaningful only if the
111 /// [`scheme`] and [`host`] attributes are also specified for the filter.
112 ///
113 /// [`scheme`]: crate::Data#structfield.scheme
114 /// [`host`]: crate::Data#structfield.host
115 #[yaserde(attribute, prefix = "android")]
116 pub port: Option<String>,
117 /// The path part of a URI which must begin with a /. The path attribute specifies a
118 /// complete path that is matched against the complete path in an Intent object.
119 /// The `pathPrefix` attribute specifies a partial path that is matched against
120 /// only the initial part of the path in the Intent object. The pathPattern
121 /// attribute specifies a complete path that is matched against the complete path
122 /// in the Intent object, but it can contain the following wildcards:
123 ///
124 /// * An asterisk `('*')` matches a sequence of 0 to many occurrences of the
125 /// immediately preceding character.
126 /// * A period followed by an asterisk `(".*")` matches any sequence of 0 to many
127 /// characters.
128 ///
129 /// Because `'\'` is used as an escape character when the string is read from XML
130 /// (before it is parsed as a pattern) , you will need to double-escape: For
131 /// example, a literal `'*'` would be written as `"\\*"` and a literal `'\'` would
132 /// be written as `"\\\\"`. This is basically the same as what you would need to
133 /// write if constructing the string in Java code.
134 ///
135 /// For more information on these three types of patterns, see the descriptions of
136 /// [`PATTERN_LITERAL`], [`PATTERN_PREFIX`], and [`PATTERN_SIMPLE_GLOB`] in the
137 /// [`PatsternMatcher`] class.
138 ///
139 /// These attributes are meaningful only if the [`scheme`] and [`host`] attributes are
140 /// also specified for the filter.
141 ///
142 /// [`PATTERN_LITERAL`]: https://developer.android.com/reference/android/os/PatternMatcher#PATTERN_LITERAL
143 /// [`PATTERN_PREFIX`]: https://developer.android.com/reference/android/os/PatternMatcher#PATTERN_PREFIX
144 /// [`PATTERN_SIMPLE_GLOB`]: https://developer.android.com/reference/android/os/PatternMatcher#PATTERN_SIMPLE_GLOB
145 /// [`PatsternMatcher`]: https://developer.android.com/reference/android/os/PatternMatcher
146 /// [`scheme`]: crate::Data#structfield.scheme
147 /// [`host`]: crate::Data#structfield.host
148 #[yaserde(attribute, prefix = "android")]
149 pub path: Option<String>,
150 #[yaserde(attribute, prefix = "android", rename = "pathPattern")]
151 pub path_pattern: Option<String>,
152 #[yaserde(attribute, prefix = "android", rename = "pathPrefix")]
153 pub path_prefix: Option<String>,
154 /// A MIME media type, such as `image/jpeg` or `audio/mpeg4-generic`. The
155 /// subtype can be the asterisk wildcard (*) to indicate that any subtype
156 /// matches.
157 ///
158 /// It's common for an intent filter to declare a `<data>` that includes only the
159 /// android:mimeType attribute.
160 ///
161 /// ## Note
162 /// MIME type matching in the Android framework is case-sensitive,
163 /// unlike formal RFC MIME types. As a result, you should always specify
164 /// MIME types using lowercase letters.
165 #[yaserde(attribute, prefix = "android", rename = "mimeType")]
166 pub mime_type: Option<String>,
167}