48 QTM_BEGIN_NAMESPACE

    48 QTM_USE_NAMESPACE

    49 

    49 

    50 /*!

    50 /*!

    51   \class QVersitContactImporter

    51   \class QVersitContactImporterPropertyHandler

    52   \preliminary

    53   \brief The QVersitContactImporterPropertyHandler class is an interface for clients wishing to

    54   implement custom import behaviour for versit properties

    57   The versit properties (\l QVersitProperty) that were not imported by

    58   \sa QVersitContactImporter

    58   \l QVersitContactImporter::importContact() can be fetched after importing

    59  */

    59   by calling \l QVersitContactImporter::unknownVersitProperties().

    60 

    60   For the returned properties,

    61 /*!

    61   the client can perform the conversions from versit properties

    62  * \fn QVersitContactImporterPropertyHandler::~QVersitContactImporterPropertyHandler()

    62   to contact details and add the converted details to the QContact.

    63  * Frees any memory in use by this handler.

    63  

    64  */

    64   \code

    65 

    65  

    66 /*!

    66   QVersitDocument document;

    67  * \fn virtual bool QVersitContactImporterPropertyHandler::preProcessProperty(const QVersitDocument& document, const QVersitProperty& property, int contactIndex, QContact* contact) = 0;

    67   QVersitProperty property;

    68  * Process \a property and update \a contact with the corresponding QContactDetail(s).

    68  

    69  * \a document provides the context within which the property was found.

    69   property.setName(QString::fromAscii("N"));

    70  * \a contactIndex specifies the position that \a contact will take in the list returned by

    70   property.setValue("Citizen;John;Q;;");

    71  * \l QVersitContactImporter::importContacts().

    71   document.addProperty(property);

    72  *

    72  

    73  * Returns true if the property has been handled and requires no further processing, false

    73   property.setName(QString::fromAscii("X-UNKNOWN-PROPERTY"));

    74  * otherwise.

    74   property.setValue("some value");

    75  *

    75   document.addProperty(property);

    76  * This function is called on every QVersitProperty encountered during an import.  Supply this

    76  

    77  * function and return true to implement custom import behaviour.

    77   QVersitContactImporter importer;

    78  */

    78   importer.setImagePath(QString::fromAscii("/my/image/path"));

    79 

    79   importer.setAudioClipPath(QString::fromAscii("my/audio_clip/path"));

    80 /*!

    80  

    81  * \fn virtual bool QVersitContactImporterPropertyHandler::postProcessProperty(const QVersitDocument& document, const QVersitProperty& property, bool alreadyProcessed, int contactIndex, QContact* contact) = 0;

    81   QContact contact = importer.importContact(document);

    82  * Process \a property and update \a contact with the corresponding QContactDetail(s).

    82   // contact now contains the "N" property as a QContactName

    83  * \a document provides the context within which the property was found.

    83   QList<QVersitProperty> unknownProperties = importer.unknownVersitProperties();

    84  * \a contactIndex specifies the position that \a contact will take in the list returned by

    84   // unknownProperties contains "X-UNKNOWN-PROPERTY"

    85  * \l QVersitContactImporter::importContacts().

    85   // that can be handled by the client itself

    86  * \a alreadyProcessed is true if the detail has already been processed either by

    86  

    87  * \l preProcessProperty() or by QVersitContactImporter itself.

    87   \endcode

    88  *

    88  

    89  * Returns true if the property has been handled, false otherwise.

    89   \sa QVersitDocument, QVersitReader

    90  *

    91  * This function is called on every QVersitProperty encountered during an import.  This can be

    92  * used to implement support for QVersitProperties not supported by QVersitContactImporter.

    93  */

    94 

    95 /*!

    96  * \class QVersitContactImporter

    97  * \preliminary

    98  * \brief The QVersitContactImporter class creates QContacts from QVersitDocuments.

    99  *

   100  * \ingroup versit

   101  *

   102  * A \l QVersitResourceHandler is associated with the importer to supply the behaviour for saving

   103  * files to persistent storage.  By default, this is set to a \l QVersitDefaultResourceHandler,

   104  * which does not save files to persistent storage.  Note that although avatars found in vCards

   105  * are not saved to disk by default, the importer does set the pixmap of the contact detail to the

   106  * image.  If a full-sized avatar image needs to be persisted, a custom QVersitResourceHandler

   107  * should be supplied which implements this.

   108  *

   109  * By associating a QVersitContactImporterPropertyHandler with the importer using

   110  * setPropertyHandler(), the client can pass in a handler to override the processing of properties

   111  * and/or handle properties that QVersitContactImporter doesn't support.

   112  *

   113  * An example property handler that logs unknown properties:

   114  * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Property handler

   115  *

   116  * An example usage of QVersitContactImporter

   117  * \snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Import example

   118  *

   119  * \sa QVersitDocument, QVersitReader, QVersitContactImporterPropertyHandler

   105  * Sets the \a path where the contact photos will be saved.

   135  * Converts \a documents into a corresponding list of QContacts.

   106  * This function should be called before calling \l importContact().

   136  */

   107  * If the image path has not been set,

   137 QList<QContact> QVersitContactImporter::importContacts(const QList<QVersitDocument>& documents)

   108  * the images in the versit document will not be added to the contact.

   138 {

   109  * There is no default path for them.

   139     QList<QContact> list;

   110  */

   140     int i = 0;

   141     foreach (QVersitDocument document, documents) {

   142         list.append(d->importContact(document, i));

   143         i++;

   144     }

   145 

   146     return list;

   147 }

   148 

   149 /*!

   150  * Sets \a handler to be the handler for processing QVersitProperties, or 0 to have no handler.

   151  */

   152 void QVersitContactImporter::setPropertyHandler(QVersitContactImporterPropertyHandler* handler)

   153 {

   154     d->mPropertyHandler = handler;

   155 }

   156 

   157 /*!

   158  * Gets the handler for processing QVersitProperties.

   159  */

   160 QVersitContactImporterPropertyHandler* QVersitContactImporter::propertyHandler() const

   161 {

   162     return d->mPropertyHandler;

   163 }

   164 

   165 /*!

   166  * Sets \a handler to be the handler to save files with, or 0 to have no handler.

   167  */

   168 void QVersitContactImporter::setResourceHandler(QVersitResourceHandler* handler)

   169 {

   170     d->mResourceHandler = handler;

   171 }

   172 

   173 /*!

   174  * Returns the associated resource handler.

   175  */

   176 QVersitResourceHandler* QVersitContactImporter::resourceHandler() const

   177 {

   178     return d->mResourceHandler;

   179 }

   180 

   181 /*! \internal */

   113     d->mImagePath = path;

   184     Q_UNUSED(path)

   114 }

   185 }

   115 

   186 

   116 /*!

   187 /*! \internal */

   117  * Returns the path where the contact photos are saved.

   118  */

   121     return d->mImagePath;

   190     return QString();

   122 }

   191 }

   123 

   192 

   124 /*!

   193 /*! \internal */

   125  * Sets the \a path where the contact related audio clips will be saved.

   126  * This function should be called before calling \l importContact().

   127  * If the audio clip path has not been set,

   128  * the audio clips in the versit document will not be added to the contact.

   129  * There is no default path for them.

   130  */

   133     d->mAudioClipPath = path;

   196     Q_UNUSED(path)

   134 }

   197 }

   135 

   198 

   136 /*!

   199 /*! \internal */

   137  * Returns the path where the contact related audio clips will be saved.

   138  */

   141     return d->mAudioClipPath;

   202     return QString();

   142 }

   203 }

   143 

   204 

   144 /*!

   205 /*! \internal */

   145  * Creates a QContact from \a versitDocument.

   146  */

   149     return d->importContact(versitDocument);

   208     QList<QVersitDocument> list;

   150 }

   209     list.append(versitDocument);

   151 

   210     return importContacts(list).first();

   152 /*!

   211 }

   153  * Returns the list of versit properties that were not imported

   212 

   154  * by the most recent call of \l importContact().

   213 /*! \internal */

   155  */

   158     return d->mUnknownVersitProperties;

   216     return QList<QVersitProperty>();

   159 }

   217 }

   160 

   161 QTM_END_NAMESPACE