/*
* Copyright (c) 2004 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:  This interface defines a generic data type
*
*/




#ifndef ALFMODELOPERATION_H
#define ALFMODELOPERATION_H


//INCLUDES
#include <osn/osndefines.h>
#include <osn/ustring.h>

using namespace osncore;

namespace Alf
    {

/* Forward declarations*/
class IAlfVariantType;

/** @class AlfModelOperation alfmodeloperation.h "alf/alfmodeloperation.h"
*  A class for storing information about changes in the model.
*  CAlfModelOperation can be used to make changes in a batch mode,
*  i.e., executing multiple changes in one call.
*  @lib hitchcockwidgetmodel.lib
*  @since S60 ?S60_version
*  @status Draft
*/
class AlfModelOperation
    {
public:

    /** The operation constants. */
    enum OperationType{EOperationAdd, EOperationRemove, EOperationUpdate};

    /**
     * constructor. The new operation is left on the cleanup stack.
     *
	 * @exception std::bad_alloc     
     * @since S60 ?S60_version
     * @param aOperation The operation to be performed.
     * @param aNumContainerIndices The number of indices in aContainerIndices.
     * @param aContainerIndices The container indices to find the correct location
     *                          in the data hierarchy. The ownership is transferred.
     * @param aData The new data in EOperationAdd and EOperationUpdate operations.
     *              The ownership is transferred.
     */
    OSN_IMPORT static AlfModelOperation* create( OperationType aOperation,
            int aNumContainerIndices,
            int* aContainerIndices,
            IAlfVariantType* aData = 0 );

    /**
     * constructor for adding or updating a map item.
     * The new operation is left on the cleanup stack.
     *
	 * @exception std::bad_alloc     
     * @since S60 ?S60_version
     * @param aOperation The operation to be performed.
     * @param aNumContainerIndices The number of indices in aContainerIndices.
     * @param aContainerIndices The container indices to find the correct location
     *                          in the data hierarchy. The ownership is transferred.
     * @param aData The new data. The ownership is transferred.
     * @param aDataName The name of the new data in EOperationAdd and EOperationUpdate
     *                  operations. Only needed when adding or updating a map item.
     */
    OSN_IMPORT static AlfModelOperation* create( OperationType aOperation,
            int aNumContainerIndices,
            int* aContainerIndices,
            IAlfVariantType* aData,
            const UString& aDataName );

    /** Destructor.*/
    OSN_IMPORT ~AlfModelOperation();

    /**
     * Get the name of the new data field in the container map.
     * Panics if the operation is EOperationRemove.
     *
     * @exception osncore::AlfDataException Thrown with the error code osncore::EInvalidModelOperation\n 
     *										  when wrong operation is performed on Model.
     * @return The new data.
     * @since S60 ?S60_version
     */
    OSN_IMPORT const UString& newDataName() const;

    /**
     * Get the new data used in EOperationAdd or EOperationUpdate operations.
     * Panics if the operation is EOperationRemove.
     *
     * @exception osncore::AlfDataException Thrown with the error code osncore::EInvalidModelOperation\n 
     *										  when wrong operation is performed on Model.
     * @return The new data.
     * @since S60 ?S60_version
     */
    OSN_IMPORT IAlfVariantType& newData() const;

    /**
     * Get the new data used in EOperationAdd or EOperationUpdate operations.
     * Panics if the operation is EOperationRemove.
     * The ownership of the data is transferred to the caller,
     * and the data of this operation is set to NULL.
     *
     * @exception osncore::AlfDataException Thrown with the error code osncore::EInvalidModelOperation\n 
     *										  when wrong operation is performed on Model.
     * @return The new data.
     * @since S60 ?S60_version
     */
    OSN_IMPORT IAlfVariantType* getNewData();

    /**
     * Get the Operation.
     *
     * @return The new data.
     * @since S60 ?S60_version
     */
    OSN_IMPORT AlfModelOperation::OperationType operation() const;

    /**
     * Get the parent data for the operation. The parent data
     * is a container for the data to be added, removed or updated.
     * The index of the data can be queried using Index().
     *
     * @exception osncore::AlfDataException Thrown with the error code osncore::EInvalidContainerOperation\n 
     *										  when wrong operation is performed on Model.
     * @param aRoot The root of the data hierarchy to perform the operation.
     * @return The parent data.
     * @since S60 ?S60_version
     */
    OSN_IMPORT IAlfVariantType* parentData(IAlfVariantType& aRoot ) const;

    /**
     * Get the index of the data inside the parent container.
     * The parent container can be queried using ParentData().
     * If the parent container is a branch, index 0 refers to
     * the branch data, and index 1 refers to the child data.
     *
     * @return The new data.
     * @since S60 ?S60_version
     */
    OSN_IMPORT int index() const;

    /**
     * Get the number of container indices to find the
     * location in the data hierarchy.
     *
     * @return The number of container indices.
     * @since S60 ?S60_version
     */
    OSN_IMPORT int numContainerIndices() const;

    /**
     * Get the container index to traverse through the data hierarchy.
     * If the container in the hierarchy is a branch, index 0 refers to
     * the branch data, and index 1 refers to the child data.
     *
     * @return The container index.
     * @since S60 ?S60_version
     */
    OSN_IMPORT int containerIndex( int aIndex ) const;

private:

    AlfModelOperation(
        OperationType aOperation,
        int aNumContainerIndices,
        int* aContainerIndices,
        IAlfVariantType* aData = 0 );

    AlfModelOperation(
        OperationType aOperation,
        int aNumContainerIndices,
        int* aContainerIndices,
        IAlfVariantType* aData,
        const UString& aDataName );

private: // data

    // Target location in the data hierarchy
    int mNumContainerIndices;
    int* mContainerIndices;

    // The new data
    IAlfVariantType* mData;
    // The name of the new data, if adding or updating a map item
    UString mDataName;

    // The operation to be performed
    OperationType mOperation;
    };

    } // namespace Alf

#endif // ALFMODELOPERATION_H