/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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: 
*
*/



#ifndef __MP2PIF_H__
#define __MP2PIF_H__

#include <p2pdefs.h>    // For TP2PProtocol

// Forward declarations
class MP2PIf;

/*
* Factory class for creating the Point-to-point interface.
*/
class TP2PFactory
    {

    public:

        /*
        * Creates a new P2P inteface.
        * Interface must be released with MP2PIf::Release
        * Execution:    Synchronous
        * Re-entrant:   Yes
        * Blocking:     No
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @return pointer to new interface
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @post Calling thread not blocked
        */
        IMPORT_C static MP2PIf* NewP2PIfF();

    };

/**
* An interface for transceiving point-to-point (P2P) data between
* two end points according to used P2P protocol.
* Interface is used from kernel side.
* NOTE! Do remember binary compatibility issues when chaning the interface.
*/
class MP2PIf
{

    public:

        /**
        * Returns a free block for data sending.
        * Blocks descriptor length is set to zero, but maximum length can be bigger
        * than size given as parameter (it depends on memory block configurations).
        * Responsibility to deallocate the block is transferred to caller.
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * NOTE! Kern::Fault raised if no free blocks left.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @param aSize, minimum size of the buffer.
        * @return TDes8&, reference to allocated block.
        * @pre Called always in kernel thread context.
        * @pre No fastmutex held.
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual TDes8& AllocateBlock( const TUint16 aSize ) = 0;

        /**
        * Closes the interface and cancels any outstanding DFC requests.
        * If interface is not opened with MP2PIf::Open function does nothing.
        * Automatically called in Release.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void Close() = 0;

        /*
        * Notifies when connection to other point is lost.
        * DFC function given as param shall be queued to run when connection is lost.
        * Automatically cancelled in MP2PIf::Close.
        * All data received after connection is lost shall be discarded.
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * NOTE! After connection lost MP2PIf::Close shall be called.
        * Execution:    Asynchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @param aStatus, updated when connection is lost
        *                 KErrNotReady when connection is lost
        *                 KErrCancel when request is cancelled
        * @param aConnectionResetedCompletedDfc, clients DFC function to notify connection lost
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void ConnectionLost( TInt& aStatus, const TDfc& aConnectionResetedCompletedDfc ) = 0;

        /*
        * Cancels the pending connection lost request with KErrCancel.
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * Automatically called in MP2PIf::Close
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void ConnectionLostCancel() = 0;


        /**
        * Deallocates the data block retrieved with MP2PIf::Receive.
        * NOTE! After deallocation set pointer to NULL.
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * NOTE! Data shall be received before with MP2PIf::Receive.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @param aDataBlock, reference to block to deallocate.
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void DeallocateBlock( TDes8& aDataBlock ) = 0;

        /**
        * Asynchronously opens the interface.
        * When open request is set to pending blocked caller thread is released.
        * Automatically cancelled in MP2PIf::Close.
        * NOTE! Inteface either not opened or closed with MP2PIf::Close.
        * NOTE! Kern::Fault will be raised if same request is set when it is already pending.
        * Execution:    Asynchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @param aP2PProtocolId, dedicated P2P protocol id.
        * @param aDfcStatus, updated when DFC queued.
        *                    KErrNone, succesfully opened
        *                    KErrCancel, outstanding request is cancelled
        *                    KErrInUse if someone uses the same protocol id
        *                    KErrAlreadyExists same interface object is opened with other protocol id
        * @param aOpenCompleteDfc, reference to DFC to be queued when open completes.
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void Open( const TP2PProtocol aP2PProtocolId, TInt& aDfcStatus, TDfc& aOpenCompleteDfc ) = 0;

        /**
        * Cancels the pending open DFC request with KErrCancel.
        * If the request is not pending anymore does nothing.
        * Automatically called in MP2PIf::Close
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void OpenCancel() = 0;

        /**
        * Receives data from other point.
        * Either receives data immediately or set the receive request pending.
        * Responsibility to deallocate the data is transferred to caller.
        * DFC function given as param shall be queued to run when data is received.
        * Automatically cancelled in MP2PIf::Close.
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * NOTE! After Receive DFC completion, client shall deallocate the block with
        * MP2PIf::DeallocateBlock and set aRxDataBlock pointer to NULL.
        * NOTE! pointer to the aRxDataBlock shall not be modified from other DFC functions
        * only from aReceiveCompletedDfc function.
        * NOTE! If interface is not opened when other point is sending data to it data shall
        * be deallocated.
        * NOTE! Kern::Fault will be raised if aRxDataBlock ptr is not NULL.
        * NOTE! Kern::Fault will be raised if API can't allocate receive buffer.
        * NOTE! Kern::Fault will be raised if same request is set when it is already pending.
        * Execution:    Asynchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @param aRxDataBlock, block where received data shall be stored.
        * @param aStatus, updated when DFC is queued.
        *                 KErrNone, succefull
        *                 KErrCancel, receive was cancelled client no need to deallocate block get from receive.
        * @param aReceiveCompletedDfc, clients DFC function for receiving data. 
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void Receive( TDes8*& aRxDataBlock, TInt& aStatus, const TDfc& aReceiveCompletedDfc ) = 0;

        /**
        * Cancels the pending receive request with KErrCancel.
        * If the request is not pending anymore does nothing.
        * Automatically called in MP2PIf::Close
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void ReceiveCancel() = 0;

        /*
        * Deletes the concret object of the interface and releases reserved resources.
        * Caller is responsible to set the interface pointer to NULL.
        * NOTE! Called when interface shall not be used anymore (usually after MP2PIf::Close).
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual void Release() = 0;

        /**
        * Sends the data and deallocates the block given as parameter.
        * Responsibility to deallocate the block is transferred.
        * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised.
        * NOTE! Descriptor shall be allocated before with MP2PIf::AllocateMsgBlock.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   Kern::Fault
        * SMP safe:     Yes
        * Called in kernel thread context.
        * Called with no fastmutex held.
        * Called with interrupts enabled.
        * Called without kernel lock held.
        * @param TDes8& aData, reference to the data to be send.
        * @return TInt, an error code
        *               KErrNone, data send
        *               KErrNotReady, connection to other point lost and data discarded, MP2PIf::Close shall be called after this
        * @pre Called always in kernel thread context
        * @pre No fastmutex held
        * @pre Called with interrupts enabled and kernel unlocked.
        * @post Calling thread not blocked
        */
        virtual TInt Send( TDes8& aData ) = 0;

    };

#endif // __MP2PIF_H__

// End of File.