/*

* Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "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:   

*

*/

#ifndef HNLIWUTILS_H

#define HNLIWUTILS_H

#include <e32base.h>

#include <e32hashtab.h>

#include <liwcommon.h>

class CHnMdBaseKey;

class CLiwGenericParamList;

class TLiwVariant;

/**

 *  Provides static methods which handles operations

 *  like extracting data from and inserting data to 

 *  LIW composite classes ( CLiwGenericParamList, TLiwVariant ).   

 * 

 *  @lib hnutilities.lib

 *  @since S60 v5.0

 *  @ingroup group_hnutilities

 */

NONSHARABLE_CLASS( HnLiwUtils )

    {   

public:

    /**

     * Appends key-value pairs stored in aKeys to aInParam.

     * Keys are appended in the same order as they occur in the aKeys array.

     * Every key value is converted to a TLiwVariant before appending to the

     * param list.

     * 

     * @since S60 v5.0

     * @param aKeys Keys to append.

     * @param aInParam Param list to be modified.

     */    

    IMPORT_C static void SetGenericParamListL(

        const RPointerArray<CHnMdBaseKey> & aKeys,

        CLiwGenericParamList& aInParam );

    /**

     * Creates a string representing a selected value from the param list.

     * The aPath paramter is the path to the selected param list element.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI Path.

     * @param aBuf Output buffer.

     * @return Error code.

     */

    IMPORT_C static TInt GetStringL(

        const CLiwGenericParamList& aParam, 

        const TDesC8& aPath, 

        RBuf& aBuf );

    /**

     * Creates a string representing a selected value from the param list.

     * The aPath paramter is the path to the selected param list element.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI Path.

     * @param aBuf Output buffer.

     * @return Error code.

     */

    IMPORT_C static TInt GetStringL(

        const CLiwGenericParamList& aParam, 

        const TDesC8& aPath, 

        RBuf8& aBuf );

    /**

     * Returns TInt64 value using the given path.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI Path.

     * @param aPos Position.

     * @param aRet Return TInt64 value.

     * @return TInt64 value or KErrNotFound.

     */

    IMPORT_C static TInt GetInt64L( const CLiwGenericParamList& aParam,

    	    const TDesC8& aPath, TInt aPos, TInt64& aRet );

    /**

     * Creates a string representing a selected value from the param list.

     * The aPath paramter is the path to the selected param list element.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI Path.

     * @param aPos Position.

     * @param aBuf Output buffer.

     * @return Error code.

     */

    IMPORT_C static TInt GetStringL(

        const CLiwGenericParamList& aParam, 

        const TDesC8& aPath, 

        TInt aPos,

        RBuf& aBuf );

    /**

     * Creates a string representing a selected value from the param list.

     * The aPath paramter is the path to the selected param list element.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI Path.

     * @param aPos Position.

     * @param aBuf Output buffer.

     * @return Error code.

     */

    IMPORT_C static TInt GetStringL(

        const CLiwGenericParamList& aParam, 

        const TDesC8& aPath, 

        TInt aPos,

        RBuf8& aBuf );

    /**

     *  Exctracts variant from param list.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI path.

     * @param aPos Position.

     * @param aRet Output buffer.

     * @return Error code.

     */

    IMPORT_C static TInt GetVariantL(

        const CLiwGenericParamList& aParam,

        const TDesC8& aPath,

        TInt aPos,

        TLiwVariant& aRet );

    /**

     *  Exctracts variant from param list.

     * 

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aPath URI path.

     * @param aRet Output buffer.

     * @return Error code.

     */

    IMPORT_C static TInt GetVariantL(

        const CLiwGenericParamList& aParam,

        const TDesC8& aPath,

        TLiwVariant& aRet );

    /**

     * Creates a string representation of a variant value.

     * Supported variant types are: EVariantTypeDesC, 

     * EVariantTypeDesC8, EVariantTypeTUid, EVariantTypeTInt32,

     * and EVariantTypeTUint.

     * 

     * @since S60 v5.0

     * @param aVariant Source variant.

     * @param aBuf Output buffer.

     * @return EFalse if variant type is not supported.

     */

    IMPORT_C static TBool VariantToStringL( TLiwVariant& aVariant,

                                           RBuf& aBuf );

    /**

     * Creates a string representation of a variant value.

     * Supported variant types are: EVariantTypeDesC, 

     * EVariantTypeDesC8, EVariantTypeTUid, EVariantTypeTInt32,

     * and EVariantTypeTUint.

     * 

     * @since S60 v5.0

     * @param aVariant Source variant.

     * @param aBuf Output buffer.

     * @return EFalse if variant type is not supported.

     */

    IMPORT_C static TBool VariantToStringL( TLiwVariant& aVariant,

                                           RBuf8& aBuf );

    /**

     * Gets total number of items held by an iterable.

     * 

     * @param aIterable the iterable

     * @return total number of items stored in aIterable

     */

    IMPORT_C static TInt GetIterableItemCountL( CLiwIterable& aIterable );

private:

    /**

     * Exctracts namespace from param list.

     *

     * @since S60 v5.0

     * @param aParam Param list.

     * @param aNameSpace Namespace.

     * @param aRet Output variant.

     * @return Error code.

     */

    static TInt ExtractNameSpaceL( const CLiwGenericParamList& aParam,

                                   const TDesC8& aNameSpace,

                                   TLiwVariant& aRet );

    /**

     * Process path for selecting elements separated by colon or slash.

     *

     * @since S60 v5.0

     * @param aPath Path.

     * @param aPathParts Elements of the path.

     */

    static void ParsePathL( const TDesC8& aPath, 

                           RArray< TPtrC8 >& aPathParts );

    /**

     * Replaces the first occurence of the string "$index" with a number.

     * On successful execution the string contained in aPath8 will have

     * have the first occurence of the substring "$index" replaced by

     * a string representation of the number given in aPos.

     *  

     * @since S60 v5.0

     * @param aPath8 A path to the variant in the generic param list.

     * @param aPos A position of the item in the group of items.

     * @return Length of the new path, ending at the index object.

     */

    static TInt ReplaceIndexL( RBuf8& aPath8, TInt aPos );

    /**

     * Extracts a number enclosed in square brackets from a string.

     * The number is assumed to be non-negative (otherwise it would be

     * impossible to determine if the function executed successfully).

     * If the string contains more than one pair of square brackets, only

     * the first pair is processed by this method.

     * 

     * @since S60 v5.0

     * @param aPosition String containing the position number.

     * @return Number extracted from string or error code on failure.

     */

    static TInt GetPosition( const TDesC8& aPosition );

    /**

     * Uses iterator object to extract variant pointed by position. 

     *

     * @since S60 v5.0

     * @param aIterable Iterator to use.

     * @param aPos Position of the variant.

     * @param aVariant Output variant.

     * @return ETrue if variant found.

     */

    static TBool GetIterableByPositionL(

        CLiwIterable & aIterable,

        TInt aPos,

        TLiwVariant & aVariant );

     };

#endif // HNLIWUTILS_H