67 /*! |
67 /*! |
68 * \fn virtual bool QVersitContactExporterDetailHandler::preProcessDetail(const QContact& contact, const QContactDetail& detail, QVersitDocument* document) = 0; |
68 * \fn virtual bool QVersitContactExporterDetailHandler::preProcessDetail(const QContact& contact, const QContactDetail& detail, QVersitDocument* document) = 0; |
69 * Process \a detail and update \a document with the corresponding QVersitProperty(s). |
69 * Process \a detail and update \a document with the corresponding QVersitProperty(s). |
70 * \a contact provides the context within which the detail was found. |
70 * \a contact provides the context within which the detail was found. |
71 * |
71 * |
72 * Returns true if the detail has been handled and requires no furthur processing, false otherwise. |
72 * Returns true if the detail has been handled and requires no further processing, false otherwise. |
73 * |
73 * |
74 * This function is called on every QContactDetail encountered during an export. Supply this |
74 * This function is called on every QContactDetail encountered during an export. Supply this |
75 * function and return true to implement custom export behaviour. |
75 * function and return true to implement custom export behaviour. |
76 */ |
76 */ |
77 |
77 |
108 * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Detail handler |
108 * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Detail handler |
109 * |
109 * |
110 * An example usage of QVersitContactExporter |
110 * An example usage of QVersitContactExporter |
111 * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export example |
111 * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export example |
112 * |
112 * |
|
113 * \section1 Exporting group relationships |
|
114 * The exporter does not handle QContactRelationships at all. |
|
115 * |
|
116 * Some managers use the \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along |
|
117 * with contacts of type \l{QContactType::TypeGroup}{TypeGroup} to indicate categorization of |
|
118 * contacts. In vCard, categorization is represented by the CATEGORIES property, which has |
|
119 * semantics most similar to the QContactTag detail. For contact manager backends that supports |
|
120 * groups but not QContactTag, if the categorization information needs to be retained through |
|
121 * CATEGORIES vCard properties, extra work can be done to convert from group relationships to |
|
122 * QContactTag before passing the contact list to the exporter. Below is some example code that |
|
123 * does this translation. |
|
124 * |
|
125 * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Export relationship example |
|
126 * |
113 * \sa QVersitDocument, QVersitProperty, QVersitContactExporterDetailHandler, QVersitResourceHandler |
127 * \sa QVersitDocument, QVersitProperty, QVersitContactExporterDetailHandler, QVersitResourceHandler |
114 */ |
128 */ |
|
129 |
|
130 /*! |
|
131 \enum QVersitContactExporter::Error |
|
132 This enum specifies an error that occurred during the most recent call to exportContacts() |
|
133 \value NoError The most recent operation was successful |
|
134 \value EmptyContactError One of the contacts was empty |
|
135 \value NoNameError One of the contacts has no QContactName field |
|
136 */ |
115 |
137 |
116 /*! |
138 /*! |
117 * Constructs a new contact exporter |
139 * Constructs a new contact exporter |
118 */ |
140 */ |
119 QVersitContactExporter::QVersitContactExporter() |
141 QVersitContactExporter::QVersitContactExporter() |
130 } |
152 } |
131 |
153 |
132 /*! |
154 /*! |
133 * Converts \a contacts into a list of corresponding QVersitDocuments, using the format given by |
155 * Converts \a contacts into a list of corresponding QVersitDocuments, using the format given by |
134 * \a versitType. |
156 * \a versitType. |
135 */ |
157 * Returns true on success. If any of the contacts could not be exported, false is returned and |
136 QList<QVersitDocument> QVersitContactExporter::exportContacts( |
158 * errors() will return a list describing the errors that occurred. The successfully exported |
|
159 * documents will still be available via documents(). |
|
160 */ |
|
161 bool QVersitContactExporter::exportContacts( |
137 const QList<QContact>& contacts, |
162 const QList<QContact>& contacts, |
138 QVersitDocument::VersitType versitType) |
163 QVersitDocument::VersitType versitType) |
139 { |
164 { |
140 QList<QVersitDocument> list; |
165 int contactIndex = 0; |
141 foreach (QContact contact, contacts) { |
166 d->mDocuments.clear(); |
|
167 d->mErrors.clear(); |
|
168 bool ok = true; |
|
169 foreach (const QContact& contact, contacts) { |
142 QVersitDocument versitDocument; |
170 QVersitDocument versitDocument; |
143 versitDocument.setType(versitType); |
171 versitDocument.setType(versitType); |
144 d->exportContact(contact, versitDocument); |
172 QVersitContactExporter::Error error; |
145 list.append(versitDocument); |
173 if (d->exportContact(contact, versitDocument, &error)) { |
|
174 d->mDocuments.append(versitDocument); |
|
175 } else { |
|
176 d->mErrors.insert(contactIndex, error); |
|
177 ok = false; |
|
178 } |
|
179 contactIndex++; |
146 } |
180 } |
147 |
181 |
148 return list; |
182 return ok; |
|
183 } |
|
184 |
|
185 /*! |
|
186 * Returns the documents exported in the most recent call to exportContacts(). |
|
187 * |
|
188 * \sa exportContacts() |
|
189 */ |
|
190 QList<QVersitDocument> QVersitContactExporter::documents() const |
|
191 { |
|
192 return d->mDocuments; |
|
193 } |
|
194 |
|
195 /*! |
|
196 * Returns the map of errors encountered in the most recent call to exportContacts(). The key is |
|
197 * the index into the input list of contacts and the value is the error that occurred on that |
|
198 * contact. |
|
199 * |
|
200 * \sa exportContacts() |
|
201 */ |
|
202 QMap<int, QVersitContactExporter::Error> QVersitContactExporter::errors() const |
|
203 { |
|
204 return d->mErrors; |
149 } |
205 } |
150 |
206 |
151 /*! |
207 /*! |
152 * Sets \a handler to be the handler for processing QContactDetails, or 0 to have no handler. |
208 * Sets \a handler to be the handler for processing QContactDetails, or 0 to have no handler. |
153 * |
209 * |