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 | |
28 | namespace 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 | */ |
53 | class 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 | */ |
134 | KABC_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 | */ |
141 | KABC_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 | */ |
149 | KABC_EXPORT QDateTime VCardStringToDate( const QString &dateString ); |
150 | |
151 | } |
152 | #endif |
153 | |