KContacts

vcardconverter.h
1 /*
2  This file is part of the KContacts framework.
3  SPDX-FileCopyrightText: 2002 Tobias Koenig <[email protected]>
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 
15 namespace 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 */
40 class KCONTACTS_EXPORT VCardConverter
41 {
42 public:
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  */
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 
104 private:
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  */
119 Q_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  */
126 Q_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  */
134 Q_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  */
140 KCONTACTS_EXPORT void adaptIMAttributes(QByteArray &data);
141 }
142 #endif
address book entry
Definition: addressee.h:69
Class to converting contact objects into vCard format and vice versa.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 04:09:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.