/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the Qt Mobility Components.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include "qcontactmanagerengine.h"

#include "qcontactdetaildefinition.h"

#include "qcontactdetailfielddefinition.h"

#include "qcontactdetails.h"

#include "qcontactsortorder.h"

#include "qcontactfilters.h"

#include "qcontactaction.h"

#include "qcontactactiondescriptor.h"

#include "qcontactabstractrequest.h"

#include "qcontactabstractrequest_p.h"

#include "qcontactrequests.h"

#include "qcontactrequests_p.h"

#include "qcontact.h"

#include "qcontactfetchhint.h"

#include "qcontact_p.h"

#include "qcontactdetail_p.h"

#include <QMutex>

#include <QMutexLocker>

#include <QWeakPointer>

QTM_BEGIN_NAMESPACE

/*!

  \class QContactManagerEngine

  \brief The QContactManagerEngine class provides the interface for all

  implementations of the contact manager backend functionality.

  \ingroup contacts-backends

  Instances of this class are usually provided by a

  \l QContactManagerEngineFactory, which is loaded from a plugin.

  The default implementation of this interface provides a basic

  level of functionality for some functions so that specific engines

  can simply implement the functionality that is supported by

  the specific contacts engine that is being adapted.

  More information on writing a contacts engine plugin is available in

  the \l{Qt Contacts Manager Engines} documentation.

  \sa QContactManager, QContactManagerEngineFactory

 */

/*!

  \fn QContactManagerEngine::QContactManagerEngine()

  A default, empty constructor.

 */

/*!

  \fn QContactManagerEngine::dataChanged()

  This signal is emitted some time after changes occur to the data managed by this

  engine, and the engine is unable to determine which changes occurred, or if the

  engine considers the changes to be radical enough to require clients to reload all data.

  If this signal is emitted, no other signals may be emitted for the associated changes.

  As it is possible that other processes (or other devices) may have caused the

  changes, the timing can not be determined.

  \sa contactsAdded(), contactsChanged(), contactsRemoved()

 */

/*!

  \fn QContactManagerEngine::contactsAdded(const QList<QContactLocalId>& contactIds);

  This signal is emitted some time after a set of contacts has been added to

  this engine where the \l dataChanged() signal was not emitted for those changes.

  As it is possible that other processes (or other devices) may

  have added the contacts, the timing cannot be determined.

  The list of ids of contacts added is given by \a contactIds.  There may be one or more

  ids in the list.

  \sa dataChanged()

 */

/*!

  \fn QContactManagerEngine::contactsChanged(const QList<QContactLocalId>& contactIds);

  This signal is emitted some time after a set of contacts has been modified in

  this engine where the \l dataChanged() signal was not emitted for those changes.

  As it is possible that other processes (or other devices) may

  have modified the contacts, the timing cannot be determined.

  The list of ids of changed contacts is given by \a contactIds.  There may be one or more

  ids in the list.

  \sa dataChanged()

 */

/*!

  \fn QContactManagerEngine::contactsRemoved(const QList<QContactLocalId>& contactIds);

  This signal is emitted some time after a set of contacts has been removed from

  this engine where the \l dataChanged() signal was not emitted for those changes.

  As it is possible that other processes (or other devices) may

  have removed the contacts, the timing cannot be determined.

  The list of ids of removed contacts is given by \a contactIds.  There may be one or more

  ids in the list.

  \sa dataChanged()

 */

/*!

  \fn QContactManagerEngine::relationshipsAdded(const QList<QContactLocalId>& affectedContactIds);

  This signal is emitted some time after a set of contacts has been added to

  this engine where the \l dataChanged() signal was not emitted for those changes.

  As it is possible that other processes (or other devices) may

  have added the contacts, the timing cannot be determined.

  The list of ids of affected contacts is given by \a affectedContactIds.  There may be one or more

  ids in the list.

  \sa dataChanged()

 */

/*!

  \fn QContactManagerEngine::relationshipsRemoved(const QList<QContactLocalId>& affectedContactIds);

  This signal is emitted some time after a set of relationships has been removed from

  this engine where the \l dataChanged() signal was not emitted for those changes.

  As it is possible that other processes (or other devices) may

  have removed the relationships, the timing cannot be determined.

  The list of ids of affected contacts is given by \a affectedContactIds.  There may be one or more

  ids in the list.

  \sa dataChanged()

 */

