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

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