/*
* 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:  CPosLmOperation class
*
*/


#ifndef CPOSLMOPERATION_H
#define CPOSLMOPERATION_H

#include <e32base.h>

class CPosLmOperation;

/**
*  Executes the operation synchronously and then deletes it.
*
*  All functions which return a @ref CPosLmOperation object can be run
*  incrementally. If the client is not interested in running it
*  incrementally, it can call @ref CPosLmOperation::ExecuteL to run the
*  whole operation in one batch. This can be simplified by using
*  @ref ExecuteAndDeleteLD. It runs the operation and deletes the object
*  when it is done.
*
*  For instance, to use this function for
*  @ref CPosLandmarkDatabase::InitializeL, the client would call
*
*  ExecuteAndDeleteLD( database->InitializeL() );
*
*  The operation object should not be on the cleanup stack when this function
*  is called.
*
*  @since S60 3.0
*  @param aOperation The operation to handle. It will be deleted when the
*   function returns.
*/
inline void ExecuteAndDeleteLD( CPosLmOperation* aOperation );


/**
*  Base class for handles to landmark operations.
*
*  Long running operations in the Landmarks API returns an object of this class
*  so that the client can run it incrementally and check the progress of the
*  operation.
*
*  The operation must explicitly be run by the client. The operation can
*  be run incrementally by calling @ref NextStep until it does not return
*  the status @p KPosLmOperationNotComplete. Alternately the operation can be
*  run synchronously by calling @ref ExecuteL.
*
*  @ref ExecuteAndDeleteLD can be used to handle the operation object if
*  it is run in synchronous mode.
*
*  @lib eposlandmarks.lib
*  @since S60 3.0
*/
class CPosLmOperation : public CBase
    {
    public:

        /**
        * Destructor.
        */
        IMPORT_C virtual ~CPosLmOperation();

    public:

        /**
        * Incremental execution of the operation.
        *
        * The client should use an active object and call this function until
        * it does not complete with status @p KPosLmOperationNotComplete.
        *
        * When the operation has finished, this function will complete with
        * status @p KErrNone if the operation was successful, or an error code
        * if some error was encountered.
        *
        * This function also returns a progress of the operation. Progress is a
        * floating point number in the interval [0.0,1.0]. 0.0 indicates that
        * the operation has not started and 1.0 indicates that the operation
        * has completed.
        *
        * Note that this function is asynchronous which means that status and
        * progress may not be set when the function returns. They are only
        * guaranteed to be set when the request is completed.
        *
        * The only way to cancel an operation is to delete the operation
        * object. This will also cancel any outstanding request to
        * NextStep().
        *
        * @param[out] aStatus The request status. Upon request completion contains
        *   step status: 
        *   - @p KPosLmOperationNotComplete if the step has completed but more
        *   steps are needed before the operation will be completed. 
        *   - @p KErrNone if the operation has finished successfully. 
        *   - An error code if the operation has failed.
        * @param[out] aProgress Upon request completion is set to the progress 
        *   of the operation.
        *
        * @panic "Landmarks Client"-EPosInvalidOperationMode 
        *   The function is called when the operation is already complete.
        */
        virtual void NextStep(
            TRequestStatus& aStatus,
            TReal32& aProgress
        ) = 0;

        /**
        * Synchronous execution of the operation.
        *
        * When this function returns, the operation has finished.
        *
        * @panic "Landmarks Client"-EPosInvalidOperationMode 
        *   -# This function is called when the operation is already complete
        *   -# The operation has already been started incrementally using @ref NextStep().
        */
        virtual void ExecuteL() = 0;

    protected:

        // C++ constructor.
        IMPORT_C CPosLmOperation();

    private:

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

    };

#include "EPos_CPosLmOperation.inl"

#endif      // CPOSLMOPERATION_H