1/*
2 This file is part of libkabc.
3 Copyright (c) 2002 Tobias Koenig <tokoe@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_VCARDCONVERTER_H
22#define KABC_VCARDCONVERTER_H
23
24#include "kabc_export.h"
25#include "addressee.h"
26#include <QtCore/QString>
27
28namespace KABC {
29
30/**
31 @short Class to converting contact objects into vCard format and vice versa.
32
33 This class implements reading and writing of contact using from/to the
34 vCard format. Currently vCard version 2.1 and 3.0 is supported.
35
36 Example:
37
38 \code
39
40 QFile file( "myfile.vcf" );
41 file.open( QIODevice::ReadOnly );
42
43 QByteArray data = file.readAll();
44
45 VCardConverter converter;
46 Addressee::List list = converter.parseVCards( data );
47
48 // print formatted name of first contact
49 qDebug( "name=%s", list[ 0 ].formattedName().toLatin1() );
50
51 \endcode
52*/
53class KABC_EXPORT VCardConverter
54{
55 public:
56
57 /**
58 @li v2_1 - VCard format version 2.1
59 @li v3_0 - VCard format version 3.0
60 @li v4_0 - VCard format version 4.0
61 */
62 enum Version {
63 v2_1,
64 v3_0,
65 v4_0
66 };
67
68 /**
69 Constructor.
70 */
71 VCardConverter();
72
73 /**
74 Destructor.
75 */
76 ~VCardConverter();
77
78 /**
79 Creates a string in vCard format which contains the given
80 contact.
81
82 @param addr The contact object
83 @param version The version of the generated vCard format
84 */
85 QByteArray createVCard( const Addressee &addr, Version version = v3_0 ) const;
86
87 /**
88 Creates a string in vCard format which contains the given
89 list of contact.
90
91 @param list The list of contact objects
92 @param version The version of the generated vCard format
93 */
94 // FIXME: Add error handling
95 QByteArray createVCards( Addressee::List list, Version version = v3_0 ) const;
96
97 // FIXME: Add "createVCards( AddressBook * )"
98
99 /**
100 * @since 4.9.1
101 */
102 QByteArray exportVCard( const Addressee &addr, Version version ) const;
103
104 /**
105 * @since 4.9.1
106 */
107 QByteArray exportVCards( const Addressee::List &list, Version version ) const;
108
109 /**
110 Parses a string in vCard format and returns the first contact.
111 */
112 Addressee parseVCard( const QByteArray &vcard ) const;
113
114 /**
115 Parses a string in vCard format and returns a list of contact objects.
116 */
117 // FIXME: Add error handling
118 Addressee::List parseVCards( const QByteArray &vcard ) const;
119
120 private:
121 class VCardConverterPrivate;
122 VCardConverterPrivate *const d;
123};
124
125/**
126 Helper functions
127 */
128
129/**
130 * Converts a QDateTime to a date string as it is used in VCard and LDIF files.
131 * The return value is in the form "yyyyMMddThhmmssZ" (e.g. "20031201T120000Z")
132 * @param dateTime date and time to be converted
133 */
134KABC_EXPORT QString dateToVCardString( const QDateTime &dateTime );
135
136/**
137 * Converts a QDate to a short date string as it is used in VCard and LDIF files.
138 * The return value is in the form "yyyyMMdd" (e.g. "20031201")
139 * @param date date to be converted
140 */
141KABC_EXPORT QString dateToVCardString( const QDate &date );
142
143/**
144 * Converts a date string as it is used in VCard and LDIF files to a QDateTime value.
145 * If the date string does not contain a time value, it will be returned as 00:00:00.
146 * (e.g. "20031201T120000" will return a QDateTime for 2003-12-01 at 12:00)
147 * @param dateString string representing the date and time.
148 */
149KABC_EXPORT QDateTime VCardStringToDate( const QString &dateString );
150
151}
152#endif
153