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

**

** Copyright (C) 2009 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_p.h"

#include "qcontactdetail_p.h"

QTM_BEGIN_NAMESPACE

/*!

  \class QContactManagerEngine

  \preliminary

  \brief The QContactManagerEngine class provides the interface for all

  implementations of the contact manager backend functionality.

  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 TODO.

  \sa QContactManager, QContactManagerEngineFactory

 */

/*!

  \fn QContactManagerEngine::QContactManagerEngine()

  A default, empty constructor.

 */

/*!

  \fn QContactManagerEngine::deref()

  Notifies the engine that it is no longer required.  If this

  engine can not be shared between managers, it is safe for the

  engine to delete itself in this function.

  If the engine implementation can be shared, this function can use a

  reference count and track lifetime that way.  The factory that

  returns an instance of this engine should increment the reference

  count in this case.

 */

/*!

  \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 sorted according to the given list of \a sortOrders.

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

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

 */

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

{

    Q_UNUSED(sortOrders);

    error = QContactManager::NotSupportedError;

    return QList<QContactLocalId>();

}

/*!

  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

{

    /* Slow way */

    QList<QContactLocalId> ret;

    /* If the filter matches all ids, then return the list of all ids */

    if (filter.type() == QContactFilter::DefaultFilter) {

        const QList<QContactLocalId>& allIds = contactIds(sortOrders, error);

        if (error != QContactManager::NoError)

            return ret;

        return allIds;

    }

    /* Otherwise, retrieve all contacts, test and return matching */

    const QList<QContact>& all = contacts(sortOrders, QStringList(), error);

    if (error != QContactManager::NoError)

        return ret;

    for (int j = 0; j < all.count(); j++) {

        if (testFilter(filter, all.at(j)))

            ret << all.at(j).localId();

    }

    return ret;

}

/*!

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

  If the given list of detail definition names \a definitionRestrictions is empty, each contact returned will include

  all of the details which are stored in it, otherwise only those details which are of a definition whose name is included

  in the \a definitionRestrictions list will be included.

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

 */

QList<QContact> QContactManagerEngine::contacts(const QList<QContactSortOrder>& sortOrders, const QStringList& definitionRestrictions, QContactManager::Error& error) const

{

    Q_UNUSED(sortOrders);

    Q_UNUSED(definitionRestrictions);

    error = QContactManager::NotSupportedError;

    return QList<QContact>();

}

/*!

  Returns a list of contacs 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.

  If the given list of detail definition names \a definitionRestrictions is empty, each contact returned will include

  all of the details which are stored in it, otherwise only those details which are of a definition whose name is included

  in the \a definitionRestrictions list will be included.

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

 */

QList<QContact> QContactManagerEngine::contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, const QStringList& definitionRestrictions, QContactManager::Error& error) const

{

    /* Slow way */

    QList<QContact> ret;

    /* Retrieve each contact.. . . */

    const QList<QContact>& all = contacts(sortOrders, definitionRestrictions, error);

    if (error != QContactManager::NoError)

        return ret;

    if (filter.type() == QContactFilter::DefaultFilter)

        return all;

    for (int j = 0; j < all.count(); j++) {

        if (testFilter(filter, all.at(j))) {

            ret << all.at(j);

        }

    }

    return ret;

}

/*!

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

  If the list of detail definition names \a definitionRestrictions given is non-empty,

  the contact returned will contain at least those details which are of a definition whose name is

  contained in the \a definitionRestrictions list.

  Note that the returned contact may also contain other details, but this function guarantees that

  all details whose definition name is included in the given list of definition names \a definitionRestrictions

  will be included in the returned contact.

  The default implementation returns the entire contact.

  Any errors encountered should be stored to \a error.

 */

QContact QContactManagerEngine::contact(const QContactLocalId& contactId, const QStringList& definitionRestrictions, QContactManager::Error& error) const

{

    Q_UNUSED(contactId);

    Q_UNUSED(definitionRestrictions);

    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, QContactRelationshipFilter::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 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 (one of the destination contacts is also the source contact), or

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

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

  If the given \a relationship could not be saved in the database (due to backend limitations)

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

  If any destination contact manager URI is not set in the \a relationship, these will be

  automatically set to the URI of this manager, before the relationship is saved.

 */

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

{

    Q_UNUSED(relationship);

    error = QContactManager::NotSupportedError;

    return false;

}

/*!

  Saves the given \a relationships in the database and returns a list of error codes.  Any error which occurs will be saved in \a error.

 */

QList<QContactManager::Error> QContactManagerEngine::saveRelationships(QList<QContactRelationship>* relationships, QContactManager::Error& error)

{

    Q_UNUSED(relationships);

    error = QContactManager::NotSupportedError;

    return QList<QContactManager::Error>();

}

/*!

  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 priority of the relationship is ignored when determining existence of the relationship.

 */

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

{

    Q_UNUSED(relationship);

    error = QContactManager::DoesNotExistError;

    return false;

}

/*!

  Removes the given \a relationships from the database and returns a list of error codes.  Any error which occurs will be saved in \a error.

 */

QList<QContactManager::Error> QContactManagerEngine::removeRelationships(const QList<QContactRelationship>& relationships, QContactManager::Error& error)

{

    Q_UNUSED(relationships);

    error = QContactManager::DoesNotExistError;

    return QList<QContactManager::Error>();

}

/*!

  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();

}

/*!

  Returns a copy of the given contact \a contact with its display label set to \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.

 */

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

{

    QContact retn = contact;

    QContactDisplayLabel dl;

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

    setDetailAccessConstraints(&dl, QContactDetail::Irremovable);

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

    return retn;

}

/*!

  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;

}

/*!