/*
* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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:   Abstract base class for all SIM ATK TSY tests classes.
*
*/



#ifndef SATBASE_H
#define SATBASE_H

// INCLUDES
#include <e32base.h>
#include <testscripterinternal.h>
#include <etelsat.h>

// FORWARDS
class CStifItemParser;
class CStifLogger;

// DATA TYPES
typedef TInt        TSatIpc;

// CLASS DECLARATION

/**
*  Abstract base class for all SIM ATK TSY tests classes. Provides
*  functionality to verify the received data against scripted values
*  by providing general helper methods for all subclasses.
*  @lib SimAtk.dll
*/
NONSHARABLE_CLASS( CSatBase ) : public CBase
    {
    public:  // Constructors and destructor
    
        /**
        * Constructor.
        */     
        CSatBase( const TSatIpc aIpc, const RSat& aSat, 
            CStifItemParser& aParser, CStifLogger& aLog );

        /**
        * Destructor.
        */     
        virtual ~CSatBase();
        
        
    public:  // Pure virtuals

        /**
        * Pure virtual method. Must be overridden by subclasses.
        * Method verifies the validity of received data by compaing
        * them against scripted parameters. 
        * @return KErrNone if date was valid or KErrCorrupt if received data
        *   and script did not match.
        */
        virtual TInt CheckData() = 0;

        /**
        * Pure virtual method. Must be overridden by subclasses.
        * Method requests notifications from Etel for specific SAT feature
        * and resets the internal data structure.
        * @param aSimAtkStatus Reference to active object's request status
        * @return KErrNone
        */
        virtual TInt NotifySat( TRequestStatus& aSimAtkStatus ) = 0;


    public:  // New Methods
        
        /**
        * Cancels pending Etel request for current command.
        * @return None
        */
        void CancelRequest();
                
        /**
        * Used to identify the Sat feature by IPC. Return appropriate 
        * boolean value.
        * @return ETrue if provide IPC matches with the IPC of the feature.
        *   Otherwise EFalse is returned
        */
        TBool MatchIpc( TSatIpc aRequestedIpc );

    
    protected:  // New Methods

        /**
        * Helper method that verifies the validity of Address
        * structure against scripted parameters.
        * @param aAddress reference to Address structure which shall be verified
        * @return KErrNone if data was valid, KErrCorrupt if received data
        *   and script did not match or KErrNotFound if script did not
        *   provide valid parameters.
        */
        TInt CheckAddress( const RSat::TAddress& aAddress );

        /**
        * Helper method that verifies the validity of AlphaId
        * against scripted parameters.
        * @param aAlphaId reference to AlphaId which shall be verified
        * @param aAlphaIdTag Script tag which shall be used when parsing
        *   alphaId structure from the script. Default value is "AlphaId".
        * @return KErrNone if data was valid, KErrCorrupt if received data
        *   and script did not match or KErrNotFound if script did not
        *   provide valid parameters.
        */
        TInt CheckAlphaId( const RSat::TAlphaId& aAlphaId,
            const TDesC& aAlphaIdTag = KNullDesC );
            
        /**
        * Helper method that verifies the validity of binary
        * data buffer against scripted parameters.
        * @param aTag Tag used to find reference binary data from script
        * @param aData Contains data to be verified  
        * @return KErrNone if data was valid or KErrCorrupt if received data
        * and script did not match. KErrNotFound if reference data was not
        * found from the script.
        */
        TInt CheckBuffer( const TDesC& aTag, const TDesC& aData );

        /**
        * Helper method that verifies the validity of 8-bit binary
        * data buffer against scripted parameters.
        * @param aTag Tag used to find reference binary data from script
        * @param aData Contains data to be verified  
        * @return KErrNone if data was valid or KErrCorrupt if received data
        * and script did not match. KErrNotFound if reference data was not
        * found from the script.
        */
        TInt CheckBuffer( const TDesC& aTag, const TDesC8& aData );
        
        /**
        * Helper method that verifies the validity of Duration
        * against scripted parameters. If script does not provide duration
        * field, method verfifies that TimeUnit field is NoDurationAvailable
        * and NumOfUnit is 0.
        * @param aDuration reference to Duration which shall be verified
        * @return KErrNone if data was valid, KErrCorrupt if received data
        *   and script did not match or KErrNotFound if script did not
        *   provide valid parameters.
        */
        TInt CheckDuration( const RSat::TDuration& aDuration );
                        
        /**
        * Helper method that verifies the validity of Icon
        * against scripted parameters. If script does not provide icon
        * field, method verfifies that Qualifier field is NoIconId
        * and identifier is 0.
        * @param aIconId reference to Icon which shall be verified
        * @param aIconTag Script tag which shall be used when parsing icon
        *   parameters from the script. Default value is "IconId".
        * @return KErrNone if data was valid, KErrCorrupt if received data
        *   and script did not match or KErrNotFound if script did not
        *   provide valid parameters.
        */
        TInt CheckIcon( const RSat::TIconId& aIconId,
            const TDesC& aIconTag = KNullDesC );
            
#ifndef LEGACY
        /**
        * Helper method that verifies the validity of TTextAttribute
        * against scripted parameters.
        * @param aTa reference to TTextAttribute which shall be verified
        * @return KErrNone if data was valid, KErrCorrupt if received data
        *   and script did not match or KErrArgument if script did not
        *   provide valid parameters.
        */
        TInt CheckTextAttribute( const RSat::TTextAttribute& aTa );
#endif // LEGACY

        /**
        * Helper method that verifies the validity of text data against the
        * scripted parameters.
        * @param aTag Tag used to find text data from script
        * @param aData Contains the text to be verified  
        * @return KErrNone if data was valid or KErrCorrupt if received data
        * and script did not match. KErrNotFound if reference data was not
        * found from the script.
        */
        TInt CheckText( const TDesC& aTag, const TDesC& aData );

        /**
        * Helper method that verifies the validity of 8-bit text data against
        * the scripted parameters.
        * @param aTag Tag used to find text data from script
        * @param aData Contains the text to be verified  
        * @return KErrNone if data was valid or KErrCorrupt if received data
        * and script did not match. KErrNotFound if reference data was not
        * found from the script.
        */
        TInt CheckText( const TDesC& aTag, const TDesC8& aData );

        /**
        * Helper method that verifies the validity of provided value against
        * the scripted parameters.
        * @param aTag Tag used to find text data from script
        * @param aValue Contains the value to be verified  
        * @param aDefault When reference value isn't found from the script,
        * verification is made againts the default value when provided.
        * @return KErrNone if value was valid or KErrCorrupt if not.
        * KErrNotFound if reference data was not found from the script and
        * default value  was not supported.
        */
        TInt CheckValue( const TDesC& aTag, const TInt& aValue,
            const TInt aDefault = KMaxTInt );

        /**
        * Helper method that verifies the validity of provided value against
        * next value parsed from the script. Must not be used alone: use
        * CheckValue first to find correct position in the script.
        * @param aValue Contains the value to be verified  
        * @param aDefault When reference value isn't found from the script,
        * verification is made againts the default value when provided.
        * @return KErrNone if value was valid or KErrCorrupt if not.
        * KErrNotFound if reference data was not found from the script and
        * default value  was not supported.
        */
        TInt CheckNextValue( const TInt& aValue,
            const TInt aDefault = KMaxTInt );

        /**
        * Helper method that parses address structure from the script.
        * Structure consist of three parameters, address, type of number and
        * numbering plan. Address is mandatory. If TON and NPI are missing,
        * defaults are used. Address can provided in one of the following
        * formats:
        * Address "address"
        * Address "address" TON
        * Address "address" TON NPI
        * @param aAddress reference to packet which shall be constructed
        * @return KErrNone or KErrNotFound if address was missing
        */
        TInt GetAddress( RSat::TAddress& aAddress );
            
        /*
        * Method reads data from the script with given tag to a buffer.
        * @param aTag Tag used to find data from script
        * @param aBuffer Output where data is read to
        * @return KErrNone if successful or system wide error code if not.
        */
        TInt GetBuffer( const TDesC& aTag, TDes& aBuffer );
        
        /**
        * Helper method reads requested value from the script. Format of
        * scripted number can be given as argument, decimal is the default.
        * @param aTag Tag used to find value from script
        * @param aValue Value read from the script. 
        * @param aRadix Number format of scripted value.
        * @return KErrNone if valid value was found or KErrCorrupt if not.
        * KErrNotFound if value with provided tag was not found.
        */ 
        TInt GetValue( const TDesC& aTag, TInt& aValue,
            TRadix aRadix = EDecimal );

        /**
        * Helper method reads requested value from the script. Templated
        * parameter enables reading typed parameters from the script.
        * Declaration and implementation of template fuctions has to be 
        * in the same complilation unit ( = file )
        * @param aTag Tag used to find value from script
        * @param aValue Value read from the script. 
        * @param aRadix Number format of scripted value.
        * @return KErrNone if valid value was found or KErrCorrupt if not.
        * KErrNotFound if value with provided tag was not found.
        */ 
        template <typename TGenType>
        TInt GetValue( const TDesC& aTag, TGenType& aType,
            TRadix aRadix = EDecimal )
            {
            return GetValue( aTag, reinterpret_cast<TInt&>( aType ), aRadix );
            }
        
        /**
        * Helper method reads next value from the script. Format of
        * scripted number can be given as argument, decimal is the default.
        * Must not be used alone: use GetValue first to find correct position
        * in the script.        
        * @param aValue Value read from the script. 
        * @return KErrNone if valid value was found or KErrCorrupt if not.
        * KErrNotFound if value with provided tag was not found.
        */            
        TInt GetNextValue( TInt& aValue, TRadix aRadix = EDecimal );

        /**
        * Helper method that parses specific text string from the script as 
        * a value. Text can be presented as a quoted text string or by unicode
        * hex values.
        * @param aTag Tag used to find text from script
        * @param aTextOutput Text output
        * @return KErrNone or KErrNotFound no requested text strings wasn't
        *  found. KErrCorrupt if parsed string did not fit to output buffer.
        */
        TInt GetText( const TDesC& aTag, TDes& aText );

        /**
        * Helper method that parses specific text string from the script as 
        * a reference. Text can be presented as a quoted text string or by
        * unicode hex values.
        * @param aTag Tag used to find text from script
        * @param aText Text output
        * @param aGetNext Specifies the parsing method. Used internally.
        * @return KErrNone or KErrNotFound no requested text strings wasn't
        *  found. KErrCorrupt if parsed string did not fit to output buffer.
        */
        TInt GetText( const TDesC& aTag, TPtrC& aText,
            TBool aGetNext = EFalse );

        /**
        * Helper method reads next text string from the script as a reference.
        * Must not be used alone: use GetText first to find correct position
        * in the script.        
        * @param aTag Tag used to find text from script
        * @param aTextOutput Text output
        * @return KErrNone or KErrNotFound no requested text strings wasn't
        *  found. KErrCorrupt if parsed string did not fit to output buffer.
        */
        TInt GetNextText( const TDesC& aTag, TPtrC& aText );
        
        /**
        * Helper method that parses UssdString structure from the script.
        * UssdString can provided in one of the following formats:
        * UssdString "string"
        * UssdSting  "string" DCS
        * @param aUssdString reference to packet which shall be constructed
        * @return KErrNone or KErrNotFound if string was missing        
        */
        TInt GetUssdString( RSat::TUssdString& aUssdString );
        
        /**
        * Template method that is used to initiate data structures with 
        * default values.
        * Declaration and implementation of template fuctions has to be 
        * in the same complilation unit ( = file )
        * @param aType Type to be initialized.
        */
        template <typename TGenType>
        void Init( TGenType& aType )
            {
            aType = TGenType();
            }

            
    private:    // New methods
            
        /**
        * Method converts Hex-tagged integers with in a text string  to
        * hex numbers. Example in string "\x0F" -> value 0Fh in buffer.
        * @param aString String to be converted
        * @return None
        */ 
        void ConvertHexTags( TDes& aString );

        /**
        * Method converts a string presentation of value to a integer.
        * @param aNumberAsString String conteining the number
        * @param aRadix Defines the number format of string. Hex of decimal
        * @param aValue Number output
        * @return KErrNone if successful or system wide error code if not.
        */ 
        TInt ConvertToNumber( TPtrC& aNumberAsString, TRadix aRadix,
            TInt& aValue );
        
            
    protected:  // Data
            
        /**
        * Reference to SAT
        */        
        const RSat&             iSat;
        
        /**
        * Reference to logger
        */
        CStifLogger&            iLog;

            
    private:    // Data
    
        /**
        * IPC of the sat feature is stored here
        */        
        const TSatIpc           iIpc;
        
        /**
        * Reference to config file parser
        */
        CStifItemParser&        iParser;
    };

#endif      // SATBASE_H
            
// End of