1 /*

     2 * Copyright (c) 2002 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:  API for listing all WIM Security Modules

    15 *

    16 */

    17 

    18 

    19 #ifndef WIMSECMODULEMGR_H

    20 #define WIMSECMODULEMGR_H

    21 

    22 //  INCLUDES

    23 #include "WimClsv.h"

    24 #include "WimSig.h"

    25 #include <e32base.h>

    26 #include <ct.h> 

    27 

    28 // FORWARD DECLARATIONS

    29 class CWimSecModule;

    30 class RWimMgmt;

    31 

    32 

    33 // CLASS DECLARATION

    34 /**

    35 *  API for list all WIM Security Modules

    36 *  This API provides function to list all WIM Security Modules

    37 *  which your device finds. Listed CWimSecModule objects provides 

    38 *  methods to manage key stores. 

    39 *

    40 *  @lib WimClient

    41 *  @since Series 60 2.1

    42 */

    43 class CWimSecModuleMgr: public CActive

    44     {

    45     public:  

    46         

    47         /**

    48         * Two-phased constructor.

    49         */

    50         IMPORT_C static CWimSecModuleMgr* NewL(); 

    51          

    52         /**

    53         * Destructor.

    54         */

    55         IMPORT_C virtual ~CWimSecModuleMgr();

    56 

    57     public: // New functions

    58         

    59         /**

    60         * Returns all WIM Security Modules in array. 

    61         * @param  aTokens     Array containing all WIMs.(OUT)

    62         * @param  aStatus   Status from caller.         

    63         * @return void

    64         */

    65         IMPORT_C void GetEntries( RCPointerArray<HBufC>& aTokens, 

    66             TRequestStatus& aStatus );

    67         

    68 

    69         /**

    70         * Cancels listing operation. 

    71         * @return void

    72         */        

    73         IMPORT_C void CancelList();

    74 

    75         /**

    76         * Returns the number of WIM cards

    77         * If WIM is not initialized and listing operation completed

    78         * before calling WimCount(), this will return KErrNotFound.

    79         * @return TInt     aNumber of wims.

    80         */        

    81         IMPORT_C TInt WimCount();

    82 

    83         /**

    84         * Returns CWimSecModule according to received index.

    85         * If WIM is not initialized and listing operation completed

    86         * before calling this function, User::Leave( KErrNotFound )

    87         * is called.        

    88         * @param aIndex -needed element from array.

    89         * @return CWimSecModule*  -the element from array.

    90         */

    91         IMPORT_C CWimSecModule* GetWimSecModuleByIndexL( 

    92             const TInt aIndex );

    93 

    94         /** 

    95         * Returns WIM label according to received index.

    96         * If WIM is not initialized and listing operation completed

    97         * before calling this function, User::Leave( KErrNotFound )

    98         * is called.                

    99         * @param aIndex -wanted index from array.

   100         * @return TPtrC -pointer to label.

   101         */

   102         IMPORT_C TPtrC WimLabelByIndexL( const TInt aIndex );

   103 

   104         /** 

   105         * Returns the number of "slot" where current token is attached.

   106         * If WIM is not initialized and listing operation completed

   107         * before calling this function, User::Leave( KErrNotFound )

   108         * is called.                

   109         * @param aIndex -needed index from array.

   110         * @return TInt -the place where token is attached.

   111         */

   112         IMPORT_C TInt WimTokenNumberByIndexL( const TInt aIndex );

   113 

   114         

   115     private:

   116         

   117         /**

   118         * C++ default constructor.

   119         */

   120         CWimSecModuleMgr();

   121 

   122     

   123         /**

   124         * By default Symbian 2nd phase constructor is private

   125         */

   126         void ConstructL();

   127 

   128         /**

   129         * Frees memory & preferences that have been allocated.

   130         * @return void

   131         */

   132         void DeAllocateWimReferences();

   133 

   134     private: 

   135         

   136 

   137         /**

   138         * Sets own iStatus to KRequestPending, and signals it 

   139         * with User::RequestComplete() request. This gives chance 

   140         * to active scheduler to run other active objects. After a quick

   141         * visit in active scheduler, signal returns to RunL() and starts next

   142         * phase of listing operation. This makes possible the cancelling 

   143         * function to get through.

   144         * @return void

   145         */

   146         void SignalOwnStatusAndComplete();

   147         

   148         /**

   149         * Appends labels of available Tokens (wims) to an array.

   150         * @return void

   151         */

   152         void AppendTokenLabelsToArrayL();

   153         

   154         /**

   155         * Reads the count of the WIM.

   156         * @return void

   157         */  

   158         void ReadWimCount();

   159         

   160         /**

   161         * Five different phases, which are used to initialize

   162         * WIM and list security modules.

   163         */

   164         enum TPhase

   165             {

   166             EConnectClientSession,

   167             ECreateNewSession,

   168             EInitializeWim,

   169             EGetWimRefs

   170             };

   171     private: //From CActive

   172 

   173         /**

   174         * Different phases are handled here.

   175         * @return void

   176         */

   177         void RunL();

   178         

   179         /**

   180         * Cancellation function

   181         * Deallocates member variables and completes client status with

   182         * KErrCancel error code.

   183         * @return void

   184         */

   185         void DoCancel();

   186 

   187         /**

   188         * The active scheduler calls this function if this active 

   189         * object's RunL() function leaves. 

   190         * Handles neccessary cleanup and completes request with

   191         * received error code.

   192         * @param aError -Error code which caused this event

   193         * @return TInt  -Error code to active scheduler, is always KErrNone.

   194         */ 

   195         TInt RunError( TInt aError );

   196 

   197     private: 

   198 

   199         /**

   200         * Allocate pointer to WIM and create CWimSecModules

   201         * @return TInt -Error code

   202         */

   203         TInt WIMModulesL();

   204 

   205 

   206     private:

   207 

   208         //Used to handle initialization of WIM and listing tokentypes

   209         TPhase                          iPhase;

   210                 

   211         //Client status is stored here while WIM is started and

   212         //listing operation is made. After that User::RequestComplete()

   213         //is signalled with iClientStatus.

   214         TRequestStatus*                 iClientStatus;

   215         

   216         //Array containing WIM labels. Not owned, caller is 

   217         //responsible to destroy received array.

   218         RCPointerArray<HBufC>*          iTokenLabels;

   219         

   220         //Flag to indicate errors during WIM initialization.

   221         TInt                            iWimStartErr;

   222         

   223         // Array of pointers to WIM Security Modules. Owned. 

   224         // Valid as long as CWimSecModuleMgr is valid.

   225         CArrayPtrFlat<CWimSecModule>*   iWims; 

   226         

   227         // Pointer to Client Session. Owned. 

   228         // Valid as long as CWimSecModuleMgr is valid.

   229         RWimMgmt*                       iClientSession;

   230         

   231         // WIM reference list. Owned. Valid as long as iClientSession

   232         // is valid.

   233         TWimAddressList                 iWimAddrLst;

   234         

   235         // WIM count, defines the amount of WIM cards.

   236         TUint                           iWimCount;

   237         

   238         TPhase                          iCurrentPhase;

   239 

   240     };

   241 

   242 #endif      // WIMSECMODULEMGR_H   

   243             

   244 // End of File