/*

 * 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