1 /*

     2 * Copyright (c) 2009 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 file contains the header file of the 

    15 * RTestEngineServer, RTestEngine and RTestCase.

    16 *

    17 */

    18 

    19 #ifndef TEST_ENGINE_CLIENT_H

    20 #define TEST_ENGINE_CLIENT_H

    21 

    22 //  INCLUDES

    23 #include <e32std.h>

    24 #include <e32base.h>

    25 #include <hal.h>

    26 #include <stiftestinterface.h>

    27 #include <StifTestEventInterface.h>

    28 #include <StifLogger.h>

    29 

    30 #include <stiftfwifprot.h>

    31 #include <e32hashtab.h> 

    32 

    33 // CONSTANTS

    34 // None

    35 

    36 // Start and end tags for STIF setting denitions

    37 _LIT( KStifSettingsStartTag, "[StifSettings]" );

    38 _LIT( KStifSettingsEndTag, "[EndStifSettings]" );

    39 // Tag for cabs modifier name

    40 _LIT( KCapsModifier, "CapsModifier=" );

    41 // Test module thread heap and stack names

    42 _LIT( KUserDefStackSize, "TestThreadStackSize=" );

    43 _LIT( KUserDefMinHeap, "TestThreadMinHeap=" );

    44 _LIT( KUserDefMaxHeap, "TestThreadMaxHeap=" );

    45 

    46 // MACROS

    47 // None

    48 

    49 // DATA TYPES

    50 

    51 // Package for test case count, used in EnumerateTestCases method

    52 typedef TPckgBuf<TInt> TCaseCount;

    53 

    54 // A set of test engine settings which can be set/read by SettingServer

    55 struct TEngineSettings

    56     {

    57     TInt iEngineSessionId;

    58     TBool iUITestingSupport;

    59     TBool iSeparateProcesses;

    60     };

    61 

    62 // FUNCTION PROTOTYPES

    63 // None

    64 

    65 // FORWARD DECLARATIONS

    66 // Template class delivering test cases from Test Module

    67 template <class T> class CFixedFlatArray;

    68 

    69 // CLASS DECLARATION

    70 

    71 // DESCRIPTION

    72 // RTestEngineServer is a client class of Test Engine Server

    73 // The connect function starts the server, if is not already running.

    74 // An RSessionBase sends messages to the server with

    75 // the function RSessionBase::SendReceive();

    76 // specifying an opcode (TTestEngineReq) and array of argument pointers.

    77 

    78 class RTestEngine

    79         : public RSessionBase 

    80     {

    81     public:     // Enumerations

    82         enum TTestEngineAsyncRequest { EErrorNotification, EEvent };

    83     private:    // Enumerations

    84 

    85     public:     // Constructors and destructor

    86 

    87     public:     // New functions

    88 

    89         /**

    90         * Connect method creates new RTestEngineServer session that is used

    91         * to manage the test case execution.

    92         */

    93         IMPORT_C TInt Connect();

    94 

    95         /**

    96         * Version returns client side version number from the 

    97         * RTestEngineServer.

    98         */

    99         IMPORT_C TVersion Version() const;

   100 

   101         /**

   102         * Open creates a subsession to Test Engine and opens new handle to

   103         * RTestEngine. The RTestEngineServer subsession shall be created by

   104         * calling RTestEngineServer::Connect before calling Open to create new

   105         * RTestEngine subsession.

   106         */

   107         IMPORT_C TInt LoadConfiguration( const TFileName& aIniFile );

   108 

   109         /**

   110         * Closes the RTestEngine subsession.

   111         */

   112         IMPORT_C void Close();

   113 

   114     public:     // New functions

   115 

   116         /**

   117         * Sets attributes to Test Framework

   118         */

   119         IMPORT_C TInt SetAttribute( TAttribute aAttribute,

   120                                     const TDesC& aValue );

   121 

   122         /**

   123         * AddTestModule is used to add dynamically a new Test Module to the

   124         * Test Framework. Test cases can then be run from the new Test Module

   125         * without restarting the Test Framework.

   126         * If the Test Module specified by aTestModule doesn't exists this

   127         * method returns KErrNotFound. If the Test Module has been already

   128         * loaded this method returns KErrAlreadyExists.

   129         */

   130         IMPORT_C TInt AddTestModule( const TName& aTestModule,

   131                                      const TFileName& aIniFile );

   132 

   133         /**

   134         * RemoveTestModule is used to remove the existing Test Module from Test

   135         * Framework. If there are not test cases executing in the Test Module

   136         * it will be shut down.

   137         * If there is test case running from the Test Module this method

   138         * returns KErrInUse.

   139         * If the Test Module specified by aTestModule is not loaded this method

   140         * returns KErrNotFound.

   141         */

   142         IMPORT_C TInt RemoveTestModule( const TName& aTestModule );

   143 

   144         /**

   145         * AddConfigFile is used to add dynamically a new config file to the

   146         * Test Module specified by aTestModule. New test cases are then 

   147         * executed by calling first GetTestCases and then RunTestCase. Thus

   148         * new test cases can be run from the Test Module without restarting

   149         * the Test Framework.

   150         */

   151         IMPORT_C TInt AddConfigFile( const TName& aTestModule,

   152                                      const TFileName& aConfigFile );

   153 

   154         /**

   155         * RemoveConfigFile is used to remove a config file from the

   156         * Test Module specified by aTestModule. 

   157         */

   158         IMPORT_C TInt RemoveConfigFile( const TName& aTestModule,

   159                                         const TFileName& aConfigFile );

   160 

   161         /**

   162         * Test cases are inquired by two-phased operation calling first the

   163         * EnumerateTestCases method and then the GetTestCases. Test cases are

   164         * inquired from Test Engine that will inquire them from Test Modules.

   165         * EnumerateTestCases requests the needed array size for test cases that

   166         * will be inquired by GetTestCases method. When the EnumerateTestCases

   167         * is completed succesfully the GetTestCases method is called to

   168         * retrieve test cases to CArrayFixFlat <TTestInfo> list object.

   169         *

   170         * TTestInfo defines individual test case and, if needed, a test set

   171         * (TName iParent) where the test case belongs to. TTestInfo is used to

   172         * create test case by calling RTestCase::Open that constructs the

   173         * actual test case. Test case is then executed calling

   174         * RTestCase::RunTestCase.

   175         */

   176         IMPORT_C void EnumerateTestCases( TCaseCount& aCount,

   177                                           TRequestStatus& aStatus );

   178 

   179         /**

   180         * GetTestCases retrieves test cases from Test Modules to 

   181         * aTestCaseBuffer that is a list consisting of several TTestInfo 

   182         * objects. If this method is called without previously succesfully

   183         * called EnumerateTestCases method, this function returns the

   184         * KErrNotReady.

   185         */

   186         IMPORT_C TInt GetTestCases(

   187                             CFixedFlatArray<TTestInfo>& aTestCaseBuffer );

   188 

   189         /**

   190         * Asynchronous request can be canceled with CancelAsyncRequest method.

   191         * The aReqToCancel parameter defines the request that will be canceled.

   192         */

   193         IMPORT_C TInt CancelAsyncRequest( TTestEngineAsyncRequest aReqToCancel );

   194         

   195         /**

   196         * Event is used to get and set events in STIF Test Framework.

   197         * TEventIf defines the event request information.

   198         */

   199         IMPORT_C void Event( TEventIfPckg& aEvent,

   200                              TRequestStatus& aStatus );

   201 

   202         /**

   203         * Used to get Logger's overwrite parameters.

   204         */

   205         IMPORT_C TInt OpenLoggerSession( TLoggerSettings& aLoggerSettings );

   206 

   207         /**

   208         * ErrorNotification obtains error notifications from test engine.

   209         */

   210         IMPORT_C void ErrorNotification( TErrorNotificationPckg& aError,

   211                                          TRequestStatus& aStatus );

   212 

   213         /**

   214         * Add info about test case to test report.

   215         */

   216         IMPORT_C TInt AddTestCaseResultToTestReport(const TTestInfo& aTestInfo,

   217                                                     const TFullTestResult& aTestResult,

   218                                                     const TInt aError);

   219         /**

   220         * Update Log Configuration.

   221         */

   222         IMPORT_C TInt UpdateLogConfiguration(TDesC& aLogConfigList);

   223        /**

   224         * Update Engine Configuration.

   225         */

   226         IMPORT_C TInt UpdateEngineConfiguration(TDesC& aEngineConfigList);

   227                                          

   228     public:     // Functions from base classes

   229         

   230     protected:  // New functions

   231 

   232     protected:  // Functions from base classes

   233 

   234     private:    // New functions

   235 

   236     public:     // Data

   237 

   238     protected:  // Data

   239 

   240     private:    // Data

   241 

   242     public:     // Friend classes

   243 

   244     protected:  // Friend classes

   245 

   246     private:    // Friend classes

   247 

   248     };

   249     

   250 // DESCRIPTION

   251 

   252 // RTestCase class represents a subsession with the RTestEngineServer.

   253 // Each RTestCase corresponds to a specific CTestExecution (a CObject

   254 // derived class) in the server. Messages are passed via the RTestEngineServer.

   255 // A RTestCase stores a handle from it's server side CTestExecution,

   256 // and uses this to identify the CTestExecution during communication.

   257 

   258 class RTestCase

   259         : public RSubSessionBase 

   260     {

   261 

   262     public:     // Structured classes

   263 

   264     public:     // Enumerations

   265         enum TTestCaseAsyncRequest { ERunTestCase, ENotifyProgress, ENotifyRemoteType, };

   266         

   267     private:    // Enumerations

   268 

   269     public:     // Constructors and destructor

   270 

   271         /**

   272         * Open creates a subsession for new test case. Test case is initialized

   273         * using aTestCaseInfo parameter. The aTestCaseInfo is TTestInfoPckg 

   274         * that is a packaged TTestInfo. TTestInfo is got from the Test Engine

   275         * by calling RTestEngine::GetTestCases method.

   276         * If there was previously called RemoveTestModule for the Test Module

   277         * that is defined in aTestCaseInfo this method returns KErrLocked.

   278         * This means that new test cases cannot be run from this Test Module

   279         * and the user should inquire test cases available calling 

   280         * RTestEngine::GetTestCases.

   281         */

   282         IMPORT_C TInt Open( RTestEngine& aServer,

   283                                 const TTestInfoPckg& aTestCaseInfo );

   284 

   285         /**

   286         * Closes the RTestCase subsession. Test case is normally closed

   287         * immediately after the test case was completed.

   288         */

   289         IMPORT_C void Close();

   290 

   291     public:     // New functions

   292 

   293         /**

   294         * RunTestCase is asynchronous method and it is completed when the test

   295         * case is completed. Result of the test case is returned to 

   296         * aTestResult. The aTestResult is TFullTestResultPckg that is a

   297         * packaged TFullTestResult.

   298         * The aStatus will have the completion result of this function. If the

   299         * test case could be run (despite of succesfully or not) the KErrNone 

   300         * is returned to aStatus.

   301         */

   302         IMPORT_C void RunTestCase( TFullTestResultPckg& aTestResult,

   303                                     TRequestStatus& aStatus );

   304 

   305         /**

   306         * Pause suspends the execution of the test case. The subsession where

   307         * the test case is run is suspended and thus the test case execution is

   308         * suspended. Test case execution can be later resumed by calling 

   309         * Resume.

   310         */

   311         IMPORT_C TInt Pause();

   312 

   313         /**

   314         * Resume is used to resume the test case suspended by previously called

   315         * Pause method. The test case execution should be continued immediately

   316         * when the Resume is called.

   317         */

   318         IMPORT_C TInt Resume();

   319 

   320         /**

   321         * NotifyProgress requests different progress information from the test

   322         * case execution. This information can be printed to UI. The progress

   323         * information is returned to aProgress. The aProgress is

   324         * TTestProgressPckg that is a packaged TTestProgress 

   325         */

   326         IMPORT_C void NotifyProgress( TTestProgressPckg& aProgress,

   327                                         TRequestStatus& aStatus );

   328                                         

   329         /**

   330         * NotifyRemoteType requests enable message waiting.

   331         */

   332         IMPORT_C void NotifyRemoteType( TStifCommandPckg& aType,

   333                                         TPckg<TInt>& aMsgSize,

   334                                         TRequestStatus& aStatus );

   335         /**

   336         * NotifyRemoteMsg gets messages.

   337         */

   338         IMPORT_C TInt NotifyRemoteMsg( TDes8& aMessage,

   339                                        TStifCommand aType );

   340 

   341         /**

   342         * Asynchronous request can be canceled with CancelAsyncRequest method.

   343         * The aReqToCancel parameter defines the request that will be canceled.

   344         */

   345         IMPORT_C TInt CancelAsyncRequest( TTestCaseAsyncRequest aReqToCancel );

   346 

   347     public:     // Functions from base classes

   348         

   349     protected:  // New functions

   350 

   351     protected:  // Functions from base classes

   352 

   353     private:    // New functions

   354 

   355     public:     // Data

   356     

   357     protected:  // Data

   358 

   359     private:    // Data

   360 

   361     public:     // Friend classes

   362 

   363     protected:  // Friend classes

   364 

   365     private:    // Friend classes

   366 

   367     };

   368 

   369 /*

   370 -------------------------------------------------------------------------------

   371 

   372     DESCRIPTION

   373 

   374     This contains the CFixedFlatArray class definitions.

   375 

   376 -------------------------------------------------------------------------------

   377 */

   378 template <class T>

   379 class CFixedFlatArray 

   380         :public CBase

   381     {

   382     public:     // Enumerations

   383 

   384     private:    // Enumerations

   385 

   386     public:     // Constructors and destructor

   387         

   388         /**

   389         * Two-phased constructor.

   390         */

   391         inline static CFixedFlatArray<T>* NewL(const TInt aSize);

   392 

   393         /**

   394         * Destructor.

   395         */

   396         inline ~CFixedFlatArray();

   397 

   398     public:     // New functions

   399 

   400         /**

   401         * Return descriptor containing array. Used in server calls

   402         */

   403         inline TPtr8& Des();

   404 

   405         /**

   406         * Returns CFixedFlatArray internal array. Used in server calls

   407         */

   408         inline T& operator[] (TInt aIndex) const;

   409 

   410         /**

   411         * Returns count

   412         */

   413         inline TInt Count() const;

   414 

   415         /**

   416         * Sets aBuf to array slot specified by aIndex

   417         */

   418         inline void Set( TInt aIndex, T& aBuf );

   419 

   420     public:     // Functions from base classes

   421 

   422     protected:  // New functions

   423 

   424     protected:  // Functions from base classes

   425 

   426     private:

   427 

   428         /**

   429         * By default Symbian OS constructor is private.

   430         */

   431         inline void ConstructL(const TInt aSize);

   432 

   433         /**

   434         * C++ default constructor.

   435         */

   436         inline CFixedFlatArray();

   437 

   438         /**

   439         * Check that given index is correct.

   440         */

   441         inline void CheckIndex( TInt aIndex ) const;

   442 

   443     protected:  // Data

   444 

   445     private:    // Data

   446         // Array

   447         T*      iArray;

   448 

   449         // Count

   450         TInt    iCount;

   451 

   452         // Buffer

   453         HBufC8* iBuffer;

   454         TPtr8   iBufferPtr;

   455 

   456     public:     // Friend classes

   457 

   458     protected:  // Friend classes

   459 

   460     private:    // Friend classes

   461 

   462     };

   463 

   464 #include <TestEngineClient.inl>

   465 

   466 

   467 #endif // TEST_ENGINE_CLIENT_H

   468 

   469 // End of File