--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/connectivitylayer/isce/isaaccessextension_dll/inc/isakernelapi.h Fri Nov 06 17:28:23 2009 +0000
@@ -0,0 +1,435 @@
+/*
+* 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 ISAKERNELAPI_H
+#define ISAKERNELAPI_H
+
+// INCLUDES
+#include <klib.h> // For DBase
+
+// CONSTANTS
+// None
+
+// MACROS
+// None
+
+// DATA TYPES
+// None
+
+// FUNCTION PROTOTYPES
+// None
+
+// FORWARD DECLARATIONS
+class DISAKernelChannel;
+
+// CLASS DECLARATION
+
+/**
+* Kernel interface for ISA Access Driver.
+*
+* @lib IsaKernelAPI
+* @since S_CPR81
+*/
+NONSHARABLE_CLASS( DIsaKernelAPI ) : public DBase
+{
+
+
+ public:
+
+ /**
+ * Static constructor. Returns an new instance of the object.
+ * NOTE! Kern::Fault raised if no free memory left.
+ */
+ static IMPORT_C DIsaKernelAPI* NewF();
+
+ /**
+ * Destructor.
+ * Cancels any outstanding DFC requests and closes the channel.
+ */
+ IMPORT_C ~DIsaKernelAPI();
+
+ /**
+ * Get a free block for ISI message sending. Block is at least the size
+ * of the param aSize.
+ * NOTE! Kern::Fault raised if no free blocks left.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Block allocated and reference returned.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aSize, minimum size of the buffer.
+ * @return TDes8&, reference to allocated block.
+ */
+ IMPORT_C TDes8& AllocateMsgBlock( const TInt aSize );
+
+ /**
+ * Get a free block for data message sending. Block is at least the size
+ * of the param aSize.
+ * NOTE! Message allocated with this function must be
+ * send with DataSend.
+ * NOTE! Kern::Fault raised if no free blocks left.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Block allocated and reference returned.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aSize, minimum size of the buffer.
+ * @return TDes8&, reference to allocated datablock.
+ */
+ IMPORT_C TDes8& AllocateDataMsgBlock( const TInt aSize );
+
+ /**
+ * Closes the channel. If channel is not open does nothing. Cancels any
+ * outstanding DFC requests.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Channel closed and outstanding requests cancelled.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @return None
+ */
+ IMPORT_C void Close();
+
+ /**
+ * Receive message. DFC function given as param
+ * shall be queued to run when message is received.
+ * NOTE! After Receive DFC completion, client must deallocate block with
+ * DeAllocateDataMsgBlock and set the pointer to NULL.
+ * Preconditions: Channel is succesfully opened.
+ * Parameter aDataMsgBlock must be NULL.
+ * Postconditions: Receive is pending.
+ * Kern::Fault will be raised if API can't allocate receive buffer.
+ * Kern::Fault will be raised if same request is set when it is already pending.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aDataMsgBlock, block where received data message is written.
+ * @param aDfcStatus, updated when DFC is queued.
+ * KErrNone, succefull
+ * KErrCancel, receive was cancelled client no need to deallocate block get from receive.
+ * @param aDataReceiveDfc, clients DFC function for receiving message.
+ * @return None
+ */
+ IMPORT_C void DataReceive( TDes8*& aDataMsgBlock,
+ TInt& aDfcStatus,
+ const TDfc& aDataReceiveDfc );
+
+ /**
+ * Cancels the pending data receive request.
+ * Data receive cancellation will cancel pending DataReceive DFC with
+ * status KErrCancel. If nothing pending does nothing.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: DataReceive is cancelled.
+ * Called automatically in destructor.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @return None
+ */
+ IMPORT_C void DataReceiveCancel();
+
+
+ /**
+ * Sends a data message and deallocates the block given as parameter.
+ * Preconditions: Channel is succesfully opened.
+ * Descriptor was allocated with AllocateDataMsgBlock.
+ * Postconditions: Data message block is deallocated.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param TDes8& aMsg, reference to message to be send.
+ * @return TInt, an error code
+ * KErrNone, send succesfully
+ * KErrBadDescriptor, descriptor length too small.
+ * KErrUnderflow, ISI message length either bigger than descriptor
+ * length or bigger than maximum ISI message length
+ * or smaller than minimum ISI message length.
+ * KErrOverFlow, send queue overflow, client must resend.
+ * KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.
+ */
+ IMPORT_C TInt DataSend( TDes8& aMsg );
+
+
+ /**
+ * Deallocates the message block retrieved with Receive.
+ * NOTE! After deallocation set pointer to NULL.
+ * Preconditions: Channel is succesfully opened.
+ * Message was received with Receive.
+ * Postconditions: Message block is deallocated.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aMsgBlock, reference to block to deallocate.
+ * @return None
+ */
+ IMPORT_C void DeAllocateMsgBlock( TDes8& aMsgBlock );
+
+ /**
+ * Deallocates the data message block retrieved with DataReceive.
+ * NOTE! After deallocation set pointer to NULL.
+ * Preconditions: Channel is succesfully opened.
+ * Data message was received with DataReceive.
+ * Postconditions: Data message block is deallocated.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aMsgBlock, reference to data block to deallocate.
+ * @return None
+ */
+ IMPORT_C void DeAllocateDataMsgBlock( TDes8& aMsgBlock );
+
+ /**
+ * Notifies flow control status change. When flowcontrol status changes
+ * DFC will be queued and status value updated to parameter.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Flowcontrol status notification is pending.
+ * Kern::Fault will be raised if same request is set when it is already pending.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aNotifyFlowDfc, DFC function for flow status changes.
+ * @param aDfcStatus, EIscFlowControlOn when datasend not allowed,
+ * EIscFlowControlOff when datasend allowed,
+ * EIscTransmissionEnd when datasend connection is removed
+ * KErrCancel, when cancelled
+ * @return None
+ */
+ IMPORT_C void NotifyFlowChange( TDfc& aNotifyFlowDfc,
+ TInt& aDfcStatus );
+
+ /**
+ * Cancels connection status change request.
+ * Does nothing if request is not pending.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Flowcontrol status notification is cancelled.
+ * Called automatically in destructor.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @return None
+ */
+ IMPORT_C void NotifyFlowChangeCancel();
+
+ /**
+ * Notifies connection status change. When connection status changes
+ * DFC will be queued and connection status value updated to parameter.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Connection status notification is pending.
+ * Kern::Fault will be raised if same request is set when it is already pending.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aNotifyStateDfc, DFC function for connection status changes.
+ * @param aDfcStatus, EIscConnectionOk, EIscConnectionNotOk or KErrCancel
+ * @return None
+ */
+ IMPORT_C void NotifyStateChange( TDfc& aNotifyStateDfc,
+ TInt& aDfcStatus );
+
+ /**
+ * Cancels pending connection status notification with KErrCancel.
+ * Does nothing if request not pending.
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Connection status notification is cancelled.
+ * Called automatically in destructor.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @return None
+ */
+ IMPORT_C void NotifyStateChangeCancel() const;
+
+ /**
+ * Opens a clients channel.
+ * NOTE! If opened with resource client must give appropriate resource
+ * as aResource.
+ * Preconditions: Channel is closed.
+ * Postconditions: Open is pending.
+ * Kern::Fault will be raised if same request is set when it is already pending.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aChannelNumber, clients dedicated channel number.
+ * @param aDfcStatus, updated when DFC queued.
+ * KErrNone, is succesfully
+ * KErrAlreadyExist, channel already open
+ * KErrNotSupported, open with resource failed.
+ * @param aOpenDfc, ref. to DFC to be queued when channel is opened.
+ * @param aResource, 32-bit resourceid default value (PN_NO_ROUTING (0xff)).
+ * @return None
+ */
+ IMPORT_C void Open( const TUint16 aChannelNumber, TInt& aDfcStatus,
+ TDfc& aOpenDfc, const TUint32 aResource = 0x000000ff );
+
+ /**
+ * Cancels the pending open DFC request with KErrCancel.
+ * If the open is not pending anymore does nothing.
+ * Called automatically in destructor.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @return None
+ */
+ IMPORT_C void OpenCancel();
+
+ /**
+ * Receive message. DFC function given as param
+ * shall be queued to run when message is received.
+ * NOTE! After Receive DFC completion, client must deallocate block with
+ * DeAllocateBlock and set the pointer to NULL.
+ * Preconditions: Channel is succesfully opened.
+ * Parameter aMsgBlock must be NULL.
+ * Postconditions: Receive is pending.
+ * Kern::Fault will be raised if API can't allocate receive buffer.
+ * Kern::Fault will be raised if same request is set when it is already pending.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aMsgBlock, block where receive message is stored.
+ * @param aStatus, updated when DFC is queued.
+ * KErrNone, succefull
+ * KErrCancel, receive was cancelled client no need to deallocate block get from receive.
+ * @param aReceiveDfc, clients DFC function for receiving message.
+ * @return None
+ */
+ IMPORT_C void Receive( TDes8*& aMsgBlock, TInt& aStatus,
+ const TDfc& aReceiveDfc );
+
+ /**
+ * Cancels the pending receive DFC request with KErrCancel.
+ * If the receive is not pending anymore does nothing.
+ * Preconditions: Channel is succesfully opened.
+ * Called automatically in destructor.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @return None
+ */
+ IMPORT_C void ReceiveCancel();
+
+ /**
+ * Sends a message and deallocates the block given as parameter.
+ * Preconditions: Channel is succesfully opened.
+ * Descriptor was allocated with AllocateMsgBlock.
+ * Postconditions: Message block is deallocated.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param TDes8& aMsg, reference to message to be send.
+ * @return TInt, an error code
+ * KErrNone, send succesfully
+ * KErrBadDescriptor, descriptor length too small.
+ * KErrUnderflow, ISI message length either bigger than descriptor
+ * length or bigger than maximum ISI message length
+ * or smaller than minimum ISI message length.
+ * KErrOverFlow, send queue overflow, client must resend.
+ * KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.
+ */
+ IMPORT_C TInt Send( TDes8& aMsg );
+
+ /**
+ * Sends an event to CMT. NOTE! Only servers in ISA-sense can do this.
+ * Preconditions: Channel is succesfully opened with resource.
+ * Block was allocated with AllocateMsgBlock.
+ * Postconditions: Indication was send.
+ * Block was deallocated.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param TDes8& aMsg, reference to indication to be send.
+ * @return TInt, an error code.
+ * KErrNone, send succesfully
+ * KErrBadDescriptor, descriptor length too small.
+ * KErrUnderflow, ISI message length either bigger than descriptor
+ * length or bigger than maximum ISI message length
+ * or smaller than minimum ISI message length.
+ * KErrOverFlow, send queue overflow, client must resend.
+ * KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.
+ */
+ IMPORT_C TInt SendIndication( TDes8& aMsg );
+
+ /**
+ * Subscribe indications. Indications are received with
+ * Receive.
+ * NOTE! Don't dellocate the descriptor for indications.
+ * 8-bit subscribing list item. Must be div. by two.
+ * byte1:[8bit resourceid]
+ * byte2:[8bit indicationid]
+ * 32-bit subscribing list item. Must be div. by five.
+ * byte1:[32-24 bits of resourceid]
+ * byte2:[24-16 bits of resourceid]
+ * byte3:[16-8 bits of resourceid]
+ * byte4:[8-0 bits of resourceid]
+ * byte5:[8bit indicationid]
+ * Preconditions: Channel is succesfully opened.
+ * Postconditions: Channel is add as indication(s) subscriber.
+ * Called in kernel thread context.
+ * Called with no fastmutex held.
+ * Called with interrupts enabled.
+ * Called without kernel lock held.
+ * @param aIndications, indication subscription list.
+ * @param aThirtyTwoBit, EFalse by default, ETrue when 32-bit subscribing used.
+ * @return TInt, an error code.
+ * KErrNone, subscribe succesfully
+ * KErrBadDescriptor, descriptor length too small or not according to subscribing list items.
+ * KErrUnderflow, subscribing list item too long.
+ * KErrOverFlow, send queue overflow, client must resend.
+ * KErrNotReady, modem sw down, send failed, start listen state change, when ok, possible to resend.
+ */
+ IMPORT_C TInt SubscribeIndications( const TDesC8& aIndications,
+ const TBool aThirtyTwoBit = EFalse );
+
+ private:
+
+ /**
+ * Private constructor.
+ * One reason class size BC.
+ */
+ DIsaKernelAPI();
+
+ private:
+
+ // Owned
+ // Kernel channel dedicated for this.
+ DISAKernelChannel* iKernelChannel;
+
+ };
+
+#endif // ISAKERNELAPI_H
+
+// End of File.
+