xmpp_parsers/
vcard.rs

1// Copyright (c) 2024 xmpp-rs contributors.
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7//! This module implements vCard, for the purpose of vCard-based avatars as defined in
8//! [XEP-0054](https://xmpp.org/extensions/xep-0054.html).
9//!
10//! Only the `<PHOTO>` element is supported as a member of this legacy vCard. For more modern and complete
11//! user profile management, see [XEP-0292](https://xmpp.org/extensions/xep-0292.html): vCard4 Over XMPP.
12//!
13//! For vCard updates defined in [XEP-0153](https://xmpp.org/extensions/xep-0153.html),
14//! see [`vcard_update`][crate::vcard_update] module.
15
16use xso::{
17    text::{Base64, StripWhitespace, TextCodec},
18    AsXml, FromXml,
19};
20
21use crate::iq::{IqGetPayload, IqResultPayload, IqSetPayload};
22use crate::ns;
23use minidom::Element;
24
25/// A photo element.
26#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
27#[xml(namespace = ns::VCARD, name = "PHOTO")]
28pub struct Photo {
29    /// The type of the photo.
30    #[xml(child)]
31    pub type_: Type,
32
33    /// The binary data of the photo.
34    #[xml(child)]
35    pub binval: Binval,
36}
37
38/// The type of the photo.
39#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
40#[xml(namespace = ns::VCARD, name = "TYPE")]
41pub struct Type {
42    /// The type as a plain text string; at least "image/jpeg", "image/gif" and "image/png" SHOULD be supported.
43    #[xml(text)]
44    pub data: String,
45}
46
47/// The binary data of the photo.
48#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
49#[xml(namespace = ns::VCARD, name = "BINVAL")]
50pub struct Binval {
51    /// The actual data.
52    #[xml(text(codec = Base64.filtered(StripWhitespace)))]
53    pub data: Vec<u8>,
54}
55
56/// A `<vCard>` element; only the `<PHOTO>` element is supported for this legacy vCard ; the rest is ignored.
57#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
58#[xml(namespace = ns::VCARD, name = "vCard")]
59pub struct VCard {
60    /// A photo element.
61    #[xml(child(default))]
62    pub photo: Option<Photo>,
63
64    /// Every other element in the vCard.
65    #[xml(element(n = ..))]
66    pub payloads: Vec<Element>,
67}
68
69impl IqSetPayload for VCard {}
70impl IqResultPayload for VCard {}
71
72/// A `<vCard/>` request element, for use in iq get.
73#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
74#[xml(namespace = ns::VCARD, name = "vCard")]
75pub struct VCardQuery;
76
77impl IqGetPayload for VCardQuery {}
78
79#[cfg(test)]
80mod tests {
81    use super::*;
82    use core::str::FromStr;
83
84    #[cfg(target_pointer_width = "32")]
85    #[test]
86    fn test_size() {
87        assert_size!(Photo, 24);
88        assert_size!(Type, 12);
89        assert_size!(Binval, 12);
90        assert_size!(VCard, 36);
91        assert_size!(VCardQuery, 0);
92    }
93
94    #[cfg(target_pointer_width = "64")]
95    #[test]
96    fn test_size() {
97        assert_size!(Photo, 48);
98        assert_size!(Type, 24);
99        assert_size!(Binval, 24);
100        assert_size!(VCard, 72);
101        assert_size!(VCardQuery, 0);
102    }
103
104    #[test]
105    fn test_vcard() {
106        // Create some bytes:
107        let bytes = [0u8, 1, 2, 129];
108
109        // Test xml stolen from https://xmpp.org/extensions/xep-0153.html#example-5
110        let test_vcard = format!(
111            r"<vCard xmlns='vcard-temp'>
112    <BDAY>1476-06-09</BDAY>
113    <ADR>
114      <CTRY>Italy</CTRY>
115      <LOCALITY>Verona</LOCALITY>
116      <HOME/>
117    </ADR>
118    <NICKNAME/>
119    <N><GIVEN>Juliet</GIVEN><FAMILY>Capulet</FAMILY></N>
120    <EMAIL>jcapulet@shakespeare.lit</EMAIL>
121    <PHOTO>
122      <TYPE>image/jpeg</TYPE>
123      <BINVAL>{}</BINVAL>
124    </PHOTO>
125  </vCard>",
126            base64::Engine::encode(&base64::prelude::BASE64_STANDARD, &bytes)
127        );
128
129        let test_vcard = Element::from_str(&test_vcard).expect("Failed to parse XML");
130        let test_vcard = VCard::try_from(test_vcard).expect("Failed to parse vCard");
131
132        let photo = test_vcard.photo.expect("No photo found");
133
134        assert_eq!(photo.type_.data, "image/jpeg".to_string());
135        assert_eq!(photo.binval.data, bytes);
136    }
137
138    #[test]
139    fn test_vcard_with_linebreaks() {
140        // Test xml stolen from https://xmpp.org/extensions/xep-0153.html#example-5
141        // extended to use a multi-line base64 string as is allowed as per RFC 2426
142        let test_vcard = r"<vCard xmlns='vcard-temp'>
143    <BDAY>1476-06-09</BDAY>
144    <ADR>
145      <CTRY>Italy</CTRY>
146      <LOCALITY>Verona</LOCALITY>
147      <HOME/>
148    </ADR>
149    <NICKNAME/>
150    <N><GIVEN>Juliet</GIVEN><FAMILY>Capulet</FAMILY></N>
151    <EMAIL>jcapulet@shakespeare.lit</EMAIL>
152    <PHOTO>
153      <TYPE>image/jpeg</TYPE>
154      <BINVAL>Zm9v
155Cg==</BINVAL>
156    </PHOTO>
157  </vCard>";
158
159        let test_vcard = Element::from_str(&test_vcard).expect("Failed to parse XML");
160        let test_vcard = VCard::try_from(test_vcard).expect("Failed to parse vCard");
161
162        let photo = test_vcard.photo.expect("No photo found");
163
164        assert_eq!(photo.type_.data, "image/jpeg".to_string());
165        assert_eq!(photo.binval.data, b"foo\n");
166    }
167}
xmpp_parsers/vcard.rs

xmpp_parsers/
vcard.rs
