/*
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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 ISCMULTIPLEXERBASE_H
#define ISCMULTIPLEXERBASE_H
// INCLUDES
#include <kernel.h>
#include <IscDefinitions.h>
// CONSTANTS
_LIT( KIscMultiplexerName,"IscMultiplexer" );
const TUint16 KIscBufferAmount = 10;
// MACROS
// DATA TYPES
typedef struct
{
TIscFrameType frameType;
TIscFrameConcatenation concatenation;
TUint16 totalLength;
TUint16 writeStartIndex;
TUint16 writeLength;
} TIscFrameInfo;
typedef struct
{
TUint16 size;
TUint16 count;
} TIscBufferEntry;
typedef struct
{
TUint16 mainRcvQueueSize;
TUint16 channelRcvQueueSize;
TUint16 channelDataRcvQueueSize;
TUint16 channelSendQueueSize;
TIscBufferEntry bufferConfig[KIscBufferAmount];
} TIscConfiguration;
// FUNCTION PROTOTYPES
// FORWARD DECLARATIONS
class DIscDevice;
// CLASS DECLARATION
/**
* DIscMultiplexerBase defines the ISC Multiplexer Plug-In API.
* This class defines the base class for Multiplexer( s ) used in
* conjunction with ISC Driver
*
* @lib IscMultiplexerBase.LIB
* @since 2.8
*/
class DIscMultiplexerBase : public DLogicalDevice
{
public: // Constructors and destructor
/**
* C++ default constructor.
*/
IMPORT_C DIscMultiplexerBase();
/**
* Destructor
*/
IMPORT_C virtual ~DIscMultiplexerBase();
public: // Functions from base class
/**
* Implementation of pure-virtual Install from DLogicalDevice. This
* function calls Install2ndPhase.
* @since 2.8
* @return TInt KErrNone
*/
IMPORT_C TInt Install();
public: // New functions
/**
* Second phase initialization, called during ISC Multiplexer loading
* ISC Multiplexer must do all initialization here that are normally
* done in Install()
* @since 2.8
* @return TInt KErrNone if successful
*/
virtual TInt Install2ndPhase() = 0;
/**
* Multiplexers "pre" intialization before Data transmission driver
* initialization has been done ( e.g. if buffer configurations are given from isc_config.ini )
* @since 2.8
* @param aParameters Additional parameters passed to multiplexer
* @return void
*/
IMPORT_C virtual void SetInitializationParameters( const TDesC8& aParameters );
/**
* Multiplexer intialization
* @since 2.8
* @param aOperation The asynchronous request to complete after
* multiplexer intialization is complete
* @param aParameters Additional parameters passed to multiplexer
* @param aChannelPtr DIscChannel pointer
* @return void
*/
virtual void InitializeMultiplexer( const TUint16 aOperation,
const TDesC8& aParameters,
const TAny* aChannelPtr ) = 0;
/**
* Open data link connection with the modem
* @since 2.8
* @param aDLCI The channel id to open
* @param aOpenParams Additional open parameters given by the ISC user,
* NULL if omitted
* @param aChannelPtr DIscChannel pointer
* @return void
*/
virtual void OpenDLC( const TUint16 aDLCI,
const TDesC8* aOpenParams,
const TAny* aChannelPtr ) = 0;
/**
* Close data link connection
* @since 2.8
* @param aDLCI The channel id to close
* @param aChannelPtr DIscChannel pointer
* @return void
*/
virtual void CloseDLC( const TUint16 aDLCI,
const TAny* aChannelPtr ) = 0;
/**
* Send data to Domestic OS
* @since 2.8
* @param aOperation Used to distinguish whether it is a synchronous
* or asynchronous Send request ( EIscSyncSend / EIscAsyncSend )
* @param aSenderChannel Sender channel id
* @param aData Data to be sent
* @param aChannelPtr DIscChannel pointer
* @return KErrNone if successful
*/
virtual TInt Send( const TUint16 aOperation,
const TUint16 aSenderChannel,
const TDesC8& aData,
const TAny* aChannelPtr ) = 0;
/**
* Send data to Domestic OS
* @since 2.8
* @param aOperation Used to distinguish whether it is a synchronous
* or asynchronous Send request ( EIscSyncDataSend / EIscAsyncDataSend )
* @param aSenderChannel Sender channel id
* @param aData Data to be sent
* @param aChannelPtr DIscChannel pointer
* @return KErrNone if successful
*/
virtual TInt DataSend( const TUint16 aOperation,
const TUint16 aSenderChannel,
const TDesC8& aData,
const TAny* aChannelPtr ) = 0;
/**
* Retrieve information on the incoming frame
* @since 2.8
* @param aFrame Frame which info to retrieve
* @param aFrameInfo Structure that the multiplexer must fill
* @return void
*/
virtual void GetFrameInfo( const TDesC8& aFrame,
TIscFrameInfo& aFrameInfo ) const = 0;
/**
* Retrieve the channel this frame belongs to
* @since 2.8
* @param aFrame Frame to check
* @param aRcvChannelId Receiver channel id has to written into this
* variable. Value should be between 0 and 63. KIscFrameReceiverNotFound
* should be returned if multiplexer could not determine correct receiver
* or multiplexer just wants to delete the frame. For multiplexer's purposes
* channel ids higher than 63 are also possible
* @param aRcvChannelPtr Receiver channel pointer. If routing to control channel
* NULL should be returned an 0 to aRcvChannelId
* @return void
*/
virtual void GetRcvChannelId( const TDesC8& aFrame,
TUint16& aRcvChannelId,
TAny*& aRcvChannelPtr ) = 0;
/**
* Set flow control to specified state
* @since 2.8
* @param aFlowStatus EIscFlowControlOn / EIscFlowControlOff
* @param aChannelId Channel who requested to DL flow control change
* @param aChannelPtr DIscChannel pointer for corresponding channel
* @return void
*/
virtual void DLFlowControl( const TInt aFlowStatus,
const TUint16 aChannelId,
const TAny* aChannelPtr ) = 0;
/**
* Handle frames going to control channel ( channel zero )
* @since 2.8
* @param aFrame Control frame to be handled
* @return void
*/
virtual void HandleControlFrame( const TDesC8& aFrame ) = 0;
/**
* Notify multiplexer that some asynchronous operation has been
* cancelled
* @since 2.8
* @param aChannelId Channel id which has cancelled the operation
* @param aOperation The operation that has been cancelled
* @param aChannelPtr Channel pointer which has cancelled the operation
* @return void
*/
virtual void CancelNotify( const TUint16 aChannelId,
const TUint16 aOperation,
const TAny* aChannelPtr ) = 0;
/**
* API extension function
* @since 2.8
* @param aChannelId Channel id that is executing the operation
* @param aOperation Which custom operation to execute
* @param aParameters Additional parameters, NULL if omitted
* @param aChannelPtr Pointer to DIscChannel
* @return TInt KErrNone if successful. KErrNotSupported if the
* operation that was requested is not supported by the multiplexer
*/
IMPORT_C virtual TInt CustomFunction( const TUint16 aChannelId,
const TUint16 aOperation,
TAny* aParameters,
const TAny* aChannelPtr );
/**
* Get information on specified channel
* @since 2.8
* @param aChannelNumber The channel, which information is required
* @param aInfo Buffer in client address space where to write the data
* @return TInt KErrNone if successful. KErrNotSupported if not supported
* by the multiplexer
*/
IMPORT_C virtual TInt GetChannelInfo( const TUint16 aChannelNumber,
TDes8& aInfo );
/**
* Get maximun data size ( for sending and receiving )
* @since 2.8
* @param aChannelId Channel which needed maximum data size is queried
* @return TInt Maximun data size in bytes
*/
virtual TInt MaximumDataSize( const TUint16 aChannelId ) = 0;
/**
* Inform multiplexer on connection status changes
* @since 2.8
* @param aConnectionStatus EIscConnectionOk / EIscConnectionNotOk
* @return void
*/
virtual void NotifyConnectionStatus( const TInt aConnectionStatus ) = 0;
/**
* Connect ISC Driver to ISC Multiplexer
* @since 2.8
* @param aDevice Pointer to DIscDevice class of ISC Driver
* @return void
*/
IMPORT_C virtual void Connect( DIscDevice* aDevice );
/**
* Get buffer configurations from ISC Multiplexer
* @since 2.8
* @param aConfig Configuration data structure that the multiplexer must fill
* @return void
*/
virtual void GetConfiguration( TIscConfiguration& aConfig ) = 0;
protected: // New functions
/**
* Complete specified asynchronous request
* @since 2.8
* @param aReqNumber Request to complete ( possible values in
* IscDefinitions.h )
* @param aStatus Error code, KErrNone if the operation in question
* was successful
* @param aChannelPtr The channel, which request to complete
* @return void
*/
IMPORT_C void CompleteRequest( TUint16 aReqNumber,
TInt aStatus,
const TAny* aChannelPtr );
/**
* Check if specified request is pending in ISC Driver
* @since 2.8
* @param aReqNumber Request to check if pending
* @param aChannelId The channel, which to check for the request
* @return TInt KRequestPending if the request is pending. KErrNone if
* request is not pending
*/
IMPORT_C TInt IsPending( const TUint16 aReqNumber,
const TAny* aChannelId );
/**
* Queue frame for sending
* @since 2.8
* @param aChannelId On which channels queue to add the frame. Value
* must be between 0 and 63. 0( zero ) refers to the control channel.
* @param aFrame Frame to send
* @param aMultiplexerDfc Dfc to run when frame transmission to modem has been done
* @param aMultiplexerErrorCode error if data transmsission was succesful or not
* @return TInt KErrNone if successful. KErrNotFound if the channel
* in question was not open
*/
IMPORT_C TInt QueueFrame( const TUint16 aChannelId,
const TDesC8* aFrame,
const TAny* aChannelPtr,
TAny* aFrameInfo = NULL );
/**
* Start sending the frames
* @since 2.8
* @return void
*/
IMPORT_C void FlushQueues();
/**
* Notify flow control changes to ISC Driver
* @since 2.8
* @param aULFlowStatus Uplink flow control status,
* EIscFlowControlOff/EIscFlowControlOn
* @param aChannelId Channel to be affected by the flow control
* @param aChannel Channel to be affected by the flow control, NULL if wanted to have
* effect on all channels within this id. By default it affects all channels
* @return void
*/
IMPORT_C void ULFlowControl( const TInt aULFlowStatus,
const TUint16 aChannelId,
TAny* aChannelPtr = NULL );
/**
* Reserve memory block
* @since 2.8
* @param aPtr Pointer to reserved memory block, NULL if not successful
* @param aSize Required minimun size of the block
* @return void
*/
IMPORT_C void ReserveMemoryBlock( TDes8*& aPtr,
const TUint16 aSize );
/**
* Release memory block allocated with ReserveMemoryBlock
* @since 2.8
* @param aPtr Pointer to memory block to be released
* @return void
*/
IMPORT_C void ReleaseMemoryBlock( TDes8* aPtr );
/**
* Copy data from user buffer to kernel side buffer by multiplexer.
* This method will be deprecated in the future.
* It is preffered to use GetThreadPtr instead.
* @since 2.8
* @param aUserBuffer pointer to source descriptor
* @param aKernelBuffer pointer to destination descriptor
* @param aChannelPtr DIscChannel pointer
* @param aOffset Offset of the source buffer
* @return KErrNone if successful
*/
IMPORT_C TInt CopyFromUserBuffer( const TDesC8& aUserBuffer,
TDes8& aKernelBuffer,
const TAny* aChannelPtr,
const TInt aOffset = 0 );
/**
* Copy data to user side buffer from kernel side by multiplexer.
* This method will be deprecated in the future.
* It is preffered to use GetThreadPtr instead.
* @since 2.8
* @param aUserBuffer pointer to destination descriptor
* @param aKernelBuffer pointer to source descriptor
* @param aChannelPtr DIscChannel pointer
* @param aOffset Offset of the destination buffer
* @return KErrNone if succesful
*/
IMPORT_C TInt CopyToUserBuffer( TAny* aUserBuffer,
const TDesC8& aKernelBuffer,
const TAny* aChannelPtr,
const TInt aOffset = 0 );
/**
* Description_here
* @since 2.8
* @param aChannelId Channel whose queued send frames should be deleted
* @param aChannelPtr Corresponding DIscChannel pointer
* @return TInt KErrNone if succesful
*/
IMPORT_C TInt CancelSending( const TUint16 aChannelId, const TAny* aChannelPtr );
/**
* Returns a user side thread of a given channel. Returns NULL if channelptr
* is not valid or if the channel is not found.
* @since 3.0
* @param const TAny* aChannelPtr, channel pointer (DIscChannel).
* @return DThread&, user side clients thread. Ownership is not given.
*/
IMPORT_C DThread* GetThreadPtr( const TAny* aChannelPtr );
protected: // Data
// pointer to DIscDevice class from ISC Driver
DIscDevice* iDevice; // No ownership
};
#endif // ISCMULTIPLEXERBASE_H
// End of File