diff -r 000000000000 -r 63b37f68c1ce connectivitylayer/isce/isirouter_dll/inc/misiif.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/connectivitylayer/isce/isirouter_dll/inc/misiif.h Fri Nov 06 17:28:23 2009 +0000 @@ -0,0 +1,185 @@ +/* +* 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 __ISIIF_H__ +#define __ISIIF_H__ + +// Forward declarations +#ifdef __KERNEL_MODE__ +class TDfc; +#endif + + +/** +* Class MISIIf defines an abstract interface for ISA entities. +* Interface is used to transceive ISI messages between ISA entities. +*/ +class MISIIf + { + + public: + +#ifdef __KERNEL_MODE__ + /** + * Returns a free block for sending ISI messages. Blocks descriptor length is set + * to zero, but maximum length can be more than size given as parameter. + * Interface shall be created before with MISIIf::NewISIIf or Kern::Fault raised. + * Fault is raised if no free blocks left. + * Responsibility to deallocate the block is transferred to caller. + * Execution: Synchronous + * Re-entrant: No + * Blocking: Yes + * Panic mode: Kern::Fault + * SMP safe: Yes + * @param aSize, minimum size of the buffer in bytes. + * @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& AllocateMsgBlock( const TUint16 aSize ) = 0; + + + /** + * Deallocates the ISI message block retrieved with MISIIf::Receive. + * After deallocation set pointer to NULL. Interface shall be created + * before with MISIIf::NewISIIf or Kern::Fault raised. ISI message shall + * be received before with MISIIf::Receive. + * Execution: Synchronous + * Re-entrant: No + * Blocking: Yes + * Panic mode: Kern::Fault + * SMP safe: Yes + * @param aMsgBlock, 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 DeallocateMsgBlock( TDes8& aMsgBlock ) = 0; +#endif + + + /** + * Creates a new ISI interface. + * Interface must be released with MISIIf::Release. + * If no memory available panics. When same UID already used Kern::Fault raised. + * Execution: Synchronous + * Re-entrant: Yes + * Blocking: No + * Panic mode: Kernel: Kern::Fault, User: User::Panic + * SMP safe: Yes + * @param aUID, clients unique UID identifier. + * @param aObjId, reference to write clients object id. + * @return pointer to new interface. + * @pre Called always in thread context (Kernel: in kernel thread context). + * @pre No fastmutex held. (Kernel only) + * @post Calling thread not blocked. + */ + IMPORT_C static MISIIf* NewISIIf( const TInt32 aUID, TUint8& aObjId ); + + + /** + * Receive an ISI message from other ISA entity. Interface shall be created + * before with MISIIf::NewISIIf or panic raised. Receive shall always be + * pending after interface is created. + * Execution: Asynchronous + * Re-entrant: No + * Blocking: Yes + * Panic mode: Kernel: Kern::Fault, User: User::Panic + * SMP safe: Yes + * @param aRxStatus, updated when receive either succesful or failed. + KErrNone, receive succesful. + KErrCancel, outstanding request is cancelled. + KErrOverflow, not enough memory to store the message. + * @param aRxMsg, reference to store received message (Kernel only pointer reference). + * @param aNeededBufLen, if receive buffer too short correct lenght is written to this (User only). + * @param aRxCompletedDfc, DFC executed when receive is completed (Kernel only). + * @pre Called always in thread context (Kernel: in kernel thread context). + * @pre No fastmutex held (Kernel only). + * @post Calling thread not blocked. + */ + virtual void Receive( TRequestStatus& aRxStatus, +#ifndef __KERNEL_MODE__ + TDes8& aRxMsg, + TUint16& aNeededBufLen +#else + TDes8*& aRxMsg, + const TDfc& aRxCompletedDfc +#endif + ) = 0; + + + /** + * Cancels the pending receive request with KErrCancel. + * If the request is not pending anymore does nothing. + * Automatically called in MISIIf::Release. Interface shall be created + * before with MISIIf::NewISIIf or panic raised. + * Execution: Synchronous + * Re-entrant: No + * Blocking: Yes + * Panic mode: Kernel: Kern::Fault, User: User::Panic + * SMP safe: Yes + * @pre Called always in kernel thread context. + * @pre No fastmutex held (Kernel only). + * @pre Called with interrupts enabled and kernel unlocked (Kernel only). + * @post Calling thread not blocked. + */ + virtual void ReceiveCancel() = 0; + + + /** + * Deletes the concret object of the interface and releases reserved resources. + * Cancels pending receive request. Caller is responsible to set the interface pointer to NULL. + * In case of User::Panic called automatically. + * Execution: Synchronous + * Re-entrant: No + * Blocking: Yes + * Panic mode: Kernel: Kern::Fault, User: User::Panic + * SMP safe: Yes + * @pre Called always in kernel thread context. + * @pre No fastmutex held (Kernel only). + * @pre Called with interrupts enabled and kernel unlocked (Kernel only). + * @post Calling thread not blocked. + */ + virtual void Release() = 0; + + + /** + * Send ISI message to other ISA entity. Interface shall be created before + * with MISIIf::NewISIIf or panic raised. + * Execution: Synchronous + * Re-entrant: No + * Blocking: Yes + * Panic mode: Kernel: Kern::Fault, User: User::Panic + * SMP safe: Yes + * @param aTxMsg, ISI message to be send. + * @return success code of the operation. + KErrNone, send succesful. + KErrOverflow, too long message tried to send. + * @pre Called always in thread context (Kernel: in kernel thread context). + * @pre No fastmutex held (Kernel only). + * @post Calling thread not blocked. + */ + virtual TInt Send( const TDesC8& aTxMsg ) = 0; + + }; + +#endif // _ISIIF_H_ + +// End of File