1/*
2 This file is part of the KContacts framework.
3 SPDX-FileCopyrightText: 2002 Tobias Koenig <tokoe@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCONTACTS_VCARDCONVERTER_H
9#define KCONTACTS_VCARDCONVERTER_H
10
11#include "kcontacts/addressee.h"
12#include "kcontacts_export.h"
13#include <QString>
14
15namespace KContacts
16{
17/*!
18 \class KContacts::VCardConverter
19 \inheaderfile KContacts/VCardConverter
20 \inmodule KContacts
21
22 \brief Class to converting contact objects into vCard format and vice versa.
23
24 This class implements reading and writing of contact using from/to the
25 vCard format. Currently vCard version 2.1 and 3.0 is supported.
26
27 Example:
28
29 \code
30 QFile file( "myfile.vcf" );
31 file.open( QIODevice::ReadOnly );
32
33 QByteArray data = file.readAll();
34
35 VCardConverter converter;
36 Addressee::List list = converter.parseVCards( data );
37
38 // print formatted name of first contact
39 qDebug( "name=%s", list[ 0 ].formattedName().toLatin1() );
40 \endcode
41*/
42class KCONTACTS_EXPORT VCardConverter
43{
44public:
45 /*!
46 \value v2_1 VCard format version 2.1
47 \value v3_0 VCard format version 3.0
48 \value v4_0 VCard format version 4.0
49 */
50 enum Version {
51 v2_1,
52 v3_0,
53 v4_0,
54 };
55
56 /*!
57 Constructor.
58 */
59 VCardConverter();
60
61 ~VCardConverter();
62
63 /*!
64 Creates a string in vCard format which contains the given
65 contact.
66
67 \a addr The contact object
68
69 \a version The version of the generated vCard format
70 */
71 Q_REQUIRED_RESULT QByteArray createVCard(const Addressee &addr, Version version = v3_0) const;
72
73 // FIXME: Add error handling
74 /*!
75 Creates a string in vCard format which contains the given
76 list of contact.
77
78 \a list The list of contact objects
79
80 \a version The version of the generated vCard format
81 */
82 Q_REQUIRED_RESULT QByteArray createVCards(const Addressee::List &list, Version version = v3_0) const;
83
84 /*!
85 * \since 4.9.1
86 */
87 Q_REQUIRED_RESULT QByteArray exportVCard(const Addressee &addr, Version version) const;
88
89 /*!
90 * \since 4.9.1
91 */
92 Q_REQUIRED_RESULT QByteArray exportVCards(const Addressee::List &list, Version version) const;
93
94 /*!
95 Parses a string in vCard format and returns the first contact.
96 */
97 Q_REQUIRED_RESULT Addressee parseVCard(const QByteArray &vcard) const;
98
99 // FIXME: Add error handling
100 /*!
101 Parses a string in vCard format and returns a list of contact objects.
102 */
103 Q_REQUIRED_RESULT Addressee::List parseVCards(const QByteArray &vcard) const;
104
105private:
106 Q_DISABLE_COPY(VCardConverter)
107 class VCardConverterPrivate;
108 VCardConverterPrivate *const d;
109};
110
111/*!
112 * Converts a QDateTime to a date string as it is used in VCard and LDIF files.
113 * The return value is in the form "yyyyMMddThhmmssZ" (e.g. "20031201T120000Z")
114 *
115 * \a dateTime date and time to be converted
116 */
117Q_REQUIRED_RESULT KCONTACTS_EXPORT QString dateToVCardString(const QDateTime &dateTime);
118
119/*!
120 * Converts a QDate to a short date string as it is used in VCard and LDIF files.
121 * The return value is in the form "yyyyMMdd" (e.g. "20031201")
122 *
123 * \a date date to be converted
124 */
125Q_REQUIRED_RESULT KCONTACTS_EXPORT QString dateToVCardString(QDate date);
126
127/*!
128 * Converts a date string as it is used in VCard and LDIF files to a QDateTime value.
129 * If the date string does not contain a time value, it will be returned as 00:00:00.
130 * (e.g. "20031201T120000" will return a QDateTime for 2003-12-01 at 12:00)
131 *
132 * \a dateString string representing the date and time.
133 */
134Q_REQUIRED_RESULT KCONTACTS_EXPORT QDateTime VCardStringToDate(const QString &dateString);
135
136/*!
137 * Convert KAddressBook attribute to VCard IM Attribute
138 */
139KCONTACTS_EXPORT void adaptIMAttributes(QByteArray &data);
140}
141#endif
142

source code of kcontacts/src/converter/vcardconverter.h