/*
* 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:  An API for SIM stores
*
*/



#ifndef MVPBKSIMCNTSTORE_H
#define MVPBKSIMCNTSTORE_H

//  INCLUDES
#include <e32std.h>
#include "VPbkSimStoreCommon.h"

// FORWARD DECLARATIONS
class MVPbkSimContactObserver;
class MVPbkSimStoreObserver;
class RVPbkSimFieldTypeArray;
class MVPbkSimCntView;
class MVPbkSimFindObserver;
class MVPbkSimContact;
class CVPbkETelCntConverter;
class MVPbkSimStoreOperation;
struct TVPbkGsmStoreProperty;
struct TVPbkUSimStoreProperty;
class CVPbkSimFieldTypeFilter;
class RVPbkStreamedIntArray;

// CLASS DECLARATION

/**
 *  An API for SIM contact stores.
 *
 */
class MVPbkSimCntStore
    {
    public: // Interface

        /**
         * Destructor.
         */
        virtual ~MVPbkSimCntStore() {}

        /**
         * Returns the store identifier
         *
         * @return The store identifier.
         */
        virtual TVPbkSimStoreIdentifier Identifier() const = 0;

        /**
         * Opens the store asynchronously.
         * Calls back the observers attached to this contact store when the
         * opening completes.
         *
         * @param aObserver Observer.
         */
        virtual void OpenL(
                MVPbkSimStoreObserver& aObserver ) = 0;

        /**
         * Closes this contact store from a single observer. The observer will
         * no longer receive events from this store.
         *
         * @param aObserver Observer.
         */
        virtual void Close(
                MVPbkSimStoreObserver& aObserver ) = 0;

        /**
         * Creates a new contact view that contains the contacts of this 
         * store.
         *
         * If the view is a shared view and it has already been created
         * then aSortOrder and aConstructionPolicy will be ignored.
         *
         * @param aSortOrder             The sort order for the view.
         * @param aConstructionPolicy    Defines the way the view
         *                               is constructed.
         * @param aFilter                Field type filter. The view
         *                               will contain only contacts
         *                               having the field types of the filter.
         *                               Ownership of the filter must be taken.
         * @return   A new contact view.
         */
        virtual MVPbkSimCntView* CreateViewL( 
                const RVPbkSimFieldTypeArray& aSortOrder,
                TVPbkSimViewConstructionPolicy aConstructionPolicy,
                const TDesC& aViewName,
                CVPbkSimFieldTypeFilter* aFilter ) = 0;
        
        /**
         * Returns a reference to the contact in ETel format or NULL.
         *
         * Client can not save the reference for later use because
         * next call to ContactAtL can invalidate the saved reference.
         *
         * @param aSimIndex The index of the contact in the store.
         * @return The ETel contact or NULL if the given index is empty
         */
        virtual const TDesC8* AtL( TInt aSimIndex ) = 0;
        
        /**
         * Returns a reference to the contact or NULL.
         *
         * Client can not save the reference for later use because
         * next call to ContactAtL can invalidate the saved reference.
         *
         * @param aSimIndex The index of the contact in the store.
         * @return The contact or NULL if the given index is empty
         */
        virtual const MVPbkSimContact* ContactAtL( TInt aSimIndex ) = 0;

        /**
         * Saves a contact asynchronously into the store.
         * It's not possible to call this if saving is already in progress.
         *
         * @param aData     The contact data in the format defined
         *                  by the Symbian MM ETel (CPhoneBookBuffer).
         * @param aSimIndex The index for the contact or 
         *                  VPbkSimStoreImpl::KFirstFreeSimIndex if
         *                  new contact (after saving the index
         *                  contains the new index).
         * @param aObserver The observer that is notified after saving.
         * @return a handle to an asynchrnous operation. Client
         *         has the ownership and can cancel the operation
         *         by deleting the operation
         */
        virtual MVPbkSimStoreOperation* SaveL(
                const TDesC8& aData,
                TInt& aSimIndex, 
                MVPbkSimContactObserver& aObserver ) = 0;

        /**
        * Deletes a contacts asynchronously from the store.
        * It's not possible to call this if deleting is already in progress.
        *
        * @param aSimIndexes array of contacts to be delete
        * @param aObserver the observer that is notified after deleting.
        * @return a handle to an asynchrnous operation. Client
        *         has the ownership and can cancel the operation
        *         by deleting the operation
        * @exception operation completes with KErrArgument if aSimIndexes
        *            is empty or contains only invalid SIM indexes.
        */
        virtual MVPbkSimStoreOperation* DeleteL( 
                RVPbkStreamedIntArray& aSimIndexes,
                MVPbkSimContactObserver& aObserver ) = 0;

        /**
         * Fills the GSM store properties
         *
         * @param aGsmProperties The GSM store properties.
         * @return  KErrNone if properties were successfully set. General error code.
         */
        virtual TInt GetGsmStoreProperties( 
                TVPbkGsmStoreProperty& aGsmProperties ) const = 0;

        /**
         * Fills the USIM store properties. If the store doesn't support
         * USIM properties then all the values are KVPbkSimStorePropertyUndefined
         *
         * @param aUSimProperties The USIM store properties.
         * @return  KErrNone if properties were successfully set. General error code.
         */
        virtual TInt GetUSimStoreProperties( 
                TVPbkUSimStoreProperty& aUSimProperties ) const = 0 ;
        
        /**
         * Returns the contact converter that is used to convert
         * native contacts to ETel contacts an vice versa.
         *
         * @return  A contact converter for native contact versus
         *          ETel contact conversion.
         */
        virtual const CVPbkETelCntConverter& ContactConverter() const = 0;
        
        /**
         * Finds a contact match for the phone number.
         *
         * @param aPhoneNumber       The phone number to look for.
         * @param aMaxMatchDigits    The maximum amount of digits to compare
         *                           from the end of the number.
         * @param aObserver          The observer that is notified
         *                           with results.
         * @return   Match phone number operation.
        */
        virtual MVPbkSimStoreOperation* CreateMatchPhoneNumberOperationL(
                const TDesC& aPhoneNumber,
                TInt aMaxMatchDigits, 
                MVPbkSimFindObserver& aObserver ) = 0;
        
        /**
         * Finds a contact match for a string.
         *
         * @param aStringToFind The string to look for.
         * @param aFieldTypes   The types of the fields to find from.
         * @param aObserver     The observer that is notified with results.
         * @return  Find operation.
         */
        virtual MVPbkSimStoreOperation* CreateFindOperationL( 
                const TDesC& aStringToFind,
                RVPbkSimFieldTypeArray& aFieldTypes,
                MVPbkSimFindObserver& aObserver ) = 0;
        
        /**
         * Returns the maximum phonenumber length defined in Virtual Phonebook
         * Central Repository settings
         *
         * @return the system maximum length for phonenumber
         */
        virtual TInt SystemPhoneNumberMaxLength() const = 0;
    };

#endif      // MVPBKSIMCNTSTORE_H
            
// End of File