// Copyright (c) 2006-2009 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:
//

/**
 @file
 @publishedPartner
 @released
*/

#ifndef MMTPSTORAGEMGR_H
#define MMTPSTORAGEMGR_H

#include <f32file.h>

#include <mtp/cmtpstoragemetadata.h>
#include <mtp/mtpstoragemgrquerytypes.h>

class CMTPTypeString;

/** 
Defines the MTP data provider framework storage manager interface. The storage 
manager controls the allocation of physical and logical MTP StorageIDs, and 
their mapping to storage media, such as Symbian OS file system drives.

MTP StorageIDs are represented as unsigned 32-bit integers and are subdivided 
into two 16-bit fields. The most significant 16-bits represents the physical 
StorageID and the least significant 16-bits represents the StorageID of a 
logical partition of that physical storage. 
@publishedPartner
@released
*/
class MMTPStorageMgr
    {
public:
    
    /**
    Creates a new logical MTP StorageID partition on the specified Symbian OS 
    file system drive, to be owned and managed by the specified data provider.
    @param aDataProviderId The identifier of the data provider which will be 
    responsible for the logical MTP StorageID.
    @param aDriveNumber The Symbian OS file system drive on which the logical 
    MTP StorageID partition is to be created.
    @return The fully formed MTP StorageID of the new logical storage 
    partition.
    @param aStorage The storage meta-data. This must minimally specify the 
    @see EStorageSystemType and @see EStorageSuid elements. The 
    @see EStorageSystemType must match that of the corresponding physical 
    MTP StorageID. If @see EStorageSystemType is specified as 
    @see ESystemTypeDefaultFileSystem then @see EStorageSuid is validated as a 
    fully formed file system folder path (e.g. "C:\Media") which must 
    correspond to the specified file system drive.
    @leave KErrAlreadyExists, if the storage SUID is already defined.
    @leave KErrArgument if @see EStorageSystemType is not 
    @see ESystemTypeDefaultFileSystem, or if @see EStorageSuid is not a valid
    file system folder path, or does not match the specified drive.
    @leave KErrNotFound if the specified drive does not exist.
    @leave KErrPathNotFound, if @see EStorageSystemType is 
    @see ESystemTypeDefaultFileSystem and the path specified by 
    @see EStorageSuid does not exist on the Symbian OS filesystem. 
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual TUint32 AllocateLogicalStorageIdL(TUint aDataProviderId, TDriveNumber aDriveNumber, const CMTPStorageMetaData& aStorage) = 0;
    
    /**
    Creates a new logical MTP StorageID partition on the specified physical MTP
    StorageID, to be owned and managed by the specified data provider.
    @param aDataProviderId The identifier of the data provider which will be 
    responsible for the logical MTP StorageID.
    @param aPhysicalStorageId The physical MTP StorageID on which the logical 
    MTP StorageID partition is to be created.
    @param aStorage The storage meta-data. This must minimally specify the 
    @see EStorageSystemType and @see EStorageSuid elements. The 
    @see EStorageSystemType must match that of the corresponding physical 
    MTP StorageID. If @see EStorageSystemType is specified as 
    @see ESystemTypeDefaultFileSystem then @see EStorageSuid is validated as a 
    fully formed file system folder path (e.g. "C:\Media") which must 
    correspond to the specified file system drive.
    @return The fully formed MTP StorageID of the new logical storage 
    partition.
    @leave KErrAlreadyExists, if the storage SUID is already defined.
    @leave KErrArgument if @see EStorageSystemType is not 
    @see ESystemTypeDefaultFileSystem, or if @see EStorageSuid is not a valid
    file system folder path, or does not match the specified drive.
    @leave KErrNotFound if the specified physical StorageID does not exist.
    @leave KErrPathNotFound, if @see EStorageSystemType is 
    @see ESystemTypeDefaultFileSystem and the path specified by 
    @see EStorageSuid does not exist on the Symbian OS filesystem. 
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual TUint32 AllocateLogicalStorageIdL(TUint aDataProviderId, TUint32 aPhysicalStorageId, const CMTPStorageMetaData& aStorage) = 0;
    
    /**
    Creates a new physical MTP StorageID to be owned and managed by the 
    specified data provider.
    @param aDataProviderId The identifier of the data provider which will be 
    responsible for the physical MTP StorageID.
    @param aStorage The storage meta-data. 
    @return The physical MTP StorageID.
    @leave KErrAlreadyExists, if the storage SUID is already defined.
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual TUint32 AllocatePhysicalStorageIdL(TUint aDataProviderId, const CMTPStorageMetaData& aStorage) = 0;
    
    /**
    Releases the specified fully formed logical MTP StorageID. 
    @param aDataProviderId The identifier of the data provider which is 
    responsible for the logical MTP StorageID.
    @param aLogicalStorageId The fully formed logical MTP StorageID to be 
    deallocated.
    @return KErrNone, if successful.
    @return KErrNotFound, if the specified logical MTP StorageID is not 
    defined.
    @return KErrAccessDenied, if the specified data provider is not the owner of
    the specified logical MTP StorageID.
    @return one of the system wide error codes, if a processing failure occurs.
    */
    virtual TInt DeallocateLogicalStorageId(TUint aDataProviderId, TUint32 aLogicalStorageId) = 0;
    
    /**
    Releases all logical MTP StorageIDs which represent partitions of the 
    specified physical MTP StorageID and which are owned by the specified data 
    provider.
    @param aDataProviderId The identifier of the data provider which is 
    responsible for the logical MTP StorageIDs.
    @param aPhysicalStorageId The physical MTP StorageID.
    */
    virtual void DeallocateLogicalStorageIds(TUint aDataProviderId, TUint32 aPhysicalStorageId) = 0;
    
    /**
    Releases the specified physical MTP StorageID, along with all associated
    logical storage partititions. 
    @param aDataProviderId The identifier of the data provider which is 
    responsible for the physical MTP StorageID.
    @param aPhysicalStorageId The physical MTP StorageID to be released.
    @return KErrNone if successful.
    @return KErrNotFound, if the specified sical MTP StorageID is not 
    defined.
    @return KErrAccessDenied if the specified data provider is not the owner of
    the specified physical MTP StorageID.
    @return one of the system wide error codes, if a processing failure occurs.
    */
    virtual TInt DeallocatePhysicalStorageId(TUint aDataProviderId, TUint32 aPhysicalStorageId) = 0;

    /**
    Provides the default MTP StorageID, as determined by the value of the 
    @see MTPFrameworkConfig::EDefaultStorageDrive framework configurability 
    parameter. This may either be a physical or fully formed logical MTP 
    StorageID, depending on the value of the 
    @see MTPFrameworkConfig::ELogicalStorageIdsAllocationEnable framework 
    configurability parameter.
    @return The default MTP StorageID.
    */
    virtual TUint32 DefaultStorageId() const = 0;

    /**
    Provides the Symbian OS drive number associated with the specified MTP 
    StorageID. 
    @param aStorageId The physical or fully formed logical MTP StorageID.
    @return The Symbian OS drive number associated with the specified MTP 
    StorageID.
    @return KErrNotFound, if the MTP StorageID does not exist, or is not 
    associated with a Symbian OS drive number.
    */
    virtual TInt DriveNumber(TUint32 aStorageId) const = 0;

    /**
    Provides the fully formed MTP StorageID created by the MTP data provider 
    framework on the specified Symbian OS drive. If the 
    @see MTPFrameworkConfig::ELogicalStorageIdsAllocationEnable framework 
    configurability parameter is set, then an MTP StorageID is created on each 
    of the available Symbian OS file system drives as they become available. If
    not set then the creation of all logical MTP StorageIDs is deferred to the 
    active data providers.
    @param aDriveNumber The drive number for which the corresponding logical
    MTP StorageID is required.
    @return The fully formed MTP StorageID of the logical storage which 
    corresponds to the specified Symbian OS drive number.
    @return KErrNotFound, if the Symbian OS drive number does not correspond 
    to an MTP data provider framework created default logical MTP StorageID.
    */
    virtual TInt32 FrameworkStorageId(TDriveNumber aDriveNumber) const = 0;
    
    /**
    Provides an ordered list of the Symbian OS file system drives which are
    available for use as MTP storages. This comprises the sub-set of available
    Symbian OS file system drives which are left exposed by the the @see
    MTPFrameworkConfig::EExcludedStorageDrives framework configurability 
    parameter.
    @param aDrives On succesful completion, the list of available Symbian OS 
    file system drives.
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual void GetAvailableDrivesL(RArray<TDriveNumber>& aDrives) const = 0;
    
    /**
    Provides an ordered list of the storage meta-data for all available logical
    MTP StorageIDs which match the specified query criteria. 
    @param aParams The query parameters.
    @param aStorages On succesful completion, the list of matching storage 
    meta-data. 
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual void GetLogicalStoragesL(const TMTPStorageMgrQueryParams& aParams, RPointerArray<const CMTPStorageMetaData>& aStorages) const = 0;
    
    /**
    Provides an ordered list of the storage meta-data for all available 
    physical MTP StorageIDs which match the specified query criteria. 
    @param aParams The query parameters.
    @param aStorages On succesful completion, the list of matching storage 
    meta-data. 
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual void GetPhysicalStoragesL(const TMTPStorageMgrQueryParams& aParams, RPointerArray<const CMTPStorageMetaData>& aStorages) const = 0;
    
    /**
    Provides the logical StorageID component (i.e. the least significant 
    16-bits) of the specified 32-bit MTP StorageID.
    @param aStorageId The MTP StorageID.
    @return The logical MTP StorageID, if successful.
    */
    virtual TUint32 LogicalStorageId(TUint32 aStorageId) const = 0;
    
    /**
    Provides the the fully formed 32-bit logical StorageID associated with the
    specified storage System Unique IDentifier (SUID).
    @param aStorageId The MTP StorageID.
    @return If successful, the fully formed MTP StorageID of the logical 
    storage which corresponds to the specified storage UID.
    KErrNotFound, if the specified storage UID is not defined.
    */
    virtual TInt32 LogicalStorageId(const TDesC& aStorageSuid) const = 0;

    /**
    Provides the physical MTP StorageID associated with the specified 
    Symbian OS drive number.
    @param aDriveNumber The Symbian OS drive number.
    @return If successful, the physical MTP StorageID associated with the 
    specified Symbian OS drive number.
    KErrNotFound, if the Symbian OS drive number is not associated with an MTP
    StorageID.
    */
    virtual TInt32 PhysicalStorageId(TDriveNumber aDriveNumber) const = 0;
   
    /**
    Provides the physical StorageID component (i.e. the most significant 
    16-bits) of the specified 32-bit MTP StorageID.
    @param aStorageId The MTP StorageID.
    @return The physical MTP StorageID.
    */
    virtual TUint32 PhysicalStorageId(TUint32 aStorageId) const = 0;
    
    /**
    Provides the storage meta-data for the specified logical MTP StorageID.
    @param aStorageId The physical or fully formed logical MTP StorageID.
    @leave KErrNotFound if the specified StorageID does not exist.
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual const CMTPStorageMetaData& StorageL(TUint32 aStorageId) const = 0;
   
    /**
    Constructs a fully formed 32-bit MTP StorageID from the specified physical 
    and logical MTP StorageIDs.
    @param aPhysicalStorageId The physical MTP StorageID. The least significant
    16-bits are ignored.
    @param aLogicalStorageId The logical MTP StorageID. The most significant 
    16-bits are ignored.
    @return The fully formed 32-bit MTP StorageID.
    */
    virtual TUint32 StorageId(TUint32 aPhysicalStorageId, TUint32 aLogicalStorageId) const = 0;
    
    /**
    Indicates if the specified StorageID is defined.
    @param aStorageId The physical or fully formed logical MTP StorageID.
    @return ETrue if the StorageID exists, otherwise EFalse.
    */
    virtual TBool ValidStorageId(TUint32 aStorageId) const = 0;

    /**
    Generates an MTP volume identifier string of which the leading 128 
    characters are guaranteed to be unique amongst all storages presented to a 
    conected MTP initiator.
    @param aDataProviderId The identifier of the data provider.
    @param aStorageId The MTP StorageID associated with the volume identifier.
    @param aVolumeIdSuffix The data provider supplied volume identifier string.
    @return The MTP volume identifier string. Ownership IS transferred.
    @leave KErrAccessDenied if the specified data provider is not the owner of
    the specified StorageID.
    @leave KErrNotFound if the specified MTP StorageID does not exist.
    @leave One of the system wide error codes, if a processing failure occurs.
    */
    virtual CMTPTypeString* VolumeIdL(TUint aDataProviderId, TUint32 aStorageId, const TDesC& aVolumeIdSuffix) const = 0;
    };
    
#endif // MMTPSTORAGEMGR_H