/*!

  \fn QContactManagerEngine::selfContactIdChanged(const QContactLocalId& oldId, const QContactLocalId& newId)

  This signal is emitted at some point after the id of the self-contact is changed from \a oldId to \a newId in the manager.

  If the \a newId is the invalid, zero id, then the self contact was deleted or no self contact exists.

  This signal must not be emitted if the dataChanged() signal was previously emitted for this change.

  As it is possible that other processes (or other devices) may

  have removed or changed the self contact, the timing cannot be determined.

  \sa dataChanged()

 */

/*! Returns the manager name for this QContactManagerEngine */

QString QContactManagerEngine::managerName() const

{

    return QString(QLatin1String("base"));

}

/*!

  Returns the parameters with which this engine was constructed.  Note that

  the engine may have discarded unused or invalid parameters at the time of

  construction, and these will not be returned.

 */

QMap<QString, QString> QContactManagerEngine::managerParameters() const

{

    return QMap<QString, QString>(); // default implementation requires no parameters.

}

/*!

  Returns the unique URI of this manager, which is built from the manager name and the parameters

  used to construct it.

 */

QString QContactManagerEngine::managerUri() const

{

    return QContactManager::buildUri(managerName(), managerParameters());

}

/*!

  Returns a list of contact ids that match the given \a filter, sorted according to the given list of \a sortOrders.

  Depending on the backend, this filtering operation may involve retrieving all the contacts.

  Any error which occurs will be saved in \a error.

 */

QList<QContactLocalId> QContactManagerEngine::contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, QContactManager::Error* error) const

{

    Q_UNUSED(filter);

    Q_UNUSED(sortOrders);

    *error = QContactManager::NotSupportedError;

    return QList<QContactLocalId>();

}

/*!

  Returns the list of contacts which match the given \a filter stored in the manager sorted according to the given list of \a sortOrders.

  Any operation error which occurs will be saved in \a error.

  The \a fetchHint parameter describes the optimization hints that a manager may take.

  If the \a fetchHint is the default constructed hint, all existing details, relationships and action preferences

  in the matching contacts will be returned.  A client should not make changes to a contact which has

  been retrieved using a fetch hint other than the default fetch hint.  Doing so will result in information

  loss when saving the contact back to the manager (as the "new" restricted contact will

  replace the previously saved contact in the backend).

  \sa QContactFetchHint

 */

QList<QContact> QContactManagerEngine::contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, const QContactFetchHint& fetchHint, QContactManager::Error* error) const

{

    Q_UNUSED(filter);

    Q_UNUSED(sortOrders);

    Q_UNUSED(fetchHint);

    *error = QContactManager::NotSupportedError;

    return QList<QContact>();

}

/*!

  Returns the contact in the database identified by \a contactId.

  If the contact does not exist, an empty, default constructed QContact will be returned,

  and the \a error will be set to  \c QContactManager::DoesNotExistError.

  Any operation error which occurs will be saved in \a error.

  The \a fetchHint parameter describes the optimization hints that a manager may take.

  If the \a fetchHint is the default constructed hint, all existing details, relationships and action preferences

  in the matching contact will be returned.  A client should not make changes to a contact which has

  been retrieved using a fetch hint other than the default fetch hint.  Doing so will result in information

  loss when saving the contact back to the manager (as the "new" restricted contact will

  replace the previously saved contact in the backend).

  \sa QContactFetchHint

 */

QContact QContactManagerEngine::contact(const QContactLocalId& contactId, const QContactFetchHint& fetchHint, QContactManager::Error* error) const

{

    Q_UNUSED(contactId);

    Q_UNUSED(fetchHint);

    *error = QContactManager::NotSupportedError;

    return QContact();

}

/*!

  Sets the id of the "self" contact to the given \a contactId.

  Returns true if the "self" contact id was set successfully.

  If the given \a contactId does not identify a contact

  stored in this manager, the \a error will be set to

  \c QContactManager::DoesNotExistError and the function will

  return false; if the backend does not support the

  concept of a "self" contact, the \a error will be set to

  \c QContactManager::NotSupportedError and the function will

  return false.

 */

