diff -r 000000000000 -r d0791faffa3f mtpfws/mtpfw/dataproviders/dataproviderapi/interface/mmtpstoragemgr.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mtpfws/mtpfw/dataproviders/dataproviderapi/interface/mmtpstoragemgr.h Tue Feb 02 01:11:40 2010 +0200 @@ -0,0 +1,306 @@ +// 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 + +#include +#include + +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& 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& 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& 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