// 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 MMTPDATAPROVIDER_H

#define MMTPDATAPROVIDER_H

#include <badesca.h>

#include <e32base.h>

#include <mtp/mtpdataproviderapitypes.h>

class MMTPConnection;

class MMTPDataProviderFramework;

class TMTPTypeEvent;

class TMTPTypeRequest;

/** 

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

@publishedPartner

@released

*/

class MMTPDataProvider

    {

public:

    /**

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

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

    no action is taken.

    */

    virtual void Cancel() = 0;

    /**

    Notifies the data provider that an asynchronous event dataset has been 

    received on the specified MTP connection.

    @param aEvent The MTP event dataset.

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

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

    in the data provider.

    */

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

    /**

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

    Additional details regarding the event may optionally be provided in the 

    accompanying notification parameter block.

    @param aNotification The notification type identifier.

    @param aParams The notification type specific parameter block

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

    in the data provider.

    */

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

    /**

    Initiates an MTP transaction phase processing sequence in the data 

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

    data provider framework layer interface that is appropriate for the request

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

    being processed, as follows:

    MTP Transaction Phase	Valid MMTPDataProviderFramework Signal

    ---------------------   --------------------------------------

	ERequestPhase			ReceiveDataL, SendDataL, SendResponseL

	EResponsePhase			SendResponseL

	ECompletingPhase		TransactionCompleteL

    @param aPhase The MTP transaction phase to be processed.

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

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

    processed.

    @see MMTPDataProviderFramework::ReceiveDataL

    @see MMTPDataProviderFramework::SendDataL

    @see MMTPDataProviderFramework::SendResponseL

    @see MMTPDataProviderFramework::TransactionCompleteL

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

    in the data provider.

    */

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

    /**

    @Deprecated.

    Initiates an object store enumeration sequence to enumerate all MTP data 

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

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

    appropriate @see MMTPObjectMgr methods to enumerate all MTP data objects 

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

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

    signalling @see ObjectEnumerationCompleteL to the data provider framework 

    layer interface.

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

    value of KMTPStorageAll indicates that all storages should be enumerated.

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

    in the data provider.

    @see MMTPDataProviderFramework::ObjectEnumerationCompleteL

    */	

    IMPORT_C virtual void StartObjectEnumerationL(TUint32 aStorageId);

    /**

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

    invoke the appropriate @see MMTPStorageMgr methods to enumerate all MTP 

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

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

    by signalling @see StorageEnumerationCompleteL to the data provider 

    framework layer interface.

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

    in the data provider.

    @see MMTPDataProviderFramework::StorageEnumerationCompleteL

    */	

    virtual void StartStorageEnumerationL() = 0;

    /**

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

    supported by the data provider.

    @param aCategory The requested MTP datacode category.

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

    supported by the data provider.

    */  

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

    /**

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

    by the data provider. 

    @param aCategory The requested MTP datacode category.

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

    supported by the data provider.

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

    in the data provider.

    */  

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

    /**

    Provides an MTP data provider extension interface implementation 

    for the specified interface Uid. 

    @param aInterfaceUid The unique identifier for the extension interface being 

    requested.

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

    supported. Ownership is NOT transfered.

    */

    IMPORT_C virtual TAny* GetExtendedInterface(TUid aInterfaceUid);

protected:

    /**

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

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

    Ownership is NOT transfered.

    */

    virtual MMTPDataProviderFramework& Framework() const = 0;

public:

    /**

    Initiates an object store enumeration sequence to enumerate all MTP data 

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

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

    appropriate @see MMTPObjectMgr methods to enumerate all MTP data objects 

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

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

    signalling @see ObjectEnumerationCompleteL to the data provider framework 

    layer interface.

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

    value of KMTPStorageAll indicates that all storages should be enumerated.

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

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

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

    in the data provider.

    @see MMTPDataProviderFramework::ObjectEnumerationCompleteL

    */	

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

    };

#endif // MMTPDATAPROVIDER_H