bool QContactManagerEngine::setSelfContactId(const QContactLocalId& contactId, QContactManager::Error* error)

{

    Q_UNUSED(contactId);

    *error = QContactManager::NotSupportedError;

    return false;

}

/*!

  Returns the id of the "self" contact which has previously been set.

  If no "self" contact has been set, or if the self contact was removed

  from the manager after being set, or if the backend does not support

  the concept of a "self" contact, an invalid id will be returned

  and the \a error will be set to \c QContactManager::DoesNotExistError.

 */

QContactLocalId QContactManagerEngine::selfContactId(QContactManager::Error* error) const

{

    *error = QContactManager::DoesNotExistError;

    return QContactLocalId();

}

/*!

  Returns a list of relationships of the given \a relationshipType in which the contact identified by the given \a participantId participates in the given \a role.

  If \a participantId is the default-constructed id, \a role is ignored and all relationships of the given \a relationshipType are returned.

  If \a relationshipType is empty, relationships of any type are returned.

  If no relationships of the given \a relationshipType in which the contact identified by the given \a participantId is involved in the given \a role exists,

  \a error is set to QContactManager::DoesNotExistError.

 */

QList<QContactRelationship> QContactManagerEngine::relationships(const QString& relationshipType, const QContactId& participantId, QContactRelationship::Role role, QContactManager::Error* error) const

{

    Q_UNUSED(relationshipType);

    Q_UNUSED(participantId);

    Q_UNUSED(role);

    *error = QContactManager::NotSupportedError;

    return QList<QContactRelationship>();

}

/*!

  Saves the given \a relationships in the database and returns true if the operation was successful.

  For any relationship which was unable to be saved, an entry into the \a errorMap will be created,

  with the key being the index into the input relationships list, and the value being the error which

  occurred for that index.

  The supplied \a errorMap parameter may be null, if the client does not desire detailed error information.

  If supplied, it will be empty upon entry to this function.

  The overall operation error will be saved in \a error.

 */

bool QContactManagerEngine::saveRelationships(QList<QContactRelationship>* relationships, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error* error)

{

    Q_UNUSED(relationships);

    Q_UNUSED(errorMap);

    *error = QContactManager::NotSupportedError;

    return false;

}

/*!

  Saves the given \a relationship in the database.  If the relationship already exists in the database, this function will

  return \c false and the \a error will be set to \c QContactManager::AlreadyExistsError.

  If the relationship is saved successfully, this function will return \c true and \a error will be set

  to \c QContactManager::NoError.  Note that relationships cannot be updated directly using this function; in order

  to update a relationship, you must remove the old relationship, make the required modifications, and then save it.

  The given relationship is invalid if it is circular (the first contact is the second contact), or

  if it references a non-existent local contact (either the first or second contact).  If the given \a relationship is invalid,

  the function will return \c false and the \a error will be set to \c QContactManager::InvalidRelationshipError.

  The default implementation of this function converts the argument into a call to saveRelationships.

 */

bool QContactManagerEngine::saveRelationship(QContactRelationship *relationship, QContactManager::Error *error)

{

    // Convert to a list op

    if (relationship) {

        QList<QContactRelationship> list;

        list.append(*relationship);

        QMap<int, QContactManager::Error> errors;

        bool ret = saveRelationships(&list, &errors, error);

        if (errors.count() > 0)

            *error = errors.begin().value();

        *relationship = list.value(0);

        return ret;

    } else {

        *error = QContactManager::BadArgumentError;

        return false;

    }

}

/*!

  Removes the given \a relationship from the manager.  If the relationship exists in the manager, the relationship

  will be removed, the \a error will be set to \c QContactManager::NoError and this function will return true.  If no such

  relationship exists in the manager, the \a error will be set to \c QContactManager::DoesNotExistError and this function

  will return false.

  The default implementation of this function converts the argument into a call to removeRelationships

 */

bool QContactManagerEngine::removeRelationship(const QContactRelationship& relationship, QContactManager::Error* error)

{

    // Convert to a list op

    QList<QContactRelationship> list;

    list.append(relationship);

    QMap<int, QContactManager::Error> errors;

    bool ret = removeRelationships(list, &errors, error);

    if (errors.count() > 0)

        *error = errors.begin().value();

    return ret;

}

