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         * Pause suspends the execution of the test case. The subsession where

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

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

   382         * Resume.

   383         */

   384         IMPORT_C TInt Pause();

   385 

   386         /**

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

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

   389         * when the Resume is called.

   390         */

   391         IMPORT_C TInt Resume();

   392 

   393         /**

   394         * NotifyProgress requests different progress information from the test

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

   396         * information is returned to aProgress. The aProgress is

   397         * TTestProgressPckg that is a packaged TTestProgress 

   398         */

   399         IMPORT_C void NotifyProgress( TTestProgressPckg& aProgress,

   400                                         TRequestStatus& aStatus );

   401                                         

   402         /**

   403         * NotifyRemoteType requests enable message waiting.

   404         */

   405         IMPORT_C void NotifyRemoteType( TStifCommandPckg& aType,

   406                                         TPckg<TInt>& aMsgSize,

   407                                         TRequestStatus& aStatus );

   408         /**

   409         * NotifyRemoteMsg gets messages.

   410         */

   411         IMPORT_C TInt NotifyRemoteMsg( TDes8& aMessage,

   412                                        TStifCommand aType );

   413 

   414         /**

   415         * Asynchronous request can be canceled with CancelAsyncRequest method.

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

   417         */

   418         IMPORT_C TInt CancelAsyncRequest( TInt aReqToCancel );

   419 

   420     public:     // Functions from base classes

   421         

   422     protected:  // New functions

   423 

   424     protected:  // Functions from base classes

   425 

   426     private:    // New functions

   427 

   428     public:     // Data

   429     

   430     protected:  // Data

   431 

   432     private:    // Data

   433 

   434     public:     // Friend classes

   435 

   436     protected:  // Friend classes

   437 

   438     private:    // Friend classes

   439 

   440     };

   441 

   442 /*

   443 -------------------------------------------------------------------------------

   444 

   445     DESCRIPTION

   446 

   447     This contains the CFixedFlatArray class definitions.

   448 

   449 -------------------------------------------------------------------------------

   450 */

   451 template <class T>

   452 class CFixedFlatArray 

   453         :public CBase

   454     {

   455     public:     // Enumerations

   456 

   457     private:    // Enumerations

   458 

   459     public:     // Constructors and destructor

   460         

   461         /**

   462         * Two-phased constructor.

   463         */

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

   465 

   466         /**

   467         * Destructor.

   468         */

   469         inline ~CFixedFlatArray();

   470 

   471     public:     // New functions

   472 

   473         /**

   474         * Return descriptor containing array. Used in server calls

   475         */

   476         inline TPtr8& Des();

   477 

   478         /**

   479         * Returns CFixedFlatArray internal array. Used in server calls

   480         */

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

   482 

   483         /**

   484         * Returns count

   485         */

   486         inline TInt Count() const;

   487 

   488         /**

   489         * Sets aBuf to array slot specified by aIndex

   490         */

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

   492 

   493     public:     // Functions from base classes

   494 

   495     protected:  // New functions

   496 

   497     protected:  // Functions from base classes

   498 

   499     private:

   500 

   501         /**

   502         * By default Symbian OS constructor is private.

   503         */

   504         inline void ConstructL(const TInt aSize);

   505 

   506         /**

   507         * C++ default constructor.

   508         */

   509         inline CFixedFlatArray();

   510 

   511         /**

   512         * Check that given index is correct.

   513         */

   514         inline void CheckIndex( TInt aIndex ) const;

   515 

   516     protected:  // Data

   517 

   518     private:    // Data

   519         // Array

   520         T*      iArray;

   521 

   522         // Count

   523         TInt    iCount;

   524 

   525         // Buffer

   526         HBufC8* iBuffer;

   527         TPtr8   iBufferPtr;

   528 

   529     public:     // Friend classes

   530 

   531     protected:  // Friend classes

   532 

   533     private:    // Friend classes

   534 

   535     };

   536 

   537 #include <TestEngineClient.inl>

   538 

   539 

   540 #endif // TEST_ENGINE_CLIENT_H

   541 

   542 // End of File