/*

* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Virtual Phonebook manager class for contact attributes.

*

*/

#ifndef MVPBKCONTACTATTRIBUTEMANAGER_H

#define MVPBKCONTACTATTRIBUTEMANAGER_H

// INCLUDE FILES

#include <e32cmn.h>

#include <e32std.h>

// FORWARD DECLARATIONS

class MVPbkContactOperationBase;

class MVPbkContactLink;

class MVPbkContactFindObserver;

class MVPbkStoreContact;

class MVPbkStoreContactField;

class MVPbkContactAttribute;

class MVPbkStoreContactFieldCollection;

/**

 * Virtual Phonebook single attribute presense observer interface.

 */

class MVPbkSingleAttributePresenceObserver

    {

    public:

        /**

         * Attribute presence query operation completed.

         * @param aOperation    Contact operation that was completed.

         * @param aResult   Result of the query.

         */

        virtual void AttributePresenceOperationComplete(

            MVPbkContactOperationBase& aOperation, TBool aResult ) = 0;

        /**

         * Attribute presence query operation failed.

         * @param aOperation    Contact operation that failed.

         * @param aError        Error code.

         */

        virtual void AttributePresenceOperationFailed(

            MVPbkContactOperationBase& aOperation, TInt aError) = 0;

        /**

         * Returns an extension point for this interface or NULL.

         * @param aExtensionUid Extension identifier.

         * @return Extension object.

         */

        virtual TAny* AttributeSinglePresenceOperationExtension(

            TUid /*aExtensionUid*/) { return NULL; }

    protected:  // Destructor

        /**

         * Destructor.

         */

        virtual ~MVPbkSingleAttributePresenceObserver() { }

    };

/**

 * Virtual Phonebook multiple attribute presense observer interface.

 */

class MVPbkMultiAttributePresenceObserver

    {

    public:

        /**

         * Attribute presence query operation completed.

         * @param aOperation    Contact operation that was completed.

         * @param aResult   Fields with attribute aAttribute, 

         *                  or NULL if there is no fields with that 

         *                  attribute in this contact.

         */

        virtual void AttributePresenceOperationComplete(

            MVPbkContactOperationBase& aOperation, 

            MVPbkStoreContactFieldCollection* aResult) = 0;

        /**

         * Attribute presence query operation failed.

         * @param aOperation    Contact operation that failed.

         * @param aError        Error code.

         */

        virtual void AttributePresenceOperationFailed(

            MVPbkContactOperationBase& aOperation, TInt aError) = 0;

        /**

         * Returns an extension point for this interface or NULL.

         * @param aExtensionUid Extension identifier.

         * @return Extension object.

         */

        virtual TAny* AttributeMultiPresenceOperationExtension(

            TUid /*aExtensionUid*/) { return NULL; }

    protected:  // Destructor

        /**

         * Destructor.

         */

        virtual ~MVPbkMultiAttributePresenceObserver() { }

    };

/**

 * Virtual Phonebook Set attribute observer interface.

 */

class MVPbkSetAttributeObserver

    {

    public:

        /**

         * Attribute operation completed.

         * @param aOperation    Contact operation that was completed.

         */

        virtual void AttributeOperationComplete(

            MVPbkContactOperationBase& aOperation) = 0;

        /**

         * Attribute operation failed.

         * @param aOperation    Contact operation that failed.

         * @param aError        Error code.

         */

        virtual void AttributeOperationFailed(

            MVPbkContactOperationBase& aOperation, TInt aError) = 0;

        /**

         * Returns an extension point for this interface or NULL.

         * @param aExtensionUid Extension identifier.

         * @return Extension object.

         */

        virtual TAny* SetAttributeObserverExtension(

                TUid /*aExtensionUid*/) { return NULL; }

    protected:  // Destructor

        /**

         * Destructor.

         */

        ~MVPbkSetAttributeObserver() { }

    };

/**

 * Abstract interface for contact attribute manager.

 *

 * Contact attribute manager can be used to set global attributes such as speed dials 

 * for contacts or fields of contacts. The attributes can be stored in external 

 * databases so that some kind of mapping is maintained between contacts and 

 * attributes. This interface provides unified access to all global attributes.

 */

