1 /*

     2 * Copyright (c) 2003 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:  This object is the one responsible for trafficing between

    15 *               the Smart Card reader and the sessions.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef CSCARDACCESSCONTROL_H

    22 #define CSCARDACCESSCONTROL_H

    23 

    24 //  INCLUDES

    25 #include "ScardDefs.h"

    26 #include "ScardChannelManager.h" // required by inline functions

    27 

    28 // FORWARD DECLARATIONS

    29 class CScardSession;

    30 class MScardReader;

    31 class CScardMessageRegistry;

    32 class CScardAccessControl;

    33 class CScardAccessControlRegistry;

    34 class CScardCommandTimer;

    35 class CScardChannelManager;

    36 

    37 // CLASS DECLARATION

    38 

    39 /**

    40 *  Handles traffic between the Smart Card reader and the sessions.

    41 *  

    42 *  @lib Scard.lib

    43 *  @since Series60 2.1

    44 */

    45 class CScardAccessControl : public CActive

    46     {

    47     public:  // Constructors and destructor

    48 

    49         /**

    50         * Two-phased constructor.

    51         * @param aReaderID Reader ID

    52         * @param aControl Pointer to AccessControlRegistry

    53         */

    54         static CScardAccessControl* NewL(

    55             const TReaderID aReaderID, 

    56             CScardAccessControlRegistry* aControl );

    57 

    58         /**

    59         * Destructor.

    60         */

    61         virtual ~CScardAccessControl();

    62     

    63     public: // New functions

    64         

    65         /**

    66         * Attach a new session to the reader.

    67         * @param aSession session

    68         * @param aSessionID session ID

    69         * @return Pointer to reader.

    70         */

    71         MScardReader* AttachSessionToReaderL( CScardSession* aSession, 

    72                                               TInt &aSessionID );

    73 

    74         /**

    75         * Is this session attached to this reader.

    76         * @param aSession session

    77         * @return true if session is attached.

    78         */

    79         TBool IsAttached( CScardSession* aSession ) const;

    80 

    81         /**

    82         * Detach a connection between reader and session.

    83         * @param aSessionID session ID

    84         * @return void

    85         */

    86         void DetachSessionFromReader( const TInt aSessionID );

    87     

    88         /**

    89         * Initialise reader by calling Open.

    90         * @param aSessionID session ID

    91         * @param aMessage message

    92         * @return EFalse if succesful, ETrue if reader is already open.

    93         */

    94         TBool InitialiseReader( const TInt aSessionID, 

    95                                 const RMessage2& aMessage );

    96     

    97         /**

    98         * Is the reader available for data transmit

    99         * @param aSessionID session ID

   100         * @param aChannel channel

   101         * @return ETrue if reader is ready for data transmission.

   102         */

   103         TBool ReaderIsReady( const TInt aSessionID, 

   104                              const TInt8 aChannel ) const;

   105     

   106         /**

   107         * Set access control in a state that enables communication with the 

   108         * reader. Also sets control object active, and gives iStatus back to 

   109         * caller.

   110         * @param aSessionID session ID

   111         * @param aMessage message

   112         * @param aTimeOut time-out in microseconds (0 = no time-out).

   113         * @param aChannel Logical channel

   114         * @param aAdditionalParameter proprietary parameter sent to reader.

   115         * @return ETrue if reader is ready for data transmission.

   116         */

   117         TRequestStatus& InitiateCommunication(

   118             const TInt aSessionID, 

   119             const RMessage2& aMessage, 

   120             const TInt32 aTimeOut, 

   121             const TInt8 aChannel,

   122             const TUint8 aAdditionalParameter = 0x00 );

   123     

   124         /**

   125         * Free reader's reservation.

   126         * @param aSessionId session ID

   127         * @param aChannel channel

   128         */

   129         void FreeChannelL( const TInt aSessionID, const TInt8 aChannel );

   130 

   131         /**

   132         * Stack the given command for completion later.

   133         * @param aMessage message

   134         * @param aSessionID session ID

   135         * @param aTimeOut time-out in milliseconds (0 = no time-out).

   136         * @param aChannel channel

   137         */

   138         void QueueExecution( const RMessage2& aMessage,

   139                              const TInt aSessionID, 

   140                              const TInt32 aTimeOut,

   141                              const TInt8 aChannel, 

   142                              const TInt8 aParameter = 0 );

   143 

   144         /**

   145         * Stack the given command for completion later with slightly higher 

   146         * priority.

   147         * @param aMessage message

   148         * @param aSessionID session ID

   149         * @param aTimeOut time-out in milliseconds (0 = no time-out).

   150         * @param aChannel channel

   151         */

   152         void QueueChannelOperation( const RMessage2& aMessage, 

   153                                     const TInt aSessionID,

   154                                     const TInt32 aTimeOut, 

   155                                     const TInt8 aChannel );

   156 

   157         /**

   158         * Remove operations for the session from the stack.

   159         * @param aSessionID session ID

   160         */

   161         void DequeueOperations( const TInt aSessionID );

   162 

   163         /**

   164         * Handle a card event.

   165         * @param aEvent card event

   166         * @param aATR ATR-bytes

   167         */

   168         void CardEvent( const TScardServiceStatus aEvent, 

   169                         const TScardATR& aATR );

   170 

   171         /**

   172         * Cancel everything from the session.

   173         * @param aSessionID session ID

   174         */

   175         void CancelTransmissionsL( const TInt aSessionID );

   176 

   177         /**

   178         * Cancel an operation because the commands timer has run out.

   179         * @param aTimer command timer

   180         */

   181         inline void CancelByTimeOut( CScardCommandTimer* aTimer );

   182 

   183         /**

   184         * ID of the reader this object controls.

   185         * @return reader ID

   186         */

   187         inline const TReaderID ReaderID() const;

   188 

   189         /**

   190         * The reader object this object control.

   191         * @return pointer to reader object.

   192         */

   193         inline MScardReader* Reader() const;

   194 

   195         /**

   196         * Give a session access rigths to the channel.

   197         * @param aChannel channel

   198         * @param aSessionID session ID

   199         * @return ETrue on success.

   200         */

   201         inline const TBool AddSessionToChannelL( const TInt8 aChannel, 

   202                                                  const TInt aSessionID );

   203 

   204         /**

   205         * Remove the session from the channel.

   206         * @param aChannel channel

   207         * @param aSessionID session ID

   208         * @return ETrue on success.

   209         */

   210         inline const TBool RemoveSessionFromChannelL( const TInt8 aChannel, 

   211                                                       const TInt aSessionID );

   212 

   213         /**

   214         * Has a channel been opened yet.

   215         * @param aChannel channel

   216         * @return ETrue if channel has been opened.

   217         */

   218         inline const TBool ChannelOpenedYet( const TInt8 aChannel );

   219 

   220         /**

   221         * Getter for channel status.

   222         * @return channel status

   223         */

   224         inline TUint16 ChannelStatus();

   225 

   226         /**

   227         * Is the channel number legal, and is the session on the channel.

   228         * @param aChannel channel number

   229         * @param aSessionID session id

   230         */

   231         inline void ValidateChannelL( const TInt8 aChannel, 

   232                                       const TInt aSessionID );

   233 

   234         /**

   235         * Get next unreserved logical channel.

   236         * @return number of next unreserved logical channel

   237         */

   238         inline const TInt8 UnreservedLogicalChannel() const;

   239 

   240 

   241     private: // Functions from base classes

   242 

   243         /**

   244         * From CActive cancel the request.

   245         */

   246         void DoCancel();

   247 

   248         /**

   249         * From CActive complete the request.

   250         */

   251         void RunL();

   252 

   253     private:

   254 

   255         /**

   256         * C++ default constructor.

   257         * @param aReaderID Reader ID

   258         * @param aControl Pointer to AccessControlRegistry

   259         */

   260         CScardAccessControl( const TReaderID aReaderID, 

   261                              CScardAccessControlRegistry* aControl );

   262     

   263         /**

   264         * By default Symbian OS constructor is private.

   265         */

   266         void ConstructL();

   267     

   268         /**

   269         * Get a pointer to the session with ID aSessionID.

   270         * @param aSessionID Session ID

   271         * @return Pointer to session

   272         */

   273         CScardSession* SessionBase( const TInt aSessionID );

   274 

   275         /**

   276         * Handles next message.

   277         * @param aHandle Handle of message

   278         */

   279         inline void HandleNextMessageL( const TMessageHandle& aHandle );

   280 

   281     private:    // Data

   282 

   283         // Reader session struct

   284         struct TReaderSession

   285             {

   286             CScardSession* SessionBase;

   287             TInt SessionID;

   288             };

   289 

   290         // Life modes

   291         enum TLifeMode

   292             {

   293             ECanBeDeleted,

   294             ECanNotDelete,

   295             EDestroyASAP

   296             };

   297 

   298         //  Container for the client sessions

   299         CArrayFixFlat<TReaderSession>* iSessionRegistry;

   300     

   301         // state variables for the reader

   302         TBool           iReaderActive;

   303         TBool           iIsCreated;

   304         TBool           iIsOpen;

   305         TInt            iNextSessionID;

   306 

   307         //  the actual reader object parameters

   308         MScardReader* iReader;

   309         TReaderID     iReaderID;

   310 

   311         //  Owner of this object

   312         CScardAccessControlRegistry* iControlRegistry;

   313 

   314         //  Internal channel manager

   315         CScardChannelManager* iManager;

   316     

   317         //  ATR bytes of the SC in the reader this object controls

   318         TScardATR iATR;

   319 

   320         // Life mode

   321         TLifeMode iLifeMode;

   322         

   323     };

   324 

   325 #include "ScardAccessControl.inl"

   326 

   327 #endif  // CSCARDACCESSCONTROL_H

   328 

   329 // End of File