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 MMTPDATAPROVIDER_H

    23 #define MMTPDATAPROVIDER_H

    24 

    25 #include <badesca.h>

    26 #include <e32base.h>

    27 #include <mtp/mtpdataproviderapitypes.h>

    28 

    29 class MMTPConnection;

    30 class MMTPDataProviderFramework;

    31 class TMTPTypeEvent;

    32 class TMTPTypeRequest;

    33 

    34 /** 

    35 Defines the MTP data provider Service Provider Interface (SPI).

    36 @publishedPartner

    37 @released

    38 */

    39 class MMTPDataProvider

    40     {

    41 public:

    42 

    43     /**

    44     Cancels the most recent outstanding request made to the MTP data provider 

    45     service provider interface. If there is no such request outstanding, then 

    46     no action is taken.

    47     */

    48     virtual void Cancel() = 0;

    49     

    50     /**

    51     Notifies the data provider that an asynchronous event dataset has been 

    52     received on the specified MTP connection.

    53     @param aEvent The MTP event dataset.

    54     @param aConnection The MTP connection on which the event was received.

    55     @leave One of the system wide error code, if a processing failure occurs

    56     in the data provider.

    57     */

    58     virtual void ProcessEventL(const TMTPTypeEvent& aEvent, MMTPConnection& aConnection) = 0;

    59 

    60     /**

    61     Notifies the data provider of a significant event which has been detected. 

    62     Additional details regarding the event may optionally be provided in the 

    63     accompanying notification parameter block.

    64     @param aNotification The notification type identifier.

    65     @param aParams The notification type specific parameter block

    66     @leave One of the system wide error code if a processing failure occurs

    67     in the data provider.

    68     */

    69     virtual void ProcessNotificationL(TMTPNotification aNotification, const TAny* aParams) = 0;

    70     

    71     /**

    72     Initiates an MTP transaction phase processing sequence in the data 

    73     provider. The data provider must respond by issuing a signal to the MTP 

    74     data provider framework layer interface that is appropriate for the request

    75     type and current phase (as specified by aPhase) of the MTP transaction 

    76     being processed, as follows:

    77     

    78     MTP Transaction Phase	Valid MMTPDataProviderFramework Signal

    79     ---------------------   --------------------------------------

    80 	ERequestPhase			ReceiveDataL, SendDataL, SendResponseL

    81 	EResponsePhase			SendResponseL

    82 	ECompletingPhase		TransactionCompleteL

    83      

    84     @param aPhase The MTP transaction phase to be processed.

    85     @param aRequest The MTP request dataset of the active MTP transaction.

    86     @param aConnection The MTP connection on which the transaction is being 

    87     processed.

    88     @see MMTPDataProviderFramework::ReceiveDataL

    89     @see MMTPDataProviderFramework::SendDataL

    90     @see MMTPDataProviderFramework::SendResponseL

    91     @see MMTPDataProviderFramework::TransactionCompleteL

    92     @leave One of the system wide error code if a processing failure occurs

    93     in the data provider.

    94     */

    95     virtual void ProcessRequestPhaseL(TMTPTransactionPhase aPhase, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    96     

    97     /**

    98     @Deprecated.

    99     Initiates an object store enumeration sequence to enumerate all MTP data 

   100     objects which reside on the specified storage and for which the data 

   101     provider is responsible. The data provider is expected to invoke the 

   102     appropriate @see MMTPObjectMgr methods to enumerate all MTP data objects 

   103     for which it is responsible and which it wishes to have presented to a 

   104     connected MTP initiator. The data provider must complete the sequence by 

   105     signalling @see ObjectEnumerationCompleteL to the data provider framework 

   106     layer interface.

   107     @param aStorageId The MTP StorageID of the storage to be enumerated. A 

   108     value of KMTPStorageAll indicates that all storages should be enumerated.

   109     @leave One of the system wide error code if a processing failure occurs

   110     in the data provider.

   111     @see MMTPDataProviderFramework::ObjectEnumerationCompleteL

   112     */	

   113     IMPORT_C virtual void StartObjectEnumerationL(TUint32 aStorageId);

   114     

   115     /**

   116     Initiates a storage enumeration sequence. The data provider is expected to 

   117     invoke the appropriate @see MMTPStorageMgr methods to enumerate all MTP 

   118     storages for which it is responsible and which it wishes to have presented 

   119     to a connected MTP initiator. The data provider must complete the sequence 

   120     by signalling @see StorageEnumerationCompleteL to the data provider 

   121     framework layer interface.

   122     @leave One of the system wide error code if a processing failure occurs

   123     in the data provider.

   124     @see MMTPDataProviderFramework::StorageEnumerationCompleteL

   125     */	

   126     virtual void StartStorageEnumerationL() = 0;

   127     

   128     /**

   129     Provides the set of MTP datacodes of the specified category that are 

   130     supported by the data provider.

   131     @param aCategory The requested MTP datacode category.

   132     @param aArray On successful completion, the set of MTP datacodes that are 

   133     supported by the data provider.

   134     */  

   135     virtual void Supported(TMTPSupportCategory aCategory, RArray<TUint>& aCodes) const = 0;

   136     

   137     /**

   138     Provides the MTP string values of the specified category that is supported 

   139     by the data provider. 

   140     @param aCategory The requested MTP datacode category.

   141     @param aStrings On successful completion, the set of string data that are 

   142     supported by the data provider.

   143     @leave One of the system wide error code if a processing failure occurs

   144     in the data provider.

   145     */  

   146     IMPORT_C virtual void SupportedL(TMTPSupportCategory aCategory, CDesCArray& aStrings) const;

   147     

   148     /**

   149     Provides an MTP data provider extension interface implementation 

   150     for the specified interface Uid. 

   151     @param aInterfaceUid The unique identifier for the extension interface being 

   152     requested.

   153     @return Pointer to an interface instance or 0 if the interface is not 

   154     supported. Ownership is NOT transfered.

   155     */

   156     IMPORT_C virtual TAny* GetExtendedInterface(TUid aInterfaceUid);

   157     

   158 protected:

   159 

   160     /**

   161     Provides a handle to the MTP data provider framework layer interface.

   162     @return Handle of the MTP data provider framework layer interface. 

   163     Ownership is NOT transfered.

   164     */

   165     virtual MMTPDataProviderFramework& Framework() const = 0;

   166     

   167 public:

   168     /**

   169     Initiates an object store enumeration sequence to enumerate all MTP data 

   170     objects which reside on the specified storage and for which the data 

   171     provider is responsible. The data provider is expected to invoke the 

   172     appropriate @see MMTPObjectMgr methods to enumerate all MTP data objects 

   173     for which it is responsible and which it wishes to have presented to a 

   174     connected MTP initiator. The data provider must complete the sequence by 

   175     signalling @see ObjectEnumerationCompleteL to the data provider framework 

   176     layer interface.

   177     @param aStorageId The MTP StorageID of the storage to be enumerated. A 

   178     value of KMTPStorageAll indicates that all storages should be enumerated.

   179     @param aPersistentFullEnumeration It is used by only persistent data providers,

   180     it indicates whether the persistent data providers should do the object full-enumreation or not. 

   181     @leave One of the system wide error code if a processing failure occurs

   182     in the data provider.

   183     @see MMTPDataProviderFramework::ObjectEnumerationCompleteL

   184     */	

   185 	IMPORT_C virtual void StartObjectEnumerationL(TUint32 aStorageId, TBool aPersistentFullEnumeration);

   186     

   187     };

   188 

   189 #endif // MMTPDATAPROVIDER_H