1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 #ifndef ISCMULTIPLEXERBASE_H

    20 #define ISCMULTIPLEXERBASE_H

    21 

    22 //  INCLUDES

    23 #include <kernel.h>

    24 #include <IscDefinitions.h>

    25 

    26 // CONSTANTS

    27 _LIT( KIscMultiplexerName,"IscMultiplexer" );

    28 

    29 const TUint16 KIscBufferAmount = 10;

    30 // MACROS

    31 

    32 // DATA TYPES

    33 

    34 typedef struct

    35 {

    36    TIscFrameType frameType;

    37    TIscFrameConcatenation concatenation;

    38    TUint16 totalLength;

    39    TUint16 writeStartIndex;

    40    TUint16 writeLength;

    41 } TIscFrameInfo;

    42 

    43 typedef struct

    44 {

    45    TUint16 size;

    46    TUint16 count;

    47 } TIscBufferEntry;

    48 

    49 typedef struct

    50 {

    51    TUint16 mainRcvQueueSize;

    52    TUint16 channelRcvQueueSize;

    53    TUint16 channelDataRcvQueueSize;

    54    TUint16 channelSendQueueSize;

    55    TIscBufferEntry bufferConfig[KIscBufferAmount];

    56 } TIscConfiguration;

    57 

    58 // FUNCTION PROTOTYPES

    59 

    60 // FORWARD DECLARATIONS

    61 class DIscDevice;

    62 

    63 // CLASS DECLARATION

    64 

    65 /**

    66 *  DIscMultiplexerBase defines the ISC Multiplexer Plug-In API.

    67 *  This class defines the base class for Multiplexer( s ) used in 

    68 *  conjunction with ISC Driver

    69 *

    70 *  @lib IscMultiplexerBase.LIB

    71 *  @since 2.8

    72 */

    73 class DIscMultiplexerBase : public DLogicalDevice

    74     {

    75     public:  // Constructors and destructor

    76 

    77         /**

    78         * C++ default constructor.

    79         */        

    80         IMPORT_C DIscMultiplexerBase();

    81         

    82         /**

    83         * Destructor

    84         */

    85         IMPORT_C virtual ~DIscMultiplexerBase();

    86 

    87     public: // Functions from base class

    88         

    89         /**

    90         * Implementation of pure-virtual Install from DLogicalDevice. This 

    91         * function calls Install2ndPhase.

    92         * @since 2.8

    93         * @return TInt KErrNone

    94         */

    95         IMPORT_C TInt Install();

    96 

    97     public: // New functions

    98         /**

    99         * Second phase initialization, called during ISC Multiplexer loading

   100         * ISC Multiplexer must do all initialization here that are normally 

   101         * done in Install()

   102         * @since 2.8

   103         * @return TInt KErrNone if successful

   104         */

   105         virtual TInt Install2ndPhase() = 0;

   106         

   107         /**

   108         * Multiplexers "pre" intialization before Data transmission driver 

   109         * initialization has been done ( e.g. if buffer configurations are given from isc_config.ini )

   110         * @since 2.8

   111         * @param aParameters Additional parameters passed to multiplexer

   112         * @return void 

   113         */

   114         IMPORT_C virtual void SetInitializationParameters( const TDesC8& aParameters );

   115 

   116         /**

   117         * Multiplexer intialization

   118         * @since 2.8

   119         * @param aOperation The asynchronous request to complete after

   120         * multiplexer intialization is complete

   121         * @param aParameters Additional parameters passed to multiplexer

   122         * @param aChannelPtr DIscChannel pointer

   123         * @return void 

   124         */

   125         virtual void InitializeMultiplexer( const TUint16 aOperation, 

   126                                             const TDesC8& aParameters,

   127                                             const TAny* aChannelPtr ) = 0;

   128 

   129         /**

   130         * Open data link connection with the modem

   131         * @since 2.8

   132         * @param aDLCI The channel id to open

   133         * @param aOpenParams Additional open parameters given by the ISC user,

   134         * NULL if omitted

   135         * @param aChannelPtr DIscChannel pointer

   136         * @return void 

   137         */

   138         virtual void OpenDLC( const TUint16 aDLCI, 

   139                               const TDesC8* aOpenParams,

   140                               const TAny* aChannelPtr ) = 0;

   141 

   142         /**

   143         * Close data link connection

   144         * @since 2.8

   145         * @param aDLCI The channel id to close

   146         * @param aChannelPtr DIscChannel pointer

   147         * @return void 

   148         */

   149         virtual void CloseDLC( const TUint16 aDLCI,

   150                                const TAny* aChannelPtr ) = 0;

   151 

   152         /**

   153         * Send data to Domestic OS

   154         * @since 2.8

   155         * @param aOperation Used to distinguish whether it is a synchronous 

   156         * or asynchronous Send request ( EIscSyncSend / EIscAsyncSend )

   157         * @param aSenderChannel Sender channel id

   158         * @param aData Data to be sent

   159         * @param aChannelPtr DIscChannel pointer

   160         * @return KErrNone if successful 

   161         */

   162         virtual TInt Send( const TUint16 aOperation,

   163                            const TUint16 aSenderChannel, 

   164                            const TDesC8& aData,

   165                            const TAny* aChannelPtr ) = 0;

   166         /**

   167         * Send data to Domestic OS

   168         * @since 2.8

   169         * @param aOperation Used to distinguish whether it is a synchronous 

   170         * or asynchronous Send request ( EIscSyncDataSend / EIscAsyncDataSend )

   171         * @param aSenderChannel Sender channel id

   172         * @param aData Data to be sent

   173         * @param aChannelPtr DIscChannel pointer

   174         * @return KErrNone if successful 

   175         */

   176         virtual TInt DataSend( const TUint16 aOperation,

   177                                const TUint16 aSenderChannel,

   178                                const TDesC8& aData,

   179                                const TAny* aChannelPtr ) = 0;

   180 

   181         

   182         /**

   183         * Retrieve information on the incoming frame

   184         * @since 2.8

   185         * @param aFrame Frame which info to retrieve

   186         * @param aFrameInfo Structure that the multiplexer must fill

   187         * @return void 

   188         */

   189         virtual void GetFrameInfo( const TDesC8& aFrame, 

   190                                    TIscFrameInfo& aFrameInfo ) const = 0;

   191 

   192         /**

   193         * Retrieve the channel this frame belongs to

   194         * @since 2.8

   195         * @param aFrame Frame to check

   196         * @param aRcvChannelId Receiver channel id has to written into this

   197         * variable. Value should be between 0 and 63. KIscFrameReceiverNotFound

   198         * should be returned if multiplexer could not determine correct receiver 

   199         * or multiplexer just wants to delete the frame. For multiplexer's purposes 

   200         * channel ids higher than 63 are also possible

   201         * @param aRcvChannelPtr Receiver channel pointer. If routing to control channel

   202         * NULL should be returned an 0 to aRcvChannelId

   203         * @return void 

   204         */

   205         virtual void GetRcvChannelId( const TDesC8& aFrame, 

   206                                       TUint16& aRcvChannelId,

   207                                       TAny*& aRcvChannelPtr ) = 0;

   208 

   209         /**

   210         * Set flow control to specified state

   211         * @since 2.8

   212         * @param aFlowStatus EIscFlowControlOn / EIscFlowControlOff

   213         * @param aChannelId Channel who requested to DL flow control change

   214         * @param aChannelPtr DIscChannel pointer for corresponding channel

   215         * @return void 

   216         */

   217         virtual void DLFlowControl( const TInt aFlowStatus,

   218                                     const TUint16 aChannelId,

   219                                     const TAny* aChannelPtr ) = 0;

   220 

   221         /**

   222         * Handle frames going to control channel ( channel zero )

   223         * @since 2.8

   224         * @param aFrame Control frame to be handled

   225         * @return void 

   226         */

   227         virtual void HandleControlFrame( const TDesC8& aFrame ) = 0;

   228         

   229         /**

   230         * Notify multiplexer that some asynchronous operation has been

   231         * cancelled

   232         * @since 2.8

   233         * @param aChannelId Channel id which has cancelled the operation

   234         * @param aOperation The operation that has been cancelled

   235         * @param aChannelPtr Channel pointer which has cancelled the operation

   236         * @return void 

   237         */

   238         virtual void CancelNotify( const TUint16 aChannelId,

   239                                    const TUint16 aOperation,

   240                                    const TAny* aChannelPtr ) = 0;

   241 

   242         /**

   243         * API extension function

   244         * @since 2.8

   245         * @param aChannelId Channel id that is executing the operation

   246         * @param aOperation Which custom operation to execute

   247         * @param aParameters Additional parameters, NULL if omitted

   248         * @param aChannelPtr Pointer to DIscChannel

   249         * @return TInt KErrNone if successful. KErrNotSupported if the

   250         * operation that was requested is not supported by the multiplexer

   251         */

   252         IMPORT_C virtual TInt CustomFunction( const TUint16 aChannelId,

   253                                               const TUint16 aOperation, 

   254                                               TAny* aParameters,

   255                                               const TAny* aChannelPtr );

   256 

   257         /**

   258         * Get information on specified channel

   259         * @since 2.8

   260         * @param aChannelNumber The channel, which information is required

   261         * @param aInfo Buffer in client address space where to write the data

   262         * @return TInt KErrNone if successful. KErrNotSupported if not supported 

   263         * by the multiplexer

   264         */

   265         IMPORT_C virtual TInt GetChannelInfo( const TUint16 aChannelNumber,

   266                                               TDes8& aInfo );

   267 

   268         /**

   269         * Get maximun data size ( for sending and receiving )

   270         * @since 2.8

   271         * @param aChannelId Channel which needed maximum data size is queried

   272         * @return TInt Maximun data size in bytes 

   273         */

   274         virtual TInt MaximumDataSize( const TUint16 aChannelId ) = 0; 

   275 

   276         /**

   277         * Inform multiplexer on connection status changes

   278         * @since 2.8

   279         * @param aConnectionStatus EIscConnectionOk / EIscConnectionNotOk

   280         * @return void 

   281         */

   282         virtual void NotifyConnectionStatus( const TInt aConnectionStatus ) = 0;

   283 

   284         /**

   285         * Connect ISC Driver to ISC Multiplexer

   286         * @since 2.8

   287         * @param aDevice Pointer to DIscDevice class of ISC Driver

   288         * @return void 

   289         */

   290         IMPORT_C virtual void Connect( DIscDevice* aDevice );

   291 

   292         /**

   293         * Get buffer configurations from ISC Multiplexer

   294         * @since 2.8

   295         * @param aConfig Configuration data structure that the multiplexer must fill

   296         * @return  void 

   297         */

   298         virtual void GetConfiguration( TIscConfiguration& aConfig ) = 0;

   299 

   300 

   301     protected:  // New functions

   302         

   303         /**

   304         * Complete specified asynchronous request

   305         * @since 2.8

   306         * @param aReqNumber Request to complete ( possible values in 

   307         * IscDefinitions.h )

   308         * @param aStatus Error code, KErrNone if the operation in question

   309         * was successful

   310         * @param aChannelPtr The channel, which request to complete

   311         * @return void 

   312         */

   313         IMPORT_C void CompleteRequest( TUint16 aReqNumber, 

   314                                        TInt aStatus, 

   315                                        const TAny* aChannelPtr );

   316      

   317         /**

   318         * Check if specified request is pending in ISC Driver

   319         * @since 2.8

   320         * @param aReqNumber Request to check if pending

   321         * @param aChannelId The channel, which to check for the request

   322         * @return TInt KRequestPending if the request is pending. KErrNone if 

   323         * request is not pending

   324         */

   325         IMPORT_C TInt IsPending( const TUint16 aReqNumber, 

   326                                  const TAny* aChannelId );

   327 

   328         /**

   329         * Queue frame for sending

   330         * @since 2.8

   331         * @param aChannelId On which channels queue to add the frame. Value

   332         * must be between 0 and 63. 0( zero ) refers to the control channel.

   333         * @param aFrame Frame to send

   334         * @param aMultiplexerDfc Dfc to run when frame transmission to modem has been done

   335         * @param aMultiplexerErrorCode error if data transmsission was succesful or not

   336         * @return TInt KErrNone if successful. KErrNotFound if the channel 

   337         * in question was not open 

   338         */        

   339         IMPORT_C TInt QueueFrame( const TUint16 aChannelId,

   340                                   const TDesC8* aFrame,

   341                                   const TAny* aChannelPtr,

   342                                   TAny* aFrameInfo = NULL );

   343 

   344         /**

   345         * Start sending the frames

   346         * @since 2.8

   347         * @return void 

   348         */

   349         IMPORT_C void FlushQueues();

   350 

   351         /**

   352         * Notify flow control changes to ISC Driver

   353         * @since 2.8

   354         * @param aULFlowStatus Uplink flow control status, 

   355         * EIscFlowControlOff/EIscFlowControlOn

   356         * @param aChannelId Channel to be affected by the flow control

   357         * @param aChannel Channel to be affected by the flow control, NULL if wanted to have 

   358         * effect on all channels within this id. By default it affects all channels

   359         * @return void 

   360         */

   361         IMPORT_C void ULFlowControl( const TInt aULFlowStatus,

   362                                      const TUint16 aChannelId,

   363                                      TAny* aChannelPtr = NULL );

   364 

   365         /**

   366         * Reserve memory block

   367         * @since 2.8

   368         * @param aPtr Pointer to reserved memory block, NULL if not successful

   369         * @param aSize Required minimun size of the block

   370         * @return void 

   371         */

   372         IMPORT_C void ReserveMemoryBlock( TDes8*& aPtr, 

   373                                           const TUint16 aSize );

   374 

   375         /**

   376         * Release memory block allocated with ReserveMemoryBlock

   377         * @since 2.8

   378         * @param aPtr Pointer to memory block to be released

   379         * @return void 

   380         */

   381         IMPORT_C void ReleaseMemoryBlock( TDes8* aPtr );

   382 

   383         

   384         /**

   385         * Copy data from user buffer to kernel side buffer by multiplexer.

   386         * This method will be deprecated in the future.

   387         * It is preffered to use GetThreadPtr instead.          

   388         * @since 2.8

   389         * @param aUserBuffer pointer to source descriptor

   390         * @param aKernelBuffer pointer to destination descriptor

   391         * @param aChannelPtr DIscChannel pointer

   392         * @param aOffset Offset of the source buffer

   393         * @return KErrNone if successful

   394         */

   395         IMPORT_C TInt CopyFromUserBuffer( const TDesC8& aUserBuffer,

   396                                           TDes8& aKernelBuffer,

   397                                           const TAny* aChannelPtr,

   398                                           const TInt aOffset = 0 );

   399 

   400         /**

   401         * Copy data to user side buffer from kernel side by multiplexer.

   402         * This method will be deprecated in the future.

   403         * It is preffered to use GetThreadPtr instead.        

   404         * @since 2.8

   405         * @param aUserBuffer pointer to destination descriptor

   406         * @param aKernelBuffer pointer to source descriptor

   407         * @param aChannelPtr DIscChannel pointer

   408         * @param aOffset Offset of the destination buffer

   409         * @return KErrNone if succesful

   410         */

   411         IMPORT_C TInt CopyToUserBuffer( TAny* aUserBuffer, 

   412                                         const TDesC8& aKernelBuffer, 

   413                                         const TAny* aChannelPtr,

   414                                         const TInt aOffset = 0 );

   415 

   416 

   417         /**

   418         * Description_here

   419         * @since 2.8

   420         * @param aChannelId Channel whose queued send frames should be deleted

   421         * @param aChannelPtr Corresponding DIscChannel pointer

   422         * @return TInt KErrNone if succesful

   423         */

   424         IMPORT_C TInt CancelSending( const TUint16 aChannelId, const TAny* aChannelPtr );

   425 

   426 

   427         /**

   428         * Returns a user side thread of a given channel. Returns NULL if channelptr

   429         * is not valid or if the channel is not found.

   430         * @since 3.0

   431         * @param const TAny* aChannelPtr, channel pointer (DIscChannel).

   432         * @return DThread&, user side clients thread. Ownership is not given.

   433         */

   434         IMPORT_C DThread* GetThreadPtr( const TAny* aChannelPtr );

   435     

   436     

   437     protected:  // Data

   438         

   439         // pointer to DIscDevice class from ISC Driver

   440         DIscDevice* iDevice; // No ownership

   441 

   442     };

   443 

   444 #endif      // ISCMULTIPLEXERBASE_H   

   445             

   446 // End of File