diff -r 000000000000 -r 63b37f68c1ce connectivitylayer/isce/p2prouter_dll/inc/mp2pif.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/connectivitylayer/isce/p2prouter_dll/inc/mp2pif.h Fri Nov 06 17:28:23 2009 +0000 @@ -0,0 +1,296 @@ +/* +* 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 // 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. +