93 |
91 |
94 /*! |
92 /*! |
95 \class QVersitContactExporterDetailHandlerV2 |
93 \class QVersitContactExporterDetailHandlerV2 |
96 \brief The QVersitContactExporterDetailHandlerV2 class is an interface for clients wishing to |
94 \brief The QVersitContactExporterDetailHandlerV2 class is an interface for clients wishing to |
97 implement custom export behaviour for certain contact details. |
95 implement custom export behaviour for certain contact details. |
|
96 \ingroup versit-extension |
|
97 \inmodule QtVersit |
98 |
98 |
99 This interface supercedes QVersitContactImporterPropertyHandler. |
99 This interface supercedes QVersitContactImporterPropertyHandler. |
100 |
|
101 \ingroup versit |
|
102 |
100 |
103 \sa QVersitContactExporter |
101 \sa QVersitContactExporter |
104 */ |
102 */ |
105 |
103 |
106 /*! |
104 /*! |
107 \fn QVersitContactExporterDetailHandlerV2::~QVersitContactExporterDetailHandlerV2() |
105 \fn QVersitContactExporterDetailHandlerV2::~QVersitContactExporterDetailHandlerV2() |
108 Frees any memory in use by this handler. |
106 Frees any memory in use by this handler. |
109 */ |
107 */ |
110 |
108 |
111 /*! |
109 /*! |
112 \fn void QVersitContactExporterDetailHandlerV2::detailProcessed(const QContact& contact, const QContactDetail& detail, const QSet<QString>& processedFields, const QVersitDocument& document, QList<QVersitProperty>* toBeRemoved, QList<QVersitProperty>* toBeAdded) |
110 \fn void QVersitContactExporterDetailHandlerV2::detailProcessed(const QContact& contact, const QContactDetail& detail, const QVersitDocument& document, QSet<QString>* processedFields, QList<QVersitProperty>* toBeRemoved, QList<QVersitProperty>* toBeAdded) |
113 |
111 |
114 Process \a detail and provide a list of updated \l{QVersitProperty}{QVersitProperties} by |
112 Process \a detail and provide a list of updated \l{QVersitProperty}{QVersitProperties} by |
115 modifying the \a toBeRemoved and \a toBeAdded lists. |
113 modifying the \a toBeRemoved and \a toBeAdded lists. |
116 |
114 |
117 This function is called on every QContactDetail encountered during an export, after the detail has |
115 This function is called on every QContactDetail encountered during an export, after the detail has |
118 been processed by the QVersitContactExporter. An implementation of this function can be made to |
116 been processed by the QVersitContactExporter. An implementation of this function can be made to |
119 provide support for QContactDetails not supported by QVersitContactExporter. |
117 provide support for QContactDetails not supported by QVersitContactExporter. |
120 |
118 |
121 The supplied \a contact is the container for the \a detail. \a processedFields contains a list of |
119 The supplied \a contact is the container for the \a detail. \a processedFields contains a list of |
122 fields in the \a detail that were considered by the QVersitContactExporter in processing the |
120 fields in the \a detail that were considered by the QVersitContactExporter or another handler in |
123 detail. \a document holds the state of the document before the detail was processed by the |
121 processing the detail. \a document holds the state of the document before the detail was |
124 exporter. |
122 processed by the exporter. |
125 |
123 |
126 \a toBeRemoved and \a toBeAdded are initially filled with a list of properties that the exporter |
124 \a toBeRemoved and \a toBeAdded are initially filled with a list of properties that the exporter |
127 will remove from and add to the document. These lists can be modified (by removing, modifying or |
125 will remove from and add to the document. These lists can be modified (by removing, modifying or |
128 adding properties) by the handler to control the changes that will actually be made to the |
126 adding properties) by the handler to control the changes that will actually be made to the |
129 document. If a property is to be modified in the document, the old version will appear in the |
127 document. If a property is to be modified in the document, the old version will appear in the |
130 \a toBeRemoved list and the new version will appear in the \a toBeAdded list. |
128 \a toBeRemoved list and the new version will appear in the \a toBeAdded list. When the handler |
|
129 uses a field from the detail, it should update the processedFields set to reflect this to inform |
|
130 later handlers that the field has already been processed. |
131 |
131 |
132 After the handler returns control back to the exporter, the properties in the \a toBeRemoved |
132 After the handler returns control back to the exporter, the properties in the \a toBeRemoved |
133 list will be removed and the properties in the \a toBeAdded list will be appended to the document. |
133 list will be removed and the properties in the \a toBeAdded list will be appended to the document. |
134 */ |
134 */ |
135 |
135 |
138 Perform any final processing on the \a document generated by the \a contact. This can be |
138 Perform any final processing on the \a document generated by the \a contact. This can be |
139 implemented by the handler to clear any internal state before moving onto the next contact. |
139 implemented by the handler to clear any internal state before moving onto the next contact. |
140 |
140 |
141 This function is called after all QContactDetails have been handled by the |
141 This function is called after all QContactDetails have been handled by the |
142 QVersitContactExporter. |
142 QVersitContactExporter. |
143 */ |
|
144 |
|
145 /*! |
|
146 \fn int QVersitContactExporterDetailHandlerV2::version() const |
|
147 Returns the version of the handler. Currently, always returns 2. |
|
148 */ |
143 */ |
149 |
144 |
150 /*! |
145 /*! |
151 \class QVersitContactExporter |
146 \class QVersitContactExporter |
152 \brief The QVersitContactExporter class converts \l {QContact}{QContacts} into |
147 \brief The QVersitContactExporter class converts \l {QContact}{QContacts} into |
153 \l {QVersitDocument}{QVersitDocuments}. |
148 \l {QVersitDocument}{QVersitDocuments}. |
154 \ingroup versit |
149 \ingroup versit |
|
150 \inmodule QtVersit |
155 |
151 |
156 This class is used to convert lists of \l {QContact}{QContacts} (which may be stored in a |
152 This class is used to convert lists of \l {QContact}{QContacts} (which may be stored in a |
157 QContactManager) into lists of \l {QVersitDocument}{QVersitDocuments} (which may be written to |
153 QContactManager) into lists of \l {QVersitDocument}{QVersitDocuments} (which may be written to |
158 an I/O device using QVersitReader. Unless there is an error, there is a one-to-one mapping |
154 an I/O device using QVersitReader. Unless there is an error, there is a one-to-one mapping |
159 between contacts and Versit documents. The exporter can be extended by clients by associating |
155 between contacts and Versit documents. The exporter can be extended by clients by associating |
160 resource and detail handlers. |
156 resource and detail handlers. |
161 |
157 |
|
158 Here is a simple example of how to use QVersitContactExporter: |
|
159 \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export example |
|
160 |
|
161 \section1 Extension via handlers |
|
162 |
162 A \l QVersitResourceHandler is associated with the exporter to supply the behaviour for loading |
163 A \l QVersitResourceHandler is associated with the exporter to supply the behaviour for loading |
163 files from persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler, |
164 files from persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler, |
164 which supports basic resource loading from the file system. An alternative resource handler |
165 which supports basic resource loading from the file system. An alternative resource handler |
165 can be specified with setResourceHandler(). |
166 can be specified with setResourceHandler(). |
166 |
167 |
167 By associating a \l QVersitContactExporterDetailHandlerV2 with the exporter using |
168 By associating a \l QVersitContactExporterDetailHandlerV2 with the exporter using |
168 setDetailHandler(), the client can pass in a handler to override the processing of details and/or |
169 setDetailHandler(), the client can pass in a handler to override the processing of details and/or |
169 handle details that QVersitContactExporter doesn't support. A "backup" handler is provided by |
170 handle details that QVersitContactExporter doesn't support. Also, handlers can be implicitly |
170 QVersitContactExporterDetailHandlerV2::createBackupHandler(), which serializes any details |
171 associated to an exporter through the \l{Versit Plugins}{handler plugin mechanism}. The exporter |
171 that the standard QVersitContactExporter doesn't support to the vCard. |
172 can be constructed with a profile, which gives hints about what kind of handlers should be added |
172 |
173 to it. For example, the backup profile can be used to instruct the exporter to encode any unknown |
173 |
174 details in the vCard such that it can be reconstructed later (a QVersitContactImporter constructed |
174 An example usage of QVersitContactExporter: |
175 under the backup profile can be used to decode it). To illustrate, a backup exporter can be |
175 \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export example |
176 constructed with: |
|
177 \code |
|
178 QVersitContactExporter exporter(QVersitContactHandlerFactory::ProfileBackup); |
|
179 \endcode |
|
180 For more details on how the backup plugin works, see \l{Versit Plugins} |
176 |
181 |
177 \section1 Exporting group relationships |
182 \section1 Exporting group relationships |
178 The exporter does not handle QContactRelationships at all. |
183 The exporter does not handle QContactRelationships at all. |
179 |
184 |
180 Some managers use the \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along |
185 Some managers use the \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along |
199 \value NoNameError One of the contacts has no QContactName field |
204 \value NoNameError One of the contacts has no QContactName field |
200 */ |
205 */ |
201 |
206 |
202 |
207 |
203 /*! |
208 /*! |
204 Constructs and returns a detail handler that encodes all details not handled by the base exporter. |
|
205 The caller is responsible for deleting the object. |
|
206 |
|
207 This handler encodes all writable details that the exporter doesn't recognise. The format it uses |
|
208 to encode the detail is as follows: |
|
209 \list |
|
210 \o All generated properties will have the name X-NOKIA-QCONTACTFIELD |
|
211 \o All generated properties will have a single Versit group, and all properties generated from a |
|
212 single detail will have the same group. |
|
213 \o All generated properties will have at least the parameters DETAIL, which holds the definition |
|
214 name of the QContactDetail from which it was generated, and FIELD, which holds the name of the |
|
215 field within the detail from which it was generated. |
|
216 \o If the field is of type QString or QByteArray, the property's value is set directly to the |
|
217 value of the field. (For a QByteArray value, the QVersitWriter will base-64 encode it.) |
|
218 \o If the field is of type bool, int, uint, QDate, QTime, QDateTime or QUrl a the property's |
|
219 value is set to a string representation of the field. A parameter DATATYPE is added to the |
|
220 property with value BOOL, INT, UINT, DATE, TIME or DATETIME depending on the type. |
|
221 \o If the field is of some other type, the field value is encoded to a QByteArray via QDataStream |
|
222 (and the resulting byte array is base-64 encoded by the QVersitWriter). In this case, the |
|
223 parameter DATATYPE=VARIANT is added to the Versit property. |
|
224 \endlist |
|
225 |
|
226 For example, a detail with definition name "Pet" and fields "Name"="Rex" and |
|
227 "Age"=(int)14 will be exported to the vCard properties: |
|
228 \code |
|
229 G0.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Name:Rex |
|
230 G0.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Age;DATATYPE=INT:14 |
|
231 \endcode |
|
232 |
|
233 And the next detail (say, "Pet" with a field "Name"="Molly" will generate: |
|
234 \code |
|
235 G1.X-NOKIA-QCONTACTFIELD;DETAIL=Pet;FIELD=Name:Molly |
|
236 \endcode |
|
237 |
|
238 The properties produced by this class can be imported by the importer "backup" property handler |
|
239 (created by QVersitContactImporterPropertyHandlerV2::createBackupHandler()) to reproduce the |
|
240 original \l{QContactDetail}{QContactDetails}. |
|
241 |
|
242 Clients wishing to implement their own detail handler and also benefit from the functionality of |
|
243 the backup handler can use this function to construct one, and wrap a custom |
|
244 QVersitContactExporterDetailHandlerV2 around it. In the implementation of detailProcessed and |
|
245 contactProcessed, the respective functions in the backup handler should be called as the last |
|
246 step (ensuring the arguments are correctly updated and passed through). |
|
247 */ |
|
248 QVersitContactExporterDetailHandlerV2* QVersitContactExporterDetailHandlerV2::createBackupHandler() { |
|
249 return new QVCardExporterBackupHandler; |
|
250 } |
|
251 |
|
252 /*! |
|
253 * Constructs a new contact exporter |
209 * Constructs a new contact exporter |
254 */ |
210 */ |
255 QVersitContactExporter::QVersitContactExporter() |
211 QVersitContactExporter::QVersitContactExporter() |
256 : d(new QVersitContactExporterPrivate()) |
212 : d(new QVersitContactExporterPrivate()) |
|
213 { |
|
214 } |
|
215 |
|
216 /*! |
|
217 * Constructs a new exporter for the given \a profile. The profile strings should be one of those |
|
218 * defined by QVersitContactHandlerFactory, or a value otherwise agreed to by a \l{Versit |
|
219 * Plugin}{Versit plugin}. |
|
220 * |
|
221 * The profile determines which plugins will be loaded to supplement the exporter. |
|
222 */ |
|
223 QVersitContactExporter::QVersitContactExporter(const QString& profile) |
|
224 : d(new QVersitContactExporterPrivate(profile)) |
257 { |
225 { |
258 } |
226 } |
259 |
227 |
260 /*! |
228 /*! |
261 * Frees any memory in use by this contact exporter. |
229 * Frees any memory in use by this contact exporter. |
281 d->mErrors.clear(); |
249 d->mErrors.clear(); |
282 bool ok = true; |
250 bool ok = true; |
283 foreach (const QContact& contact, contacts) { |
251 foreach (const QContact& contact, contacts) { |
284 QVersitDocument versitDocument; |
252 QVersitDocument versitDocument; |
285 versitDocument.setType(versitType); |
253 versitDocument.setType(versitType); |
|
254 versitDocument.setComponentType(QLatin1String("VCARD")); |
286 QVersitContactExporter::Error error; |
255 QVersitContactExporter::Error error; |
287 if (d->exportContact(contact, versitDocument, &error)) { |
256 if (d->exportContact(contact, versitDocument, &error)) { |
288 d->mDocuments.append(versitDocument); |
257 d->mDocuments.append(versitDocument); |
289 } else { |
258 } else { |
290 d->mErrors.insert(contactIndex, error); |
259 d->mErrors.insert(contactIndex, error); |