98 |
95 |
99 /*! |
96 /*! |
100 \class QVersitContactImporterPropertyHandlerV2 |
97 \class QVersitContactImporterPropertyHandlerV2 |
101 \brief The QVersitContactImporterPropertyHandlerV2 class is an interface for clients wishing to |
98 \brief The QVersitContactImporterPropertyHandlerV2 class is an interface for clients wishing to |
102 implement custom import behaviour for vCard properties. |
99 implement custom import behaviour for vCard properties. |
|
100 \ingroup versit-extension |
|
101 \inmodule QtVersit |
103 |
102 |
104 This interface supercedes QVersitContactImporterPropertyHandler. |
103 This interface supercedes QVersitContactImporterPropertyHandler. |
105 |
|
106 \ingroup versit |
|
107 |
104 |
108 \sa QVersitContactImporter |
105 \sa QVersitContactImporter |
109 */ |
106 */ |
110 |
107 |
111 /*! |
108 /*! |
112 \fn QVersitContactImporterPropertyHandlerV2::~QVersitContactImporterPropertyHandlerV2() |
109 \fn QVersitContactImporterPropertyHandlerV2::~QVersitContactImporterPropertyHandlerV2() |
113 Frees any memory in use by this handler. |
110 Frees any memory in use by this handler. |
114 */ |
111 */ |
115 |
112 |
116 /*! |
113 /*! |
117 \fn void QVersitContactImporterPropertyHandlerV2::propertyProcessed(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, const QContact& contact, QList<QContactDetail>* updatedDetails) |
114 \fn void QVersitContactImporterPropertyHandlerV2::propertyProcessed(const QVersitDocument& document, const QVersitProperty& property, const QContact& contact, bool* alreadyProcessed, QList<QContactDetail>* updatedDetails) |
118 Process \a property and provide a list of updated details by adding them to \a updatedDetails. |
115 Process \a property and provide a list of updated details by adding them to \a updatedDetails. |
119 |
116 |
120 This function is called on every QVersitProperty encountered during an import, after the property |
117 This function is called on every QVersitProperty encountered during an import, after the property |
121 has been processed by the QVersitContactImporter. An implementation of this function can be made |
118 has been processed by the QVersitContactImporter. An implementation of this function can be made |
122 to provide support for vCard properties not supported by QVersitContactImporter. |
119 to provide support for vCard properties not supported by QVersitContactImporter. |
123 |
120 |
124 The supplied \a document is the container for the \a property. \a alreadyProcessed is true if the |
121 The supplied \a document is the container for the \a property. \a alreadyProcessed is true if |
125 QVersitContactImporter was successful in processing the property. \a contact holds the state of |
122 the QVersitContactImporter or another handler was successful in processing the property. If it is |
126 the contact before the property was processed by the importer. \a updatedDetails is initially |
123 false and the handler processes the property, it should be set to true to inform later handlers |
127 filled with a list of details that the importer will update, and can be modified (by removing, |
124 that the property requires no further processing. \a contact holds the state of the contact |
128 modifying or adding details to the list) |
125 before the property was processed by the importer. \a updatedDetails is initially filled with a |
|
126 list of details that the importer will update, and can be modified (by removing, modifying or |
|
127 adding details to the list) |
129 */ |
128 */ |
130 |
129 |
131 /*! |
130 /*! |
132 \fn void QVersitContactImporterPropertyHandlerV2::documentProcessed(const QVersitDocument& document, QContact* contact) |
131 \fn void QVersitContactImporterPropertyHandlerV2::documentProcessed(const QVersitDocument& document, QContact* contact) |
133 Perform any final processing on the \a contact generated by the \a document. This can be |
132 Perform any final processing on the \a contact generated by the \a document. This can be |
136 This function is called after all QVersitProperties have been handled by the |
135 This function is called after all QVersitProperties have been handled by the |
137 QVersitContactImporter. |
136 QVersitContactImporter. |
138 */ |
137 */ |
139 |
138 |
140 /*! |
139 /*! |
141 \fn int QVersitContactImporterPropertyHandlerV2::version() const |
|
142 Returns the version of the handler. Currently, always returns 2. |
|
143 */ |
|
144 |
|
145 /*! |
|
146 \class QVersitContactImporter |
140 \class QVersitContactImporter |
147 \brief The QVersitContactImporter class converts \l{QVersitDocument}{QVersitDocuments} to |
141 \brief The QVersitContactImporter class converts \l{QVersitDocument}{QVersitDocuments} to |
148 \l{QContact}{QContacts}. |
142 \l{QContact}{QContacts}. |
149 |
143 |
150 \ingroup versit |
144 \ingroup versit |
|
145 \inmodule QtVersit |
151 |
146 |
152 This class is used to convert lists of \l{QVersitDocument}{QVersitDocuments} (which may be |
147 This class is used to convert lists of \l{QVersitDocument}{QVersitDocuments} (which may be |
153 produced by a QVersitReader) to lists of \l{QContact}{QContacts} (which may be saved into a |
148 produced by a QVersitReader) to lists of \l{QContact}{QContacts} (which may be saved into a |
154 QContactManager. Unless there is an error, there is a one-to-one mapping between Versit |
149 QContactManager. Unless there is an error, there is a one-to-one mapping between Versit |
155 documents and QContacts. The importer can be extended by clients by associating resource |
150 documents and QContacts. The importer can be extended by clients by associating resource |
156 and property handlers. |
151 and property handlers. |
|
152 |
|
153 Here is a simple example of how to use QVersitContactImporter: |
|
154 \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example |
|
155 |
|
156 \section1 Extension via handlers |
157 |
157 |
158 A \l QVersitResourceHandler is associated with the importer to supply the behaviour for saving |
158 A \l QVersitResourceHandler is associated with the importer to supply the behaviour for saving |
159 files to persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler, |
159 files to persistent storage. By default, this is set to a \l QVersitDefaultResourceHandler, |
160 which does not save files to persistent storage. Note that although photos found in vCards |
160 which does not save files to persistent storage. Note that although photos found in vCards |
161 are not saved to disk by default, the importer does add a QContactThumbnail detail to the |
161 are not saved to disk by default, the importer does add a QContactThumbnail detail to the |
162 image. If a full-sized image needs to be loaded from a URL and persisted on disk, a custom |
162 image. If a full-sized image needs to be loaded from a URL and persisted on disk, a custom |
163 QVersitResourceHandler should be supplied which implements this. |
163 QVersitResourceHandler should be supplied which implements this. |
164 |
164 |
165 By associating a QVersitContactImporterPropertyHandlerV2 with the importer using |
165 By associating a QVersitContactImporterPropertyHandlerV2 with the importer using |
166 setPropertyHandler(), the client can pass in a handler to override the processing of properties |
166 setPropertyHandler(), the client can pass in a handler to override the processing of properties |
167 and/or handle properties that QVersitContactImporter doesn't support. A "backup" handler is |
167 and/or handle properties that QVersitContactImporter doesn't support. Also, handlers can be |
168 provided by QVersitContactImporterPropertyHandlerV2::createBackupHandler() which imports |
168 implicitly associated to an importer through the \l{Versit Plugins}{handler plugin mechanism}. |
169 properties generated by the corresponding backup handler for the QVersitContactExporter. |
169 The importer can be constructed with a profile, which gives hints about what kind of handlers |
170 |
170 should be added to it. For example, the backup profile can be used to instruct the importer to |
171 An example usage of QVersitContactImporter: |
171 interpret properties that have been generated by a backup-profiled QVersitContactExporter. To |
172 \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example |
172 illustrate, a backup importer can be constructed with: |
|
173 \code |
|
174 QVersitContactImporter importer(QVersitContactHandlerFactory::ProfileBackup); |
|
175 \endcode |
|
176 For more details on how the backup plugin works, see \l{Versit Plugins} |
173 |
177 |
174 \section1 Importing categories |
178 \section1 Importing categories |
175 The importer imports the vCard CATEGORIES property by converting each category to a QContactTag. |
179 The importer imports the vCard CATEGORIES property by converting each category to a QContactTag. |
176 Some managers may not have support for QContactTag, but instead support categorization using the |
180 Some managers may not have support for QContactTag, but instead support categorization using the |
177 \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along with contacts of type |
181 \l{QContactRelationship::HasMember}{HasMember} QContactRelationship along with contacts of type |
191 \value InvalidDocumentError One of the documents is not a vCard |
195 \value InvalidDocumentError One of the documents is not a vCard |
192 \value EmptyDocumentError One of the documents is empty |
196 \value EmptyDocumentError One of the documents is empty |
193 */ |
197 */ |
194 |
198 |
195 |
199 |
196 /*! |
|
197 Constructs and returns a property handler that restores data from a vCard generated using the |
|
198 exporter backup detail handler (see QVersitContactExporterDetailHandlerV2::createBackupHandler()). |
|
199 The caller is responsible for deleting the object. |
|
200 |
|
201 Clients wishing to implement their own property handler and also benefit from the functionality of |
|
202 the default handler can use this function to construct one, and wrap a custom |
|
203 QVersitContactImporterPropertyHandlerV2 around it. In the implementation of propertyProcessed and |
|
204 documentProcessed, the respective functions in the backup handler should be called as the last |
|
205 step (ensuring the arguments are correctly updated and passed through). |
|
206 */ |
|
207 QVersitContactImporterPropertyHandlerV2* QVersitContactImporterPropertyHandlerV2::createBackupHandler() { |
|
208 return new QVCardImporterBackupHandler; |
|
209 } |
|
210 |
|
211 /*! Constructs a new importer */ |
200 /*! Constructs a new importer */ |
212 QVersitContactImporter::QVersitContactImporter() |
201 QVersitContactImporter::QVersitContactImporter() |
213 : d(new QVersitContactImporterPrivate) |
202 : d(new QVersitContactImporterPrivate) |
|
203 { |
|
204 } |
|
205 |
|
206 /*! |
|
207 * Constructs a new importer for the given \a profile. The profile strings should be one of those |
|
208 * defined by QVersitContactHandlerFactory, or a value otherwise agreed to by a \l{Versit |
|
209 * Plugins}{Versit plugin}. |
|
210 * |
|
211 * The profile determines which plugins will be loaded to supplement the importer. |
|
212 */ |
|
213 QVersitContactImporter::QVersitContactImporter(const QString& profile) |
|
214 : d(new QVersitContactImporterPrivate(profile)) |
214 { |
215 { |
215 } |
216 } |
216 |
217 |
217 /*! Frees the memory used by the importer */ |
218 /*! Frees the memory used by the importer */ |
218 QVersitContactImporter::~QVersitContactImporter() |
219 QVersitContactImporter::~QVersitContactImporter() |