1//! A crate parsing common XMPP elements into Rust structures.
2//!
3//! Each module implements the [`TryFrom<Element>`] trait, which takes a
4//! minidom [`Element`] and returns a `Result` whose value is `Ok` if the
5//! element parsed correctly, `Err(error::Error)` otherwise.
6//!
7//! The returned structure can be manipuled as any Rust structure, with each
8//! field being public. You can also create the same structure manually, with
9//! some having `new()` and `with_*()` helper methods to create them.
10//!
11//! Once you are happy with your structure, you can serialise it back to an
12//! [`Element`], using either `From` or `Into<Element>`, which give you what
13//! you want to be sending on the wire.
14//!
15//! [`TryFrom<Element>`]: ../try_from/trait.TryFrom.html
16//! [`Element`]: ../minidom/element/struct.Element.html
17
18// Copyright (c) 2017 Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
19// Copyright (c) 2017 Maxime “pep” Buquet <pep+code@bouah.net>
20//
21// This Source Code Form is subject to the terms of the Mozilla Public
22// License, v. 2.0. If a copy of the MPL was not distributed with this
23// file, You can obtain one at http://mozilla.org/MPL/2.0/.
24
25extern crate minidom;
26extern crate jid;
27extern crate base64;
28extern crate digest;
29extern crate sha_1;
30extern crate sha2;
31extern crate sha3;
32extern crate blake2;
33extern crate chrono;
34extern crate try_from;
35
36macro_rules! get_attr {
37 ($elem:ident, $attr:tt, $type:tt) => (
38 get_attr!($elem, $attr, $type, value, value.parse()?)
39 );
40 ($elem:ident, $attr:tt, optional, $value:ident, $func:expr) => (
41 match $elem.attr($attr) {
42 Some($value) => Some($func),
43 None => None,
44 }
45 );
46 ($elem:ident, $attr:tt, required, $value:ident, $func:expr) => (
47 match $elem.attr($attr) {
48 Some($value) => $func,
49 None => return Err(Error::ParseError(concat!("Required attribute '", $attr, "' missing."))),
50 }
51 );
52 ($elem:ident, $attr:tt, default, $value:ident, $func:expr) => (
53 match $elem.attr($attr) {
54 Some($value) => $func,
55 None => Default::default(),
56 }
57 );
58}
59
60macro_rules! generate_attribute {
61 ($elem:ident, $name:tt, {$($a:ident => $b:tt),+,}) => (
62 generate_attribute!($elem, $name, {$($a => $b),+});
63 );
64 ($elem:ident, $name:tt, {$($a:ident => $b:tt),+,}, Default = $default:ident) => (
65 generate_attribute!($elem, $name, {$($a => $b),+}, Default = $default);
66 );
67 ($elem:ident, $name:tt, {$($a:ident => $b:tt),+}) => (
68 #[derive(Debug, Clone, PartialEq)]
69 pub enum $elem {
70 $(
71 #[doc=$b]
72 #[doc="value for this attribute."]
73 $a
74 ),+
75 }
76 impl FromStr for $elem {
77 type Err = Error;
78 fn from_str(s: &str) -> Result<$elem, Error> {
79 Ok(match s {
80 $($b => $elem::$a),+,
81 _ => return Err(Error::ParseError(concat!("Unknown value for '", $name, "' attribute."))),
82 })
83 }
84 }
85 impl IntoAttributeValue for $elem {
86 fn into_attribute_value(self) -> Option<String> {
87 Some(String::from(match self {
88 $($elem::$a => $b),+
89 }))
90 }
91 }
92 );
93 ($elem:ident, $name:tt, {$($a:ident => $b:tt),+}, Default = $default:ident) => (
94 #[derive(Debug, Clone, PartialEq)]
95 pub enum $elem {
96 $(
97 #[doc=$b]
98 #[doc="value for this attribute."]
99 $a
100 ),+
101 }
102 impl FromStr for $elem {
103 type Err = Error;
104 fn from_str(s: &str) -> Result<$elem, Error> {
105 Ok(match s {
106 $($b => $elem::$a),+,
107 _ => return Err(Error::ParseError(concat!("Unknown value for '", $name, "' attribute."))),
108 })
109 }
110 }
111 impl IntoAttributeValue for $elem {
112 #[allow(unreachable_patterns)]
113 fn into_attribute_value(self) -> Option<String> {
114 Some(String::from(match self {
115 $elem::$default => return None,
116 $($elem::$a => $b),+
117 }))
118 }
119 }
120 impl Default for $elem {
121 fn default() -> $elem {
122 $elem::$default
123 }
124 }
125 );
126}
127
128macro_rules! check_self {
129 ($elem:ident, $name:tt, $ns:expr) => (
130 if !$elem.is($name, $ns) {
131 return Err(Error::ParseError(concat!("This is not a ", $name, " element.")));
132 }
133 );
134 ($elem:ident, $name:tt, $ns:expr, $pretty_name:tt) => (
135 if !$elem.is($name, $ns) {
136 return Err(Error::ParseError(concat!("This is not a ", $pretty_name, " element.")));
137 }
138 );
139}
140
141macro_rules! check_ns_only {
142 ($elem:ident, $name:tt, $ns:expr) => (
143 if !$elem.has_ns($ns) {
144 return Err(Error::ParseError(concat!("This is not a ", $name, " element.")));
145 }
146 );
147}
148
149macro_rules! check_no_children {
150 ($elem:ident, $name:tt) => (
151 for _ in $elem.children() {
152 return Err(Error::ParseError(concat!("Unknown child in ", $name, " element.")));
153 }
154 );
155}
156
157macro_rules! check_no_attributes {
158 ($elem:ident, $name:tt) => (
159 check_no_unknown_attributes!($elem, $name, []);
160 );
161}
162
163macro_rules! check_no_unknown_attributes {
164 ($elem:ident, $name:tt, [$($attr:tt),*]) => (
165 for (_attr, _) in $elem.attrs() {
166 $(
167 if _attr == $attr {
168 continue;
169 }
170 )*
171 return Err(Error::ParseError(concat!("Unknown attribute in ", $name, " element.")));
172 }
173 );
174}
175
176macro_rules! generate_empty_element {
177 ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:expr) => (
178 $(#[$meta])*
179 #[derive(Debug, Clone)]
180 pub struct $elem;
181
182 impl TryFrom<Element> for $elem {
183 type Err = Error;
184
185 fn try_from(elem: Element) -> Result<$elem, Error> {
186 check_self!(elem, $name, $ns);
187 check_no_children!(elem, $name);
188 check_no_attributes!(elem, $name);
189 Ok($elem)
190 }
191 }
192
193 impl From<$elem> for Element {
194 fn from(_: $elem) -> Element {
195 Element::builder($name)
196 .ns($ns)
197 .build()
198 }
199 }
200 );
201}
202
203macro_rules! generate_element_with_only_attributes {
204 ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:expr, [$($(#[$attr_meta:meta])* $attr:ident: $attr_type:ty = $attr_name:tt => $attr_action:tt),+,]) => (
205 generate_element_with_only_attributes!($(#[$meta])* $elem, $name, $ns, [$($(#[$attr_meta])* $attr: $attr_type = $attr_name => $attr_action),*]);
206 );
207 ($(#[$meta:meta])* $elem:ident, $name:tt, $ns:expr, [$($(#[$attr_meta:meta])* $attr:ident: $attr_type:ty = $attr_name:tt => $attr_action:tt),+]) => (
208 $(#[$meta])*
209 #[derive(Debug, Clone)]
210 pub struct $elem {
211 $(
212 $(#[$attr_meta])*
213 pub $attr: $attr_type
214 ),*
215 }
216
217 impl TryFrom<Element> for $elem {
218 type Err = Error;
219
220 fn try_from(elem: Element) -> Result<$elem, Error> {
221 check_self!(elem, $name, $ns);
222 check_no_children!(elem, $name);
223 check_no_unknown_attributes!(elem, $name, [$($attr_name),*]);
224 Ok($elem {
225 $(
226 $attr: get_attr!(elem, $attr_name, $attr_action)
227 ),*
228 })
229 }
230 }
231
232 impl From<$elem> for Element {
233 fn from(elem: $elem) -> Element {
234 Element::builder($name)
235 .ns($ns)
236 $(
237 .attr($attr_name, elem.$attr)
238 )*
239 .build()
240 }
241 }
242 );
243}
244
245macro_rules! generate_id {
246 ($elem:ident) => (
247 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
248 pub struct $elem(pub String);
249 impl FromStr for $elem {
250 type Err = Error;
251 fn from_str(s: &str) -> Result<$elem, Error> {
252 // TODO: add a way to parse that differently when needed.
253 Ok($elem(String::from(s)))
254 }
255 }
256 impl IntoAttributeValue for $elem {
257 fn into_attribute_value(self) -> Option<String> {
258 Some(self.0)
259 }
260 }
261 );
262}
263
264macro_rules! generate_elem_id {
265 ($elem:ident, $name:tt, $ns:expr) => (
266 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
267 pub struct $elem(pub String);
268 impl FromStr for $elem {
269 type Err = Error;
270 fn from_str(s: &str) -> Result<$elem, Error> {
271 // TODO: add a way to parse that differently when needed.
272 Ok($elem(String::from(s)))
273 }
274 }
275 impl From<$elem> for Element {
276 fn from(elem: $elem) -> Element {
277 Element::builder($name)
278 .ns($ns)
279 .append(elem.0)
280 .build()
281 }
282 }
283 );
284}
285
286/// Error type returned by every parser on failure.
287pub mod error;
288/// XML namespace definitions used through XMPP.
289pub mod ns;
290
291#[cfg(test)]
292/// Namespace-aware comparison for tests
293mod compare_elements;
294
295/// RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
296pub mod message;
297/// RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
298pub mod presence;
299/// RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
300pub mod iq;
301/// RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core
302pub mod stanza_error;
303
304/// RFC 6121: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence
305pub mod roster;
306
307/// XEP-0004: Data Forms
308pub mod data_forms;
309
310/// XEP-0030: Service Discovery
311pub mod disco;
312
313/// XEP-0045: Multi-User Chat
314pub mod muc;
315
316/// XEP-0047: In-Band Bytestreams
317pub mod ibb;
318
319/// XEP-0059: Result Set Management
320pub mod rsm;
321
322/// XEP-0060: Publish-Subscribe
323pub mod pubsub;
324
325/// XEP-0077: In-Band Registration
326pub mod ibr;
327
328/// XEP-0085: Chat State Notifications
329pub mod chatstates;
330
331/// XEP-0092: Software Version
332pub mod version;
333
334/// XEP-0115: Entity Capabilities
335pub mod caps;
336
337/// XEP-0166: Jingle
338pub mod jingle;
339
340/// XEP-0184: Message Delivery Receipts
341pub mod receipts;
342
343/// XEP-0191: Blocking Command
344pub mod blocking;
345
346/// XEP-0199: XMPP Ping
347pub mod ping;
348
349/// XEP-0203: Delayed Delivery
350pub mod delay;
351
352/// XEP-0221: Data Forms Media Element
353pub mod media_element;
354
355/// XEP-0224: Attention
356pub mod attention;
357
358/// XEP-0234: Jingle File Transfer
359pub mod jingle_ft;
360
361/// XEP-0260: Jingle SOCKS5 Bytestreams Transport Method
362pub mod jingle_s5b;
363
364/// XEP-0261: Jingle In-Band Bytestreams Transport Method
365pub mod jingle_ibb;
366
367/// XEP-0297: Stanza Forwarding
368pub mod forwarding;
369
370/// XEP-0300: Use of Cryptographic Hash Functions in XMPP
371pub mod hashes;
372
373/// XEP-0308: Last Message Correction
374pub mod message_correct;
375
376/// XEP-0313: Message Archive Management
377pub mod mam;
378
379/// XEP-0319: Last User Interaction in Presence
380pub mod idle;
381
382/// XEP-0353: Jingle Message Initiation
383pub mod jingle_message;
384
385/// XEP-0359: Unique and Stable Stanza IDs
386pub mod stanza_id;
387
388/// XEP-0380: Explicit Message Encryption
389pub mod eme;
390
391/// XEP-0390: Entity Capabilities 2.0
392pub mod ecaps2;