/*!

  Removes the given \a relationships from the database and returns true if the operation was successful.

  For any relationship which was unable to be removed, an entry into the \a errorMap will be created,

  with the key being the index into the input relationships list, and the value being the error which

  occurred for that index.

  The supplied \a errorMap parameter may be null, if the client does not desire detailed error information.

  If supplied, it will be empty upon entry to this function.

  The overall operation error will be saved in \a error.

 */

bool QContactManagerEngine::removeRelationships(const QList<QContactRelationship>& relationships, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error* error)

{

    Q_UNUSED(relationships);

    Q_UNUSED(errorMap);

    *error = QContactManager::NotSupportedError;

    return false;

}

/*!

  Synthesizes the display label of the given \a contact in a platform specific manner.

  Any error that occurs will be stored in \a error.

  Returns the synthesized display label.

 */

QString QContactManagerEngine::synthesizedDisplayLabel(const QContact& contact, QContactManager::Error* error) const

{

    // synthesize the display name from the name of the contact, or, failing that, the organisation of the contact.

    *error = QContactManager::NoError;

    QList<QContactDetail> allNames = contact.details(QContactName::DefinitionName);

    const QLatin1String space(" ");

    // synthesize the display label from the name.

    for (int i=0; i < allNames.size(); i++) {

        const QContactName& name = allNames.at(i);

        if (!name.customLabel().isEmpty()) {

            // default behaviour is to allow the user to define a custom display label.

            return name.customLabel();

        }

        QString result;

        if (!name.value(QContactName::FieldPrefix).trimmed().isEmpty()) {

           result += name.value(QContactName::FieldPrefix);

        }

        if (!name.value(QContactName::FieldFirstName).trimmed().isEmpty()) {

            if (!result.isEmpty())

                result += space;

            result += name.value(QContactName::FieldFirstName);

        }

        if (!name.value(QContactName::FieldMiddleName).trimmed().isEmpty()) {

            if (!result.isEmpty())

                result += space;

            result += name.value(QContactName::FieldMiddleName);

        }

        if (!name.value(QContactName::FieldLastName).trimmed().isEmpty()) {

            if (!result.isEmpty())

                result += space;

            result += name.value(QContactName::FieldLastName);

        }

        if (!name.value(QContactName::FieldSuffix).trimmed().isEmpty()) {

            if (!result.isEmpty())

                result += space;

            result += name.value(QContactName::FieldSuffix);

        }

        if (!result.isEmpty()) {

            return result;

        }

    }

    /* Well, we had no non empty names. if we have orgs, fall back to those */

    QList<QContactDetail> allOrgs = contact.details(QContactOrganization::DefinitionName);

    for (int i=0; i < allOrgs.size(); i++) {

        const QContactOrganization& org = allOrgs.at(i);

        if (!org.name().isEmpty()) {

            return org.name();

        }

    }

    *error = QContactManager::UnspecifiedError;

    return QString();

}

/*!

  Sets the contact display label of \a contact to the supplied \a displayLabel.

 */

void QContactManagerEngine::setContactDisplayLabel(QContact* contact, const QString& displayLabel)

{

    QContactDisplayLabel dl;

    dl.setValue(QContactDisplayLabel::FieldLabel, displayLabel);

    setDetailAccessConstraints(&dl, QContactDetail::Irremovable | QContactDetail::ReadOnly);

    contact->d->m_details.replace(0, dl);

}

/*!  

  \deprecated

  Returns a copy of \a contact with the contact display label set to the supplied \a displayLabel.

  This function does not touch the database in any way, and is purely a convenience to allow engine implementations to set the display label.

  This function has been deprecated - use the function with the same name that accepts different parameters.

*/

QContact QContactManagerEngine::setContactDisplayLabel(const QString& displayLabel, const QContact& contact)

{

    QContact newContact = contact;

    setContactDisplayLabel(&newContact, displayLabel);

    return newContact;

}

/*!

  Returns true if the given \a feature is supported by this engine for contacts of the given \a contactType

 */

bool QContactManagerEngine::hasFeature(QContactManager::ManagerFeature feature, const QString& contactType) const

{

    Q_UNUSED(feature);

    Q_UNUSED(contactType);

    return false;

}