First Contribution. Vanilla as it came from Nokia
/*
* 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.