systemswstubs/examplecommonisc/IscMultiplexerBase/inc/IscMultiplexerBase.h
changeset 0 0ce1b5ce9557
equal deleted inserted replaced
-1:000000000000 0:0ce1b5ce9557
       
     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