/*
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Destination interface class.
*
*/

#ifndef DESTINATION_H
#define DESTINATION_H

// System includes
#include <cmconnectionmethod.h>
#include <cmmanagerdef.h>
#include <E32def.h>
#include <e32base.h>
#include <metadatabase.h>

// FORWARD DECLARATIONS
class CCmManagerImpl;
class CCmDestinationData;
class CGulIcon;

/**
 *  RCmDestination is for setting/getting values of a network destination.
 *
 *  @lib cmmanager.lib
 *  @since S60 v3.2
 */
NONSHARABLE_CLASS(RCmDestination)
    {
    //=====================================================================
    // Constructors/Destructors
    // 
    public:
    
        /** Default constructor. */
        IMPORT_C RCmDestination();

        IMPORT_C ~RCmDestination();

        IMPORT_C RCmDestination(const RCmDestination& aCmDestination);
        
    //=====================================================================
    // API functions
    public:

        /**
        * Close the session.
        *
        * @since S60 3.2
        */
        IMPORT_C void Close();
            
        /**
        * Returns the number of connection methods of the destination
        *
        * @since 3.2
        * @return the number of connection methods belonging to a destination        
        */                 
        IMPORT_C TInt ConnectionMethodCount() const;
        
        /**
        * Returns a reference to the connection method. 
        * The index must be less than the return value of 
        * ConnectionMethodCount().
        *
        * @since 3.2
        * @param anIndex
        * @return a connection method
        */        
        IMPORT_C RCmConnectionMethod ConnectionMethodL( TInt anIndex ) const;

        /**
        * Returns the connection method with the ECmId.
        * Leaves with KErrNotFound if not found.
        * @param aCmId unique id of the requested connection method.
        * @return connection method
        */
        IMPORT_C RCmConnectionMethod ConnectionMethodByIDL( 
                                                        TInt aCmId ) const;

        /**
        * Return the priority of the passed connection method
        *
        * @since 3.2
        * @param aCCMItem connection method
        * @return the priority of the queried connection method 
        */
        IMPORT_C TUint PriorityL(const RCmConnectionMethod& aCCMItem ) const;
        
        //Getting attributes

        /**
        * Returns the destination's Name attribute
        * HBuf ownership is passed to the caller
        *
        * @since 3.2
        * @return HBufC* Passes returned value's ownership to the caller
        */      
        IMPORT_C HBufC* NameLC() const;                        
        
        /**
        * Returns the destination's Id attribute
        *
        * @since 3.2
        * @return the destination's id
        */                    
        IMPORT_C TUint32 Id() const;
        
        /**
        * Returns the destination's ElementId attribute
        *
        * @since 3.2
        * @return the destination's element id        
        */            
        IMPORT_C TUint32 ElementId() const;        
                
        /**
        * Returns the Icon pointer
        * This function leaves if the client does not have a valid UI context
        *
        * @since 3.2
        * @return the destination icon  
        */ 
        IMPORT_C CGulIcon* IconL() const;

        /**
        * Returns the Metadata
        *
        * @since 3.2
        * @param aMetaField the meta data field to query
        * @return the value of the requested field        
        */            
        IMPORT_C TUint32 MetadataL( CMManager::TSnapMetadataField aMetaField ) const;
    
        /**
        * Return the protection level of the destination.
        *
        * @since 3.2              
        * @return protection level of the destination
        */
        IMPORT_C CMManager::TProtectionLevel ProtectionLevel() const;

        /**
        * Returns if there's a connection created with any of the destination's
        * connection method.
        *
        * @since 3.2        
        * @return ETrue if there's a connection with any of the destination's
        * connection method.
        */
        IMPORT_C TBool IsConnectedL() const;
        
        /**
        * Returns whether the destination is hidden or not.
        *
        * @since 3.2
        * @return ETrue if the destination is hidden
        */
        IMPORT_C TBool IsHidden() const;

        /**
        * checks if destinations are the same 
        * 
        * @since S60 3.2
        * @param aDestination the destination being compared
        * @return ETrue if the destinations are the same
        */
        IMPORT_C TBool operator==(const RCmDestination& aDestination ) const;
        
        /**
        * checks if destinations are not the same 
        * 
        * @since S60 3.2
        * @param aDestination the destination being compared
        * @return ETrue if the destinations are different
        */
        IMPORT_C TBool operator!=(const RCmDestination& aDestination ) const;

        /**
        * assignment operator 
        * 
        * @since S60 3.2
        * @param aDestination the destination being compared
        * @return RCmDestination
        */
        IMPORT_C RCmDestination& operator=(const RCmDestination& 
                                                    aCmDestination);

                /**
        * Create a connection method that belongs to this destination.
        * @param aImplementationUid - implementation uid (bearer type) of the 
        * connection method to be created
        * @return newly created connection method
        */
        IMPORT_C RCmConnectionMethod CreateConnectionMethodL( TUint32 aBearerType );

        /*
        * Adds an existing connection method to a destination
        * @param aConnectionMethod Connection method to be added
        * @return index in the Connection Method list
        */
        IMPORT_C TInt AddConnectionMethodL( RCmConnectionMethod aConnectionMethod );            

        /*
        * Embeds an existing destination into this destination.
        * @param RCmDestination - Destination to be embedded
        * @return TInt - index in the Connection Method list
        */
        IMPORT_C TInt AddEmbeddedDestinationL( const RCmDestination& aDestination );     

        /**
        * Remove a connection method from a destination and delete it
        * on update. 
        * Exception: conenction method is not deleted  if it's referenced 
        * from any other destination.
        * @param aConnectionMethod the connection method to be deleted.
        */
        IMPORT_C void DeleteConnectionMethodL( RCmConnectionMethod& aConnectionMethod );

        /**
        * Remove connection method from the destination
        * @param aConnectionMethod connection method to be removed
        */
        IMPORT_C void RemoveConnectionMethodL( RCmConnectionMethod aConnectionMethod );


        /**
        * Set the connection method's priority based on the passed index.
        * @param aCCMItem the connection method item
        * @param aIndex the new priority of the connection method in the 
        * destination
        */
        IMPORT_C void ModifyPriorityL( RCmConnectionMethod& aCCMItem, 
                                       TUint aIndex );

        /**
        * Set the destination's name
        * @param aDestinationName new name of the destination
        */
        IMPORT_C void SetNameL( const TDesC& aName );

        /**
        * Set the destination's icon index.
        * This fucton leaves if the client does not have a valid UI context
        * @param aIconIndex new icon index of the destination
        */
        IMPORT_C void SetIconL( TUint32 anIndex );

        /**
        * Set the Metadata
        * @param aMetaField field to be modified
        * @param aValue value to be set
        */            
        IMPORT_C void SetMetadataL( CMManager::TSnapMetadataField aMetaField, 
                                    TUint32 aValue );

        /**
        * Set the protection level of the destination.
        * @param aProtLevel new protection level 
        */
        IMPORT_C void SetProtectionL( CMManager::TProtectionLevel aProtLevel );

        /**
        * Set if the destination is hidden or not.
        * @param aHidden - ETrue if destination is hidden
        */
        IMPORT_C void SetHiddenL( TBool aHidden );         

        /**
        * Update all values of the destination and its connection method.
        * Nothing if stored, if update leaves due to any reason.
        */
        IMPORT_C void UpdateL();               

        /**
        * Delete destination and its connection methods from CommsDat.
        * Connection methods that belong to other destination, too, are
        * not deleted.
        */
        IMPORT_C void DeleteLD();

        /**
        * Create a connection method with given id that belongs to this destination.
        * @param aImplementationUid - implementation uid (bearer type) of the 
        * connection method to be created
        * @return newly created connection method or leaves with
        * KErrAlreadyExists if there exists CM with the same Id.
        */
        IMPORT_C RCmConnectionMethod CreateConnectionMethodL( TUint32 aBearerType,
                                                              TUint32 aConnMethId );


    //=======================================================================
    // Member variables
    //
    private: 
        
        /**
         * the implementation class
         */
        CCmDestinationData* iDestinatonData;

    private:
    
        friend class RCmManager;
        friend class RCmConnectionMethod;
    };
    

#endif // DESTINATION_H