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 

    32 // CONSTANTS

    33 // None

    34 

    35 // Start and end tags for STIF setting denitions

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

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

    38 // Tag for cabs modifier name

    39 _LIT( KCapsModifier, "CapsModifier=" );

    40 // Test module thread heap and stack names

    41 _LIT( KUserDefStackSize, "TestThreadStackSize=" );

    42 _LIT( KUserDefMinHeap, "TestThreadMinHeap=" );

    43 _LIT( KUserDefMaxHeap, "TestThreadMaxHeap=" );

    44 

    45 // Global mutex name

    46 _LIT( KStifTestServerStartupMutex, "KStifTestServerStartupMutex" );

    47 

    48 // MACROS

    49 // None

    50 

    51 // DATA TYPES

    52 

    53 // Opcodes used in message passing between client and server

    54 enum TTestEngineRequests

    55     {

    56     // RTestEngineServer requests

    57     ETestEngineServerCloseSession,

    58     // RTestEngine requests

    59     ETestEngineCreateSubSession,

    60     ETestEngineCloseSubSession,

    61     ETestEngineSetAttribute,

    62     ETestEngineAddTestModule,

    63     ETestEngineRemoveTestModule,

    64     ETestEngineAddConfigFile,

    65     ETestEngineRemoveConfigFile,

    66     ETestEngineEnumerateTestCases,

    67     ETestEngineGetTestCases,    

    68     ETestEngineCancelAsyncRequest,

    69     ETestEngineEvent,

    70     ETestEngineErrorNotification,

    71     ETestEngineLoggerSettings,

    72     ETestEngineCloseLoggerSettings,

    73     ETestEngineReportTestCase, //Add info about executed test case to test report. Used by reboot mechanism

    74     // RTestCase requests

    75     ETestCaseCreateSubSession,

    76     ETestCaseCloseSubSession,

    77     ETestCaseRunTestCase,

    78     ETestCasePause,

    79     ETestCaseResume,

    80     ETestCaseNotifyProgress,

    81     ETestCaseNotifyRemoteType,

    82     ETestCaseNotifyRemoteMsg,

    83     ETestCaseCancelAsyncRequest,

    84     ETestCaseNotifyCommand,

    85     };

    86 

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

    88 typedef TPckgBuf<TInt> TCaseCount;

    89 

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

    91 struct TEngineSettings

    92     {

    93     TBool iUITestingSupport;

    94     TBool iSeparateProcesses;

    95     };

    96 

    97 // FUNCTION PROTOTYPES

    98 // None

    99 

   100 // FORWARD DECLARATIONS

   101 // Template class delivering test cases from Test Module

   102 template <class T> class CFixedFlatArray;

   103 

   104 // CLASS DECLARATION

   105 

   106 // DESCRIPTION

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

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

   109 // An RSessionBase sends messages to the server with

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

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

   112 

   113 class RTestEngineServer

   114         : public RSessionBase 

   115     {

   116     public:     // Enumerations

   117 

   118     private:    // Enumerations

   119 

   120     public:     // Constructors and destructor

   121 

   122         /**

   123         * Closes the RTestEngineServer session.

   124         */

   125         IMPORT_C void Close();

   126 

   127     public:     // New functions

   128 

   129         /**

   130         * Connect method creates new RTestEngineServer session that is used

   131         * to manage the test case execution.

   132         */

   133         IMPORT_C TInt Connect();

   134 

   135         /**

   136         * Version returns client side version number from the 

   137         * RTestEngineServer.

   138         */

   139         IMPORT_C TVersion Version() const;

   140 

   141     public:     // Functions from base classes

   142 

   143     protected:  // New functions

   144 

   145     protected:  // Functions from base classes

   146 

   147     private:    // New functions

   148 

   149     public:     // Data

   150 

   151     protected:  // Data

   152 

   153     private:    // Data

   154 

   155     public:     // Friend classes

   156 

   157     protected:  // Friend classes

   158 

   159     private:    // Friend classes

   160 

   161     };

   162 

   163 // DESCRIPTION

   164 

   165 // RTestEngine class represents a subsession with the RTestEngineServer.

   166 // Each RTestEngine corresponds to a specific CTestEngine (a CObject derived

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

   168 // A RTestEngine stores a handle from it's server side CTestEngine, and uses

   169 // this to identify the CTestEngine during communication.

   170 

   171 class RTestEngine

   172         : public RSubSessionBase 

   173     {

   174 

   175     public:     // Enumerations

   176 

   177     private:    // Enumerations

   178 

   179     public:     // Constructors and destructor

   180 

   181         /**

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

   183         * RTestEngine. The RTestEngineServer subsession shall be created by

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

   185         * RTestEngine subsession.

   186         */

   187         IMPORT_C TInt Open( RTestEngineServer& aServer,

   188                             const TFileName& aIniFile );

   189 

   190         /**

   191         * Closes the RTestEngine subsession.

   192         */

   193         IMPORT_C void Close();

   194 

   195     public:     // New functions

   196 

   197         /**

   198         * Sets attributes to Test Framework

   199         */

   200         IMPORT_C TInt SetAttribute( TAttribute aAttribute,

   201                                     const TDesC& aValue );

   202 

   203         /**

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

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

   206         * without restarting the Test Framework.

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

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

   209         * loaded this method returns KErrAlreadyExists.

   210         */

   211         IMPORT_C TInt AddTestModule( const TName& aTestModule,

   212                                      const TFileName& aIniFile );

   213 

   214         /**

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

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

   217         * it will be shut down.

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

   219         * returns KErrInUse.

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

   221         * returns KErrNotFound.

   222         */

   223         IMPORT_C TInt RemoveTestModule( const TName& aTestModule );

   224 

   225         /**

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

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

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

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

   230         * the Test Framework.

   231         */

   232         IMPORT_C TInt AddConfigFile( const TName& aTestModule,

   233                                      const TFileName& aConfigFile );

   234 

   235         /**

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

   237         * Test Module specified by aTestModule. 

   238         */

   239         IMPORT_C TInt RemoveConfigFile( const TName& aTestModule,

   240                                         const TFileName& aConfigFile );

   241 

   242         /**

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

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

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

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

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

   248         * is completed succesfully the GetTestCases method is called to

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

   250         *

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

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

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

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

   255         * RTestCase::RunTestCase.

   256         */

   257         IMPORT_C void EnumerateTestCases( TCaseCount& aCount,

   258                                           TRequestStatus& aStatus );

   259 

   260         /**

   261         * GetTestCases retrieves test cases from Test Modules to 

   262         * aTestCaseBuffer that is a list consisting of several TTestInfo 

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

   264         * called EnumerateTestCases method, this function returns the

   265         * KErrNotReady.

   266         */

   267         IMPORT_C TInt GetTestCases(

   268                             CFixedFlatArray<TTestInfo>& aTestCaseBuffer );

   269 

   270         /**

   271         * Asynchronous request can be canceled with CancelAsyncRequest method.

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

   273         */

   274         IMPORT_C TInt CancelAsyncRequest( TInt aReqToCancel );

   275         

   276         /**

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

   278         * TEventIf defines the event request information.

   279         */

   280         IMPORT_C void Event( TEventIfPckg& aEvent,

   281                              TRequestStatus& aStatus );

   282 

   283         /**

   284         * Used to get Logger's overwrite parameters.

   285         */

   286         IMPORT_C TInt OpenLoggerSession( RTestEngineServer& aServer,

   287                                             TLoggerSettings& aLoggerSettings );

   288 

   289         /**

   290         * ErrorNotification obtains error notifications from test engine.

   291         */

   292         IMPORT_C void ErrorNotification( TErrorNotificationPckg& aError,

   293                                          TRequestStatus& aStatus );

   294 

   295         /**

   296         * Add info about test case to test report.

   297         */

   298         IMPORT_C TInt AddTestCaseResultToTestReport(const TTestInfo& aTestInfo,

   299                                                     const TFullTestResult& aTestResult,

   300                                                     const TInt aError);

   301                                          

   302     public:     // Functions from base classes

   303         

   304     protected:  // New functions

   305 

   306     protected:  // Functions from base classes

   307 

   308     private:    // New functions

   309 

   310     public:     // Data

   311 

   312     protected:  // Data

   313 

   314     private:    // Data

   315 

   316     public:     // Friend classes

   317 

   318     protected:  // Friend classes

   319 

   320     private:    // Friend classes

   321 

   322     };

   323     

   324 // DESCRIPTION

   325 

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

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

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

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

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

   331 

   332 class RTestCase

   333         : public RSubSessionBase 

   334     {

   335 

   336     public:     // Structured classes

   337 

   338     public:     // Enumerations

   339 

   340     private:    // Enumerations

   341 

   342     public:     // Constructors and destructor

   343 

   344         /**

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

   346         * using aTestCaseInfo parameter. The aTestCaseInfo is TTestInfoPckg 

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

   348         * by calling RTestEngine::GetTestCases method.

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

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

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

   352         * and the user should inquire test cases available calling 

   353         * RTestEngine::GetTestCases.

   354         */

   355         IMPORT_C TInt Open( RTestEngineServer& aServer,

   356                                 const TTestInfoPckg& aTestCaseInfo );

   357 

   358         /**

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

   360         * immediately after the test case was completed.

   361         */

   362         IMPORT_C void Close();

   363 

   364     public:     // New functions

   365 

   366         /**

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

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

   369         * aTestResult. The aTestResult is TFullTestResultPckg that is a

   370         * packaged TFullTestResult.

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

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

   373         * is returned to aStatus.

   374         */

   375         IMPORT_C void RunTestCase( TFullTestResultPckg& aTestResult,

   376                                     TRequestStatus& aStatus );

   377 

   378         /**

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

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

   381         * aTestResult. The aTestResult is TFullTestResultPckg that is a

   382         * packaged TFullTestResult.

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

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

   385         * is returned to aStatus.

   386         */

   387         IMPORT_C void RunTestCase( TFullTestResultPckg& aTestResult,

   388                                    const TDesC& aTestCaseArgs,

   389                                    TRequestStatus& aStatus );        

   390 

   391         /**

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

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

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

   395         * Resume.

   396         */

   397         IMPORT_C TInt Pause();

   398 

   399         /**

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

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

   402         * when the Resume is called.

   403         */

   404         IMPORT_C TInt Resume();

   405 

   406         /**

   407         * NotifyProgress requests different progress information from the test

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

   409         * information is returned to aProgress. The aProgress is

   410         * TTestProgressPckg that is a packaged TTestProgress 

   411         */

   412         IMPORT_C void NotifyProgress( TTestProgressPckg& aProgress,

   413                                         TRequestStatus& aStatus );

   414                                         

   415         /**

   416         * NotifyRemoteType requests enable message waiting.

   417         */

   418         IMPORT_C void NotifyRemoteType( TStifCommandPckg& aType,

   419                                         TPckg<TInt>& aMsgSize,

   420                                         TRequestStatus& aStatus );

   421         /**

   422         * NotifyRemoteMsg gets messages.

   423         */

   424         IMPORT_C TInt NotifyRemoteMsg( TDes8& aMessage,

   425                                        TStifCommand aType );

   426 

   427         /**

   428         * Asynchronous request can be canceled with CancelAsyncRequest method.

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

   430         */

   431         IMPORT_C TInt CancelAsyncRequest( TInt aReqToCancel );

   432 

   433     public:     // Functions from base classes

   434         

   435     protected:  // New functions

   436 

   437     protected:  // Functions from base classes

   438 

   439     private:    // New functions

   440 

   441     public:     // Data

   442     

   443     protected:  // Data

   444 

   445     private:    // Data

   446 

   447     public:     // Friend classes

   448 

   449     protected:  // Friend classes

   450 

   451     private:    // Friend classes

   452 

   453     };

   454 

   455 /*

   456 -------------------------------------------------------------------------------

   457 

   458     DESCRIPTION

   459 

   460     This contains the CFixedFlatArray class definitions.

   461 

   462 -------------------------------------------------------------------------------

   463 */

   464 template <class T>

   465 class CFixedFlatArray 

   466         :public CBase

   467     {

   468     public:     // Enumerations

   469 

   470     private:    // Enumerations

   471 

   472     public:     // Constructors and destructor

   473         

   474         /**

   475         * Two-phased constructor.

   476         */

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

   478 

   479         /**

   480         * Destructor.

   481         */

   482         inline ~CFixedFlatArray();

   483 

   484     public:     // New functions

   485 

   486         /**

   487         * Return descriptor containing array. Used in server calls

   488         */

   489         inline TPtr8& Des();

   490 

   491         /**

   492         * Returns CFixedFlatArray internal array. Used in server calls

   493         */

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

   495 

   496         /**

   497         * Returns count

   498         */

   499         inline TInt Count() const;

   500 

   501         /**

   502         * Sets aBuf to array slot specified by aIndex

   503         */

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

   505 

   506     public:     // Functions from base classes

   507 

   508     protected:  // New functions

   509 

   510     protected:  // Functions from base classes

   511 

   512     private:

   513 

   514         /**

   515         * By default Symbian OS constructor is private.

   516         */

   517         inline void ConstructL(const TInt aSize);

   518 

   519         /**

   520         * C++ default constructor.

   521         */

   522         inline CFixedFlatArray();

   523 

   524         /**

   525         * Check that given index is correct.

   526         */

   527         inline void CheckIndex( TInt aIndex ) const;

   528 

   529     protected:  // Data

   530 

   531     private:    // Data

   532         // Array

   533         T*      iArray;

   534 

   535         // Count

   536         TInt    iCount;

   537 

   538         // Buffer

   539         HBufC8* iBuffer;

   540         TPtr8   iBufferPtr;

   541 

   542     public:     // Friend classes

   543 

   544     protected:  // Friend classes

   545 

   546     private:    // Friend classes

   547 

   548     };

   549 

   550 #include <TestEngineClient.inl>

   551 

   552 

   553 #endif // TEST_ENGINE_CLIENT_H

   554 

   555 // End of File