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

**

** 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::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.

 */

{

}

/*!

 */

{

    Q_UNUSED(sortOrders);

    return QList<QContact>();

}

/*!

 */

{

    Q_UNUSED(contactId);

    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.

 */

{

    Q_UNUSED(contactId);

    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.

 */

{

    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.

 */

{

    Q_UNUSED(relationshipType);

    Q_UNUSED(participantId);

    Q_UNUSED(role);

    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 function will return \c false and the \a error will be set to \c QContactManager::InvalidRelationshipError.

 */

{

}

/*!

  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.

 */

{

}

/*!

 */

{

    Q_UNUSED(relationships);

}

/*!

  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.

 */

{

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

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

        }

    }

    return QString();

}

/*!

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

 */

{

    QContactDisplayLabel dl;

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

    setDetailAccessConstraints(&dl, QContactDetail::Irremovable);

}

/*!

  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;

}

/*!