// 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 MMTPDATAPROVIDERFRAMEWORK_H
#define MMTPDATAPROVIDERFRAMEWORK_H

#include <e32cmn.h>
#include <e32def.h>
#include <mtp/mtpdataproviderconfig.hrh>
#include <mtp/mtpdataproviderapitypes.h>

class MMTPConnection;
class MMTPDataProviderConfig;
class MMTPFrameworkConfig;
class MMTPObjectMgr;
class MMTPReferenceMgr;
class MMTPStorageMgr;
class MMTPType;
class TMTPTypeEvent;
class TMTPTypeResponse;
class TMTPTypeRequest;
class RFs;
class MMTPDataCodeGenerator;

/**
Defines the MTP data provider framework layer application programming
interface.
@publishedPartner
@released
*/
class MMTPDataProviderFramework
    {
public:

    /**
    Provides the unique identifier of the calling data provider.
    @return The data provider identifier.
    */
    virtual TUint DataProviderId() const = 0;

    /**
    Provides the current MTP operational mode.
    @return The current MTP operational mode.
    */
    virtual TMTPOperationalMode Mode() const = 0;

    /**
    Initiates a data object receive sequence in the MTP data provider framework
    layer. This method should only be invoked when processing the ERequestPhase
    of an MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL),
    and causes the MTP session transaction state to transition to the
    @see EDataIToRPhase. The data object receive sequence is completed when the 
    MTP data provider framework layer initiates the @see EResponsePhase of the 
    MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL).
    @param aData The MTP data object sink buffer.
    @param aRequest The MTP request dataset of the active MTP transaction.
    @param aConnection The handle of the MTP connection on which the transaction
    is being processed.
    @see CMTPDataProviderPlugin::ProcessRequestPhaseL
    @leave KErrNotReady, if invoked when the current MTP transaction phase is
    not ERequestPhase.
    */
    virtual void ReceiveDataL(MMTPType& aData, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    /**
    Initiates a data object send sequence in the MTP data provider framework
    layer. This method should only be invoked when processing the ERequestPhase
    of an MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL),
    and causes the MTP session transaction state to transition to the
    @see EDataRToIPhase. The data object send sequence is completed when the 
    MTP data provider framework layer initiates the @see EResponsePhase of the 
    MTP transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL).
    @param aData The MTP data object source buffer.
    @param aRequest The MTP request dataset of the active MTP transaction.
    @param aConnection The handle of the MTP connection on which the transaction
    is being processed.
    @see CMTPDataProviderPlugin::ProcessRequestPhaseL
    @leave KErrNotReady, if invoked when the current MTP transaction phase is
    not ERequestPhase.
    */
    virtual void SendDataL(const MMTPType& aData, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    /**
    Signals the MTP data provider framework layer to send an asynchronous event
    dataset on the specified MTP connection.
    @param aEvent The MTP event dataset source buffer.
    @param aConnection The handle of the MTP connection on which the event is
    to be sent.
    @leave KErrArgument, if the event data is not valid.
    */
    virtual void SendEventL(const TMTPTypeEvent& aEvent, MMTPConnection& aConnection) = 0;

    /**
    Signals the MTP data provider framework layer to send an asynchronous event
    dataset on all active MTP connections.
    @param aEvent The MTP event dataset source, this should always target all
    open sessions, i.e. SessionID should be set to KMTPAllSessions.
    @leave KErrArgument, if the event data is invalid.
    */
    virtual void SendEventL(const TMTPTypeEvent& aEvent) = 0;

    /**
    Initiates an MTP response dataset send sequence in the MTP data provider
    framework layer. This method should only be invoked when processing either
    the @see ERequestPhase or @see EResponsePhase of an MTP transaction, (@see
    CMTPDataProviderPlugin::ProcessRequestPhaseL) and causes the MTP session
    transaction state to transition to the @see ECompletingPhase. The MTP 
    response dataset send sequence is completed when the MTP data provider 
    framework layer initiates the @see ECompletingPhase of the MTP transaction 
    (@see CMTPDataProviderPlugin::ProcessRequestPhaseL).
    @param aResponse The MTP aResponse dataset source buffer.
    @param aConnection The handle of the MTP connection on which the transaction
    is being processed.
    @see CMTPDataProviderPlugin::ProcessRequestPhaseL
    @leave KErrNotReady, if invoked when the current MTP transaction phase is
    not ERequestPhase or EResponsePhase.
    */
    virtual void SendResponseL(const TMTPTypeResponse& aResponse, const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    /**
    Signals to the MTP data provider framework layer that all processing
    related to the current transaction has been completed. This method should
    only be invoked when processing the @see ECompletingPhase of the MTP 
    transaction (@see CMTPDataProviderPlugin::ProcessRequestPhaseL), and causes 
    the MTP session transaction state to transition to the @see EIdle state.
    @param aRequest The MTP request dataset that initiated the transaction.
    @param aRequest The MTP request dataset of the active MTP transaction.
    @param aConnection The handle of the MTP connection on which the transaction
    is being processed.
    @see CMTPDataProviderPlugin::ProcessRequestPhaseL
    @leave KErrNotReady If invoked when the current MTP transaction phase is
    invalid.
    */
    virtual void TransactionCompleteL(const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    /**
    Registers the calling data provider to receive one or more occurrences of 
    the specified request dataset that are received on the specified 
    connection. This method should be used to register the calling data 
    provider to receive the following request types:
    
        1.  Follow-on requests of an MTP operation that can span multiple 
            transaction cycles. The following request types are recognised
            by the framework as follow-on requests:
            
            i)  SendObject (preceded by SendObjectInfo or SendObjectPropList). 
            ii) TerminateOpenCapture (preceded by InitiateOpenCapture).
            
        2.  MTP vendor extension requests.
        
    Note that:

        1.  The request dataset being registered must minimally specify the
            Operation Code of the expected operation and the SessionID on which 
            the operation request is expected to be received. 
            
            Follow-on request registrations MUST specify a specific SessionID. 
            Registrations of non follow-on requests may optionally specify a 
            SessionID of @see KMTPSessionAll to receive matching requests from
            any active MTP session.
           
        2.  With the exception of the TransactionID element, registered request
            datasets must exactly match all data elements of the expected request 
            dataset in order to be successfully routed.
           
        3.  Duplicate RouteRequestRegisterL registrations are not permitted. A request 
            dataset that matches that of a previous registration by this or 
            any other data provider on the same MTP session will result in the 
            previous registration being superceded.
           
        4.  Pending RouteRequestRegisterL registrations can be withdrawn at any time
            using the @see RouteRequestUnregisterL method. 
           
        5.  RouteRequestRegisterL registrations of MTP request types which ARE 
            recognised by the framework as MTP follow-on requests (SendObject, 
            TerminateOpenCapture) will result in at most one matching request 
            occurence being routed to the data provider. To receive another 
            request dataset of the same type, a new @see RouteRequestRegisterL 
            registration must be made.
            
        6   RouteRequestRegisterL registrations of MTP request types which ARE
            NOT recognised by the framework as MTP follow-on requests will 
            result in all matching requests which are subsequently received 
            being routed to the data provider. This will continue until such 
            time as the RouteRequestRegisterL registration is withdrawn using 
            the @see RouteRequestUnregisterL method.
            
        7.  RouteRequestRegisterL registrations request datasets which specify 
            an SessionID value of @see KMTPSessionAll, will result in matching 
            requests which are subsequently received on any active MTP session
            being routed to the data provider.

    @param aRequest The operation request dataset being registered.
    @param aConnection The handle of the MTP connection on which the operation
    request is expected to be received.
    @leave KErrArgument, if the request dataset does meet the minimal
    registration requirements specified above.
    @leave One of the system wide error codes, if a general processing error
    occurs.
    @see RouteRequestUnregisterL
    */
    virtual void RouteRequestRegisterL(const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    /**
    Cancels a pending RouteRequestRegisterL registration.
    @param aRequest The registered operation request dataset.
    @param aConnection The handle of the MTP connection for which the operation
    request was registered.
    @leave One of the system wide error codes, if a general processing error
    occurs.
    @see RouteRequestRegisterL
    */
    virtual void RouteRequestUnregisterL(const TMTPTypeRequest& aRequest, MMTPConnection& aConnection) = 0;

    /**
    Signals the completion of the data provider's object store enumeration
    sequence that was previously initiated by a StartObjectEnumerationL signal
    made to the MTP data provider interface.
    @param aStorageId The MTP StorageID of the enumerated storage. This should 
    match the value specified in the preceding StartObjectEnumerationL.
    @see MMTPDataProvider::StartObjectEnumerationL
    */
    virtual void ObjectEnumerationCompleteL(TUint32 aStorageId) = 0;

    /**
    Signals the completion of the data provider's storage enumeration sequence
    that was previously initiated by a StartStorageEnumerationL signal
    made to the MTP data provider interface.
    @see MMTPDataProvider::StartStorageEnumerationL
    */
    virtual void StorageEnumerationCompleteL() = 0;

    /**
    Provides a handle to the configurability data specified in the data 
    provider's configuration file. 
    @return Handle to the data provider's configurability data.
    */
    virtual const MMTPDataProviderConfig& DataProviderConfig() const = 0;

    /**
    Provides a handle to the data provider framework configurability parameter 
    data. 
    @return Handle to the data provider framework configurability data.
    */
    virtual const MMTPFrameworkConfig& FrameworkConfig() const = 0;

    /**
    Provides a handle to the MTP object manager, which manages the assignment
    of MTP object handles and their mapping to actual data objects on behalf
    of the data provider.
    @return Handle to the MTP data provider framework object manager.
    */
    virtual MMTPObjectMgr& ObjectMgr() const = 0;

    /**
    Provides a handle to the MTP object reference manager, to which data
    providers can delegate the handling of the MTP persistent, abstract
    object referencing mechanism.
    @return Handle to the MTP data provider framework object reference manager.
    */
    virtual MMTPReferenceMgr& ReferenceMgr() const = 0;

    /**
    Provides a handle to the MTP storage manager, which manages the assignment 
    of MTP storage identifiers on behalf of the data provider.
    @return Handle to the MTP data provider framework storage manager.
    */
    virtual MMTPStorageMgr& StorageMgr() const = 0;
    
    /**
    Provides a handle to the MTP data provider framework RFs session.
    @return Handle to the MTP data provider framework RFs session.
    */
    virtual RFs& Fs() const = 0;
    
    /**
    Provides a handle to the MTP datacode generator, which generate the datacode of service properties , formats and methods etc.
    @return Handle to the MTP datacode generator.
    */
    virtual MMTPDataCodeGenerator& DataCodeGenerator() const = 0;
    
    /**
    Issues the specified notification to framework.
    @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 framework.
    */
    virtual void NotifyFrameworkL( TMTPNotificationToFramework aNotification, const TAny* aParams ) = 0;
    
    /**
    Register the current request as pending request. The pending request will be handled
    after enumeration done.
    */
    virtual void RegisterPendingRequest(TUint aTimeOut = 0) = 0;
     
    };

#endif // MMTPDATAPROVIDERFRAMEWORK_H