/*
* Copyright (c) 2002-2010 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:  API for managing WIM Security Module
*
*/



#ifndef WIMSECMODULE_H
#define WIMSECMODULE_H

//  INCLUDES
#include "WimClsv.h"
#include <e32base.h>

// FORWARD DECLARATIONS
class CWimPin;
class RWimMgmt;


// CLASS DECLARATION

/**
*  API for managing WIM Security Module.
*  Provides methods to manage one WIM Security Module:
*  check statuses, change settings, use functionality 
*  provide it and list PINs.
*
*  @lib WimClient
*  @since Series 60 2.1
*/
class CWimSecModule: public CActive
    {
    public:  // Constructors and destructor
                    
        /**
        * Two-phased constructor.
        * @param aWimAddr
        */
        IMPORT_C static CWimSecModule* NewL( TWimAddress aWimAddr ); 
        
        /**
        * Destructor.
        */
        IMPORT_C virtual ~CWimSecModule();

    public: // New functions
            
        /**
        * Checks is WIM already open.
        * @return ETrue if WIM's is open (=PIN-G verified)
        *         else EFalse  
        */
        IMPORT_C TBool IsOpen(); 

        /**
        * Returns the time which is set as WIM closeout time
        * @return Timeout in minutes
        */
        IMPORT_C TInt CloseAfter();

        /**
        * Returns the timeout which tells how 
        * long WIM Security Module will be open 
        * after it is opened.
        * @return Timeout in minutes
        */
        IMPORT_C TInt TimeRemaining();

        
        /**
        * Returns WIM Security Module's keys' PIN-NR objects in array.
        * @param aPinNRs -Array of pointers to CWimPin objects which
        *                are initialized as PIN-NR. (IN/OUT)
        * @return TInt  -Error code
        */
        IMPORT_C TInt PinNrEntriesL( const CArrayPtrFlat<CWimPin>*& aPinNRs, TRequestStatus& aStatus  );
     
        /**
        * Returns WIM Security Module's keys' PIN-NR objects in array.
        * @param aPinNRs -Array of pointers to CWimPin objects which
        *                are initialized as PIN-NR. (IN/OUT)
        * @return TInt  -Error code
        */
        IMPORT_C TInt PinNrEntriesL( const CArrayPtrFlat<CWimPin>*& aPinNRs );
        
        /**
        * Returns WIM's version. This will return KErrNone according to PKC15. 
        * @return Pointer descriptor containing version.
        */
        IMPORT_C const TDesC& Version();

        /**
        * Returns WIM's label.
        * @return Pointer descriptor containing label.
        */
        IMPORT_C TPtrC Label();

        /**
        * Returns WIM's manufacturer.
        * @return Pointer descriptor containing manufacturer.
        */
        IMPORT_C const TDesC& Manufacturer();

        /**
        * Returns WIM's serial number which identifies it.
        * @return Pointer descriptor containing serial number
        */
        IMPORT_C const TDesC& SerialNumber();

        /**
        * Closes the parts of WIM which is opened with PIN-G.
        * @return TInt Error code
        */
        IMPORT_C TInt Close();

        /**
        * Sets the timeout which defines the time after WIM 
        * is automatically closed.
        * @param aTimeout, timeout in minutes.
        * @return void
        */
        IMPORT_C void SetCloseAfter( const TUint aTimeout );


        /**
        * Notifies the client when the token has been removed.
        * @param aStatus -TRequestStatus
        * @return void
        */
        IMPORT_C void NotifyOnRemoval( TRequestStatus& aStatus );

        /**
        * Cancels the notifyOnRemoval request.
        * @return void
        */
        IMPORT_C void CancelNotifyOnRemoval();

        /**
        * Returns the number of the slot, where current token is connected
        * @return TUint8
        */
        IMPORT_C TUint8 TokenNumber();

        /**
        * Sets pointer RWimMgmt object to modifier iClientSession
        * @param aClientSession Client session
        * @return void
        */
        void SetClientSession( RWimMgmt* aClientSession );


    private:

        /**
        * C++ constructor.
        * @param aWimAddr
        */
        CWimSecModule( TWimAddress aWimAddr );

        /**
        * By default EPOC constructor is private.
        */
        void ConstructL();


        /**
        * Gets label,manufacturer,serialnumber and the number of 
        * the slot where card is.
        * @return TInt
        */
        TInt GetWIMInfoL(); 

        /** 
        * Handles cleanup for an TPinAddress array allocated using new[].
        * @param aObject - TPinAddress list to be cleaned up
        */
        static void CleanupPinAddressList( TAny* aObject );

        /** 
        * Converts serialnumber to 8-bit form. Conversion reads
        * memory area from orginal serialnumber and captures its significant
        * bits to a new 8-bit -modifier. 
        * @param aSerialNumber -number to be converted
        * @return void
        */
        void ConvertSerialNumberL( HBufC*& aSerialNumber );
        
    private:  
        
        /**
        * Gets PIN references and creates new CWimPin objects
        * @return TInt  -Error code
        */
        TInt GetPINModulesL( TRequestStatus& aStatus );
        
        /**
        * Gets PIN references and creates new CWimPin objects
        * @return TInt  -Error code
        */
        TInt GetPINModulesL();
        
    private: //from CActive
        
        /**
        * Different phases are handled here.
        * @return void
        */
        void RunL();
        
        /**
        * Cancellation function
        * Deallocates member variables and completes client status with
        * KErrCancel error code.
        * @return void
        */
        void DoCancel();

        /**
        * The active scheduler calls this function if this active 
        * object's RunL() function leaves. 
        * Handles neccessary cleanup and completes request with
        * received error code.
        * @param aError -Error code which caused this event
        * @return TInt  -Error code to active scheduler, is always KErrNone.
        */ 
        TInt RunError( TInt aError );    
  
    private: 

        // Reference to WIM. 
        TWimAddress             iReference;  
        // Array of pointers to PIN-NRs.This class owns this and
        // this is valid as long as CWimSecModule is valid.
        CArrayPtrFlat<CWimPin>* iPinNRs; 
        //Contains tokens label.Owned
        HBufC*                  iLabel;
        //Contains tokens manufacturer.Owned
        HBufC*                  iManufacturer;
        //Contains tokens SerialNumber.Owned
        HBufC*                  iSerialNumber;
        //Contains tokens version. Owned
        HBufC*                  iVersion;
        //The "slot" where WIM-card is inserted
        TUint8                  iReader;        
        //pointer to RWIMMgmt. Owned by CWimSecModuleMgr.
        RWimMgmt*               iClientSession;
        //Boolean value 
        TBool                   iWimInfoConstructed;
        //TUint32, reference to pinlist.
        TUint32                 iPinLstAddr;
        //TUint32, reference to ping.
        TPinAddress             iRefPing;
        
        TWimPinStruct*          iPinStructLst; //Owned
        
        TRequestStatus*         iClientStatus;
        
        TUint                   iPinCount;
        
        CArrayFixFlat<TWimPinStruct>* iPinInfoLst; //Owned
        //ETrue if iPinNRs is initialized
        TBool                   iPinNRsInit;

    };

#endif      // WIMSECMODULE_H   
            
// End of File