class MVPbkContactAttributeManager

    {

    public:

        /**

         * Destructor.

         */

        virtual ~MVPbkContactAttributeManager() { }

        /**

         * Lists all contacts having the requested type of 

         * attribute asynchronously.

         *

         * @param aAttributeType    Type of the attribute to search for.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the process.

         */

        virtual MVPbkContactOperationBase* ListContactsL(

                TUid aAttributeType, 

                MVPbkContactFindObserver& aObserver) = 0;

        /**

         * Lists all contacts matching the given attribute asynchronously.

         *

         * @param aAttribute    Attribute prototype to match against.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the process.

         */

        virtual MVPbkContactOperationBase* ListContactsL(

                const MVPbkContactAttribute& aAttribute, 

                MVPbkContactFindObserver& aObserver) = 0;

        /**

         * Checks if the given contact has the given attribute.

         *

         * @param aAttributeType    Type of the attribute to check for.

         * @param aContact  Contact whose attributes are checked.

         * @return ETrue if aContact has an attribute of aAttributeType,

         *         EFalse otherwise.

         */

        virtual TBool HasContactAttributeL(

                TUid aAttributeType, 

                const MVPbkStoreContact& aContact) const = 0;

        /**

         * Checks if the given contact has an attribute matching the 

         * given attribute.

         *

         * @param aAttribute    Attribute prototype to match against.

         * @param aContact  Contact whose attributes are checked.

         * @return ETrue if aContact has an attribute matching the aAttribute,

         *         EFalse otherwise.

         */

        virtual TBool HasContactAttributeL(

                const MVPbkContactAttribute& aAttribute, 

                const MVPbkStoreContact& aContact) const = 0;

        /**

         * Checks if the given contact field has the given attribute.

         * 

         * @param aAttributeType    Type of the attribute to check for.

         * @param aField    Field whose attributes are checked.

         * @return ETrue if aField has an attribute of aAttributeType,

         *         EFalse otherwise.

         */

        virtual TBool HasFieldAttributeL(

                TUid aAttributeType, 

                const MVPbkStoreContactField& aField) const = 0;

        /**

         * Checks if the given contact field has an attribute matching 

         * the given attribute.

         *

         * @param aAttribute Attribute prototype to match against.

         * @param aField Contact field whose attribute is checked.

         * @return ETrue if aField has an attribute matching the aAttribute,

         *         EFalse otherwise.

         */

        virtual TBool HasFieldAttributeL(

                const MVPbkContactAttribute& aAttribute, 

                const MVPbkStoreContactField& aField) const = 0;

        /**

         * Returns fields with attribute type aAttributeType, or 

         * NULL if there is no fields with that attribute in this 

         * contact.

         *

         * @param aAttributeType Type of the attribute to find for.

         * @param aContact Contact whose attributes are checked.

         */

        virtual MVPbkStoreContactFieldCollection* FindFieldsWithAttributeLC(

                TUid aAttributeType,

                MVPbkStoreContact& aContact) const = 0;

        /**

         * Returns fields with attribute aAttribute, or NULL if there is no

         * fields with that attribute in this contact.

         *

         * @param aAttribute Attribute prototype to match against.

         * @param aContact Contact whose attributes are checked.

         */

        virtual MVPbkStoreContactFieldCollection* FindFieldsWithAttributeLC(

                const MVPbkContactAttribute& aAttribute,

                MVPbkStoreContact& aContact) const = 0;

        /**

         * Finds the first field that has the aAttr and returns

         * a reference to the field or NULL if not found.

         *

         * Note: the returned reference will become invalid if 

         * MVPbkStoreContactFieldCollection::FieldAt is called for

         * different field. If this is a problem then use

         * MVPbkStoreContactField::CloneLC for permanent copy of

         * the field.

         *

         * @param aAttr The attribute that is looked for.

         * @param aContact  Contact whose fields are iterated.

         * @return Returns a reference to the field or NULL if not found.

         */

        virtual MVPbkStoreContactField* FindFieldWithAttributeL(

                const MVPbkContactAttribute& aAttr,

                MVPbkStoreContact& aContact) const = 0;

        /**

         * Asynchronously sets the contact attribute for the contact referred 

         * by the given contact link.

         *

         * @param aContactLink  Link to contact whose attribute to set.

         * @param aAttribute    Attribute to set for the contact.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */          

        virtual MVPbkContactOperationBase* SetContactAttributeL(

                const MVPbkContactLink& aContactLink, 

                const MVPbkContactAttribute& aAttribute,

                MVPbkSetAttributeObserver& aObserver) = 0;

        /**

         * Asynchronously sets the contact field attribute for the 

         * give contact field.

         *

         * @param aField    Contact field whose attribute to set.

         * @param aAttribute    Attribute to set for the contact field.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* SetFieldAttributeL(

                MVPbkStoreContactField& aField, 

                const MVPbkContactAttribute& aAttribute,

                MVPbkSetAttributeObserver& aObserver) = 0;

        /**

         * asynchronously removes the given attribute from the contact 

         * referred by the aContactLink.

         * 

         * @param aContactLink  Link to the contact whose attribute 

         *                      to remove.

         * @param aAttribute    Attribute to remove from the contact.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* RemoveContactAttributeL(

                const MVPbkContactLink& aContactLink, 

                const MVPbkContactAttribute& aAttribute,

                MVPbkSetAttributeObserver& aObserver) = 0;

        /**

         * asynchronously removes all attributes having the attribute 

         * type aAttributeType from the contact.

         * 

         * @param aContactLink  Link to the contact whose attribute 

         *                      to remove.

         * @param aAttributeType    Type of the attributes to remove 

         *                          from the contact.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* RemoveContactAttributeL(

                const MVPbkContactLink& aContactLink, 

                TUid aAttributeType,

                MVPbkSetAttributeObserver& aObserver) = 0;

        /**

         * Asynchronously removes the given attribute from the 

         * given contact field.

         *

         * @param aField    Field whose attribute to remove.

         * @param aAttribute    Attribute to remove from the contact field.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* RemoveFieldAttributeL(

                MVPbkStoreContactField& aField, 

                const MVPbkContactAttribute& aAttribute,

                MVPbkSetAttributeObserver& aObserver) = 0;

        /**

         * Asynchronously removes all attributes having the attribute 

         * type aAttributeType from the contact field.

         *

         * @param aField    Field whose attribute to remove.

         * @param aAttributeType    Type of the attributes to remove 

         *                          from the contact field.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* RemoveFieldAttributeL(

                MVPbkStoreContactField& aField, 

                TUid aAttributeType,

                MVPbkSetAttributeObserver& aObserver) = 0;

        /**

         * Checks if the given contact has the given attribute asynchronously.

         *

         * @param aAttributeType    Type of the attribute to check for.

         * @param aContact  Contact whose attributes are checked.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* HasContactAttributeL(

                TUid aAttributeType, 

                const MVPbkStoreContact& aContact,

                MVPbkSingleAttributePresenceObserver& aObserver) const = 0;

        /**

         * Checks if the given contact has an attribute matching the 

         * given attribute asynchronously.

         *

         * @param aAttribute    Attribute prototype to match against.

         * @param aContact  Contact whose attributes are checked.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* HasContactAttributeL(

                const MVPbkContactAttribute& aAttribute, 

                const MVPbkStoreContact& aContact,

                MVPbkSingleAttributePresenceObserver& aObserver) const = 0;

        /**

         * Checks if the given contact field has the given attribute 

         * asynchronously.

         * 

         * @param aAttributeType    Type of the attribute to check for.

         * @param aField    Field whose attributes are checked.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* HasFieldAttributeL(

                TUid aAttributeType, 

                const MVPbkStoreContactField& aField,

                MVPbkSingleAttributePresenceObserver& aObserver) const = 0;

        /**

         * Checks if the given contact field has an attribute matching 

         * the given attribute asynchronously.

         *

         * @param aAttribute Attribute prototype to match against.

         * @param aField Contact field whose attribute is checked.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* HasFieldAttributeL(

                const MVPbkContactAttribute& aAttribute, 

                const MVPbkStoreContactField& aField,

                MVPbkSingleAttributePresenceObserver& aObserver) const = 0;

        /**

         * Initiates an asynchronous operation, which finds the aAttribute type 

         * attributed fields from the contact.

         *

         * @param aAttributeType Type of the attribute to find for.

         * @param aContact Contact whose attributes are checked.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* FindFieldsWithAttributeL(

                TUid aAttributeType,

                MVPbkStoreContact& aContact,

                MVPbkMultiAttributePresenceObserver& aObserver) const = 0;

        /**

         * Initiates an asynchronous operation, which finds the aAttribute type 

         * attributed fields from the contact.

         *

         * @param aAttribute Attribute prototype to match against.

         * @param aContact Contact whose attributes are checked.

         * @param aObserver Observer for the asynchronous process.

         * @return Newly created handle to the operation.

         */

        virtual MVPbkContactOperationBase* FindFieldsWithAttributeL(

                const MVPbkContactAttribute& aAttribute,

                MVPbkStoreContact& aContact,

                MVPbkMultiAttributePresenceObserver& aObserver) const = 0;

        /**

         * Returns an extension point for this interface or NULL.

         * @param aExtensionUid Extension identifier.

         * @return Extension point or NULL

         */

        virtual TAny* ContactAttributeManagerExtension(

                TUid /*aExtensionUid*/) { return NULL; }

    };

#endif // MVPBKCONTACTATTRIBUTEMANAGER_H

// End of File