1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @released

    20 */

    21 

    22 #ifndef MMTPSTORAGEMGR_H

    23 #define MMTPSTORAGEMGR_H

    24 

    25 #include <f32file.h>

    26 

    27 #include <mtp/cmtpstoragemetadata.h>

    28 #include <mtp/mtpstoragemgrquerytypes.h>

    29 

    30 class CMTPTypeString;

    31 

    32 /** 

    33 Defines the MTP data provider framework storage manager interface. The storage 

    34 manager controls the allocation of physical and logical MTP StorageIDs, and 

    35 their mapping to storage media, such as Symbian OS file system drives.

    36 

    37 MTP StorageIDs are represented as unsigned 32-bit integers and are subdivided 

    38 into two 16-bit fields. The most significant 16-bits represents the physical 

    39 StorageID and the least significant 16-bits represents the StorageID of a 

    40 logical partition of that physical storage. 

    41 @publishedPartner

    42 @released

    43 */

    44 class MMTPStorageMgr

    45     {

    46 public:

    47     

    48     /**

    49     Creates a new logical MTP StorageID partition on the specified Symbian OS 

    50     file system drive, to be owned and managed by the specified data provider.

    51     @param aDataProviderId The identifier of the data provider which will be 

    52     responsible for the logical MTP StorageID.

    53     @param aDriveNumber The Symbian OS file system drive on which the logical 

    54     MTP StorageID partition is to be created.

    55     @return The fully formed MTP StorageID of the new logical storage 

    56     partition.

    57     @param aStorage The storage meta-data. This must minimally specify the 

    58     @see EStorageSystemType and @see EStorageSuid elements. The 

    59     @see EStorageSystemType must match that of the corresponding physical 

    60     MTP StorageID. If @see EStorageSystemType is specified as 

    61     @see ESystemTypeDefaultFileSystem then @see EStorageSuid is validated as a 

    62     fully formed file system folder path (e.g. "C:\Media") which must 

    63     correspond to the specified file system drive.

    64     @leave KErrAlreadyExists, if the storage SUID is already defined.

    65     @leave KErrArgument if @see EStorageSystemType is not 

    66     @see ESystemTypeDefaultFileSystem, or if @see EStorageSuid is not a valid

    67     file system folder path, or does not match the specified drive.

    68     @leave KErrNotFound if the specified drive does not exist.

    69     @leave KErrPathNotFound, if @see EStorageSystemType is 

    70     @see ESystemTypeDefaultFileSystem and the path specified by 

    71     @see EStorageSuid does not exist on the Symbian OS filesystem. 

    72     @leave One of the system wide error codes, if a processing failure occurs.

    73     */

    74     virtual TUint32 AllocateLogicalStorageIdL(TUint aDataProviderId, TDriveNumber aDriveNumber, const CMTPStorageMetaData& aStorage) = 0;

    75     

    76     /**

    77     Creates a new logical MTP StorageID partition on the specified physical MTP

    78     StorageID, to be owned and managed by the specified data provider.

    79     @param aDataProviderId The identifier of the data provider which will be 

    80     responsible for the logical MTP StorageID.

    81     @param aPhysicalStorageId The physical MTP StorageID on which the logical 

    82     MTP StorageID partition is to be created.

    83     @param aStorage The storage meta-data. This must minimally specify the 

    84     @see EStorageSystemType and @see EStorageSuid elements. The 

    85     @see EStorageSystemType must match that of the corresponding physical 

    86     MTP StorageID. If @see EStorageSystemType is specified as 

    87     @see ESystemTypeDefaultFileSystem then @see EStorageSuid is validated as a 

    88     fully formed file system folder path (e.g. "C:\Media") which must 

    89     correspond to the specified file system drive.

    90     @return The fully formed MTP StorageID of the new logical storage 

    91     partition.

    92     @leave KErrAlreadyExists, if the storage SUID is already defined.

    93     @leave KErrArgument if @see EStorageSystemType is not 

    94     @see ESystemTypeDefaultFileSystem, or if @see EStorageSuid is not a valid

    95     file system folder path, or does not match the specified drive.

    96     @leave KErrNotFound if the specified physical StorageID does not exist.

    97     @leave KErrPathNotFound, if @see EStorageSystemType is 

    98     @see ESystemTypeDefaultFileSystem and the path specified by 

    99     @see EStorageSuid does not exist on the Symbian OS filesystem. 

   100     @leave One of the system wide error codes, if a processing failure occurs.

   101     */

   102     virtual TUint32 AllocateLogicalStorageIdL(TUint aDataProviderId, TUint32 aPhysicalStorageId, const CMTPStorageMetaData& aStorage) = 0;

   103     

   104     /**

   105     Creates a new physical MTP StorageID to be owned and managed by the 

   106     specified data provider.

   107     @param aDataProviderId The identifier of the data provider which will be 

   108     responsible for the physical MTP StorageID.

   109     @param aStorage The storage meta-data. 

   110     @return The physical MTP StorageID.

   111     @leave KErrAlreadyExists, if the storage SUID is already defined.

   112     @leave One of the system wide error codes, if a processing failure occurs.

   113     */

   114     virtual TUint32 AllocatePhysicalStorageIdL(TUint aDataProviderId, const CMTPStorageMetaData& aStorage) = 0;

   115     

   116     /**

   117     Releases the specified fully formed logical MTP StorageID. 

   118     @param aDataProviderId The identifier of the data provider which is 

   119     responsible for the logical MTP StorageID.

   120     @param aLogicalStorageId The fully formed logical MTP StorageID to be 

   121     deallocated.

   122     @return KErrNone, if successful.

   123     @return KErrNotFound, if the specified logical MTP StorageID is not 

   124     defined.

   125     @return KErrAccessDenied, if the specified data provider is not the owner of

   126     the specified logical MTP StorageID.

   127     @return one of the system wide error codes, if a processing failure occurs.

   128     */

   129     virtual TInt DeallocateLogicalStorageId(TUint aDataProviderId, TUint32 aLogicalStorageId) = 0;

   130     

   131     /**

   132     Releases all logical MTP StorageIDs which represent partitions of the 

   133     specified physical MTP StorageID and which are owned by the specified data 

   134     provider.

   135     @param aDataProviderId The identifier of the data provider which is 

   136     responsible for the logical MTP StorageIDs.

   137     @param aPhysicalStorageId The physical MTP StorageID.

   138     */

   139     virtual void DeallocateLogicalStorageIds(TUint aDataProviderId, TUint32 aPhysicalStorageId) = 0;

   140     

   141     /**

   142     Releases the specified physical MTP StorageID, along with all associated

   143     logical storage partititions. 

   144     @param aDataProviderId The identifier of the data provider which is 

   145     responsible for the physical MTP StorageID.

   146     @param aPhysicalStorageId The physical MTP StorageID to be released.

   147     @return KErrNone if successful.

   148     @return KErrNotFound, if the specified sical MTP StorageID is not 

   149     defined.

   150     @return KErrAccessDenied if the specified data provider is not the owner of

   151     the specified physical MTP StorageID.

   152     @return one of the system wide error codes, if a processing failure occurs.

   153     */

   154     virtual TInt DeallocatePhysicalStorageId(TUint aDataProviderId, TUint32 aPhysicalStorageId) = 0;

   155 

   156     /**

   157     Provides the default MTP StorageID, as determined by the value of the 

   158     @see MTPFrameworkConfig::EDefaultStorageDrive framework configurability 

   159     parameter. This may either be a physical or fully formed logical MTP 

   160     StorageID, depending on the value of the 

   161     @see MTPFrameworkConfig::ELogicalStorageIdsAllocationEnable framework 

   162     configurability parameter.

   163     @return The default MTP StorageID.

   164     */

   165     virtual TUint32 DefaultStorageId() const = 0;

   166 

   167     /**

   168     Provides the Symbian OS drive number associated with the specified MTP 

   169     StorageID. 

   170     @param aStorageId The physical or fully formed logical MTP StorageID.

   171     @return The Symbian OS drive number associated with the specified MTP 

   172     StorageID.

   173     @return KErrNotFound, if the MTP StorageID does not exist, or is not 

   174     associated with a Symbian OS drive number.

   175     */

   176     virtual TInt DriveNumber(TUint32 aStorageId) const = 0;

   177 

   178     /**

   179     Provides the fully formed MTP StorageID created by the MTP data provider 

   180     framework on the specified Symbian OS drive. If the 

   181     @see MTPFrameworkConfig::ELogicalStorageIdsAllocationEnable framework 

   182     configurability parameter is set, then an MTP StorageID is created on each 

   183     of the available Symbian OS file system drives as they become available. If

   184     not set then the creation of all logical MTP StorageIDs is deferred to the 

   185     active data providers.

   186     @param aDriveNumber The drive number for which the corresponding logical

   187     MTP StorageID is required.

   188     @return The fully formed MTP StorageID of the logical storage which 

   189     corresponds to the specified Symbian OS drive number.

   190     @return KErrNotFound, if the Symbian OS drive number does not correspond 

   191     to an MTP data provider framework created default logical MTP StorageID.

   192     */

   193     virtual TInt32 FrameworkStorageId(TDriveNumber aDriveNumber) const = 0;

   194     

   195     /**

   196     Provides an ordered list of the Symbian OS file system drives which are

   197     available for use as MTP storages. This comprises the sub-set of available

   198     Symbian OS file system drives which are left exposed by the the @see

   199     MTPFrameworkConfig::EExcludedStorageDrives framework configurability 

   200     parameter.

   201     @param aDrives On succesful completion, the list of available Symbian OS 

   202     file system drives.

   203     @leave One of the system wide error codes, if a processing failure occurs.

   204     */

   205     virtual void GetAvailableDrivesL(RArray<TDriveNumber>& aDrives) const = 0;

   206     

   207     /**

   208     Provides an ordered list of the storage meta-data for all available logical

   209     MTP StorageIDs which match the specified query criteria. 

   210     @param aParams The query parameters.

   211     @param aStorages On succesful completion, the list of matching storage 

   212     meta-data. 

   213     @leave One of the system wide error codes, if a processing failure occurs.

   214     */

   215     virtual void GetLogicalStoragesL(const TMTPStorageMgrQueryParams& aParams, RPointerArray<const CMTPStorageMetaData>& aStorages) const = 0;

   216     

   217     /**

   218     Provides an ordered list of the storage meta-data for all available 

   219     physical MTP StorageIDs which match the specified query criteria. 

   220     @param aParams The query parameters.

   221     @param aStorages On succesful completion, the list of matching storage 

   222     meta-data. 

   223     @leave One of the system wide error codes, if a processing failure occurs.

   224     */

   225     virtual void GetPhysicalStoragesL(const TMTPStorageMgrQueryParams& aParams, RPointerArray<const CMTPStorageMetaData>& aStorages) const = 0;

   226     

   227     /**

   228     Provides the logical StorageID component (i.e. the least significant 

   229     16-bits) of the specified 32-bit MTP StorageID.

   230     @param aStorageId The MTP StorageID.

   231     @return The logical MTP StorageID, if successful.

   232     */

   233     virtual TUint32 LogicalStorageId(TUint32 aStorageId) const = 0;

   234     

   235     /**

   236     Provides the the fully formed 32-bit logical StorageID associated with the

   237     specified storage System Unique IDentifier (SUID).

   238     @param aStorageId The MTP StorageID.

   239     @return If successful, the fully formed MTP StorageID of the logical 

   240     storage which corresponds to the specified storage UID.

   241     KErrNotFound, if the specified storage UID is not defined.

   242     */

   243     virtual TInt32 LogicalStorageId(const TDesC& aStorageSuid) const = 0;

   244 

   245     /**

   246     Provides the physical MTP StorageID associated with the specified 

   247     Symbian OS drive number.

   248     @param aDriveNumber The Symbian OS drive number.

   249     @return If successful, the physical MTP StorageID associated with the 

   250     specified Symbian OS drive number.

   251     KErrNotFound, if the Symbian OS drive number is not associated with an MTP

   252     StorageID.

   253     */

   254     virtual TInt32 PhysicalStorageId(TDriveNumber aDriveNumber) const = 0;

   255    

   256     /**

   257     Provides the physical StorageID component (i.e. the most significant 

   258     16-bits) of the specified 32-bit MTP StorageID.

   259     @param aStorageId The MTP StorageID.

   260     @return The physical MTP StorageID.

   261     */

   262     virtual TUint32 PhysicalStorageId(TUint32 aStorageId) const = 0;

   263     

   264     /**

   265     Provides the storage meta-data for the specified logical MTP StorageID.

   266     @param aStorageId The physical or fully formed logical MTP StorageID.

   267     @leave KErrNotFound if the specified StorageID does not exist.

   268     @leave One of the system wide error codes, if a processing failure occurs.

   269     */

   270     virtual const CMTPStorageMetaData& StorageL(TUint32 aStorageId) const = 0;

   271    

   272     /**

   273     Constructs a fully formed 32-bit MTP StorageID from the specified physical 

   274     and logical MTP StorageIDs.

   275     @param aPhysicalStorageId The physical MTP StorageID. The least significant

   276     16-bits are ignored.

   277     @param aLogicalStorageId The logical MTP StorageID. The most significant 

   278     16-bits are ignored.

   279     @return The fully formed 32-bit MTP StorageID.

   280     */

   281     virtual TUint32 StorageId(TUint32 aPhysicalStorageId, TUint32 aLogicalStorageId) const = 0;

   282     

   283     /**

   284     Indicates if the specified StorageID is defined.

   285     @param aStorageId The physical or fully formed logical MTP StorageID.

   286     @return ETrue if the StorageID exists, otherwise EFalse.

   287     */

   288     virtual TBool ValidStorageId(TUint32 aStorageId) const = 0;

   289 

   290     /**

   291     Generates an MTP volume identifier string of which the leading 128 

   292     characters are guaranteed to be unique amongst all storages presented to a 

   293     conected MTP initiator.

   294     @param aDataProviderId The identifier of the data provider.

   295     @param aStorageId The MTP StorageID associated with the volume identifier.

   296     @param aVolumeIdSuffix The data provider supplied volume identifier string.

   297     @return The MTP volume identifier string. Ownership IS transferred.

   298     @leave KErrAccessDenied if the specified data provider is not the owner of

   299     the specified StorageID.

   300     @leave KErrNotFound if the specified MTP StorageID does not exist.

   301     @leave One of the system wide error codes, if a processing failure occurs.

   302     */

   303     virtual CMTPTypeString* VolumeIdL(TUint aDataProviderId, TUint32 aStorageId, const TDesC& aVolumeIdSuffix) const = 0;

   304     };

   305     

   306 #endif // MMTPSTORAGEMGR_H