/*
* Copyright (c) 2005-2006 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:  CPosLmCompositeCriteria class
*
*/


#ifndef CPOSLMCOMPOSITECRITERIA_H
#define CPOSLMCOMPOSITECRITERIA_H

#include <e32base.h>
#include "EPos_CPosLmSearchCriteria.h"

/**
*  Class used to combine multiple search criterion.
*
*  For instance, to search for all restaurants in the area, this class can be
*  used to combine a @ref CPosLmAreaCriteria and a @ref CPosLmCategoryCriteria.
*
*  If a @ref CPosLmNearestCriteria is used and no sort preference is specified,
*  the result will be sorted by distance. If more than one
*  @ref CPosLmNearestCriteria are combined using a @ref CPosLmCompositeCriteria,
*  the sort order will be undefined unless a sort preference is specified.
*
*  Nested @ref CPosLmCompositeCriteria are not allowed.
*
*  This criterion only supports searching for landmarks, e.g. if it is passed
*  to @p CPosLandmarkSearch::StartCategorySearchL, the function will fail with
*  error code @p KErrNotSupported.
*
*  @lib eposlmsearchlib.lib
*  @since S60 3.0
*/
class CPosLmCompositeCriteria : public CPosLmSearchCriteria
    {
    public:

        /**
        *  Specifies the type of the composite criterion.
        *  ECompositionOR - is supported only when all the contained critarias are CPosLmTextCriteria. it is not supported for other criteria.
        */
        enum TCompositionType
            {
            ECompositionAND = 0,     /**< Search results must match all
                                    * contained criteria. */
            ECompositionOR = 1		/**< Search result must match one of the contained criteria
            	
            						* ECompositionOR - is supported only when all the contained critarias are CPosLmTextCriteria. it is not supported for other criteria*/
            };

    public:

        /**
        * Two-phased constructor.
        *
        * @param[in] aType The composition type to use.
        * @returns A new instance of this class.
        */
        IMPORT_C static CPosLmCompositeCriteria* NewLC(
            TCompositionType  aType
        );

        /**
        * Destructor.
        */
        virtual ~CPosLmCompositeCriteria();

    public:

        /**
        * Returns the type of this composite criterion.
        *
        * @return The composition type. 
        */
        IMPORT_C TCompositionType CompositionType() const;

        /**
        * Set the type of this composite criterion.
        *
        * @param[in] The composition type to use. 
        */
        IMPORT_C void SetCompositionType( TCompositionType  aType );

        /**
        * Returns the number of criteria this object contains.
        *
        * @return The number of criteria this object contains.
        */
        IMPORT_C TUint NumOfArguments() const;

        /**
        * Returns a criterion argument contained in this object.
        *
        * This overload returns a const reference to the criterion argument.
        * There is another overload which returns a non-const reference.
        *
        * @param aIndex The argument to read. Must be in the interval
        *   [0, @ref NumOfArguments - 1], or this function will raise a
        *   USER-130 panic.
        * @return The requested argument.
        */
        IMPORT_C const CPosLmSearchCriteria& Argument( TUint aIndex ) const;

        /**
        * Returns a criterion argument contained in this object.
        *
        * This overload returns a non-const reference to the criterion
        * argument. There is another overload which returns a const reference.
        *
        * @param aIndex The argument to read. Must be in the interval
        *   [0, @ref NumOfArguments - 1], or this function will raise a
        *   USER-130 panic.
        * @return The requested argument.
        */
        IMPORT_C CPosLmSearchCriteria& Argument( TUint aIndex );

        /**
        * Adds a criterion to this composition.
        *
        * The composite criterion must contain at least one argument, otherwise
        * @ref CPosLandmarkSearch::StartLandmarkSearchL will fail with error
        * code @p KErrArgument.
        *
        * If this function returns without an error code, ownership of the
        * added criterion object is transferred to the composite object.
        *
        * @ref CPosLmCompositeCriteria are not supported when composition type is @ref ECompositionAND.
        * @ref Only CPosLmTextCriteria is supported in the case of @ref ECompositionOR
        *
        * Searching for landmark categories using @ref CPosLmCompositeCriteria 
        * is not supported in the case of ECompositionAND.
        *
        * @param[in] aCriteria The criterion to add to the composition.
        * @returns - @p KErrNone if successful
        *          - @p KErrNotSupported 
        *				- @p if @ref CPosLmCompositeCriteria or @ref CPosLmCatNameCriteria is specified when coposition type is ECompositionAND.
        *			 	- @p If criteria other than CPosLmTextCriteria is specified with ECompositionOR
        *          - @p otherwise a system wide error code.
        */
        IMPORT_C TInt AddArgument( CPosLmSearchCriteria* aCriteria );

        /**
        * Removes a criterion from this composition.
        *
        * Note: This function does not delete the criterion object. Instead,
        * the ownership of the object is passed to the caller.
        *
        * @param aIndex The argument to remove. Must be in the interval
        *   [0, @ref NumOfArguments - 1], or this function will raise a
        *   USER-130 panic.
        *
        * @returns The criterion object which was removed from the composition.
        */
        IMPORT_C CPosLmSearchCriteria* RemoveArgument( TUint  aIndex );

        /**
        * Removes and deletes all contained criterion objects.
        *
        * The composite criterion must contain at least one argument, otherwise
        * @ref CPosLandmarkSearch::StartLandmarkSearchL will fail with error
        * code @p KErrArgument.
        */
        IMPORT_C void ClearArguments();

    private:

        CPosLmCompositeCriteria( TCompositionType aType );

        void ConstructL();

        // Prohibit copy constructor
        CPosLmCompositeCriteria( const CPosLmCompositeCriteria& );
        // Prohibit assigment operator
        CPosLmCompositeCriteria& operator= ( const CPosLmCompositeCriteria& );

    private:

        TCompositionType                    iCompositionType;
        RPointerArray<CPosLmSearchCriteria> iArguments;

    };

#endif      // CPOSLMCOMPOSITECRITERIA_H