williamr@2: /*
williamr@2: * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  CPosLmOperation class
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef CPOSLMOPERATION_H
williamr@2: #define CPOSLMOPERATION_H
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: 
williamr@2: class CPosLmOperation;
williamr@2: 
williamr@2: /**
williamr@2: *  Executes the operation synchronously and then deletes it.
williamr@2: *
williamr@2: *  All functions which return a @ref CPosLmOperation object can be run
williamr@2: *  incrementally. If the client is not interested in running it
williamr@2: *  incrementally, it can call @ref CPosLmOperation::ExecuteL to run the
williamr@2: *  whole operation in one batch. This can be simplified by using
williamr@2: *  @ref ExecuteAndDeleteLD. It runs the operation and deletes the object
williamr@2: *  when it is done.
williamr@2: *
williamr@2: *  For instance, to use this function for
williamr@2: *  @ref CPosLandmarkDatabase::InitializeL, the client would call
williamr@2: *
williamr@2: *  ExecuteAndDeleteLD( database->InitializeL() );
williamr@2: *
williamr@2: *  The operation object should not be on the cleanup stack when this function
williamr@2: *  is called.
williamr@2: *
williamr@2: *  @since S60 3.0
williamr@2: *  @param aOperation The operation to handle. It will be deleted when the
williamr@2: *   function returns.
williamr@2: */
williamr@2: inline void ExecuteAndDeleteLD( CPosLmOperation* aOperation );
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: *  Base class for handles to landmark operations.
williamr@2: *
williamr@2: *  Long running operations in the Landmarks API returns an object of this class
williamr@2: *  so that the client can run it incrementally and check the progress of the
williamr@2: *  operation.
williamr@2: *
williamr@2: *  The operation must explicitly be run by the client. The operation can
williamr@2: *  be run incrementally by calling @ref NextStep until it does not return
williamr@2: *  the status @p KPosLmOperationNotComplete. Alternately the operation can be
williamr@2: *  run synchronously by calling @ref ExecuteL.
williamr@2: *
williamr@2: *  @ref ExecuteAndDeleteLD can be used to handle the operation object if
williamr@2: *  it is run in synchronous mode.
williamr@2: *
williamr@2: *  @lib eposlandmarks.lib
williamr@2: *  @since S60 3.0
williamr@2: */
williamr@2: class CPosLmOperation : public CBase
williamr@2:     {
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         IMPORT_C virtual ~CPosLmOperation();
williamr@2: 
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2:         * Incremental execution of the operation.
williamr@2:         *
williamr@2:         * The client should use an active object and call this function until
williamr@2:         * it does not complete with status @p KPosLmOperationNotComplete.
williamr@2:         *
williamr@2:         * When the operation has finished, this function will complete with
williamr@2:         * status @p KErrNone if the operation was successful, or an error code
williamr@2:         * if some error was encountered.
williamr@2:         *
williamr@2:         * This function also returns a progress of the operation. Progress is a
williamr@2:         * floating point number in the interval [0.0,1.0]. 0.0 indicates that
williamr@2:         * the operation has not started and 1.0 indicates that the operation
williamr@2:         * has completed.
williamr@2:         *
williamr@2:         * Note that this function is asynchronous which means that status and
williamr@2:         * progress may not be set when the function returns. They are only
williamr@2:         * guaranteed to be set when the request is completed.
williamr@2:         *
williamr@2:         * The only way to cancel an operation is to delete the operation
williamr@2:         * object. This will also cancel any outstanding request to
williamr@2:         * NextStep().
williamr@2:         *
williamr@2:         * @param[out] aStatus The request status. Upon request completion contains
williamr@2:         *   step status: 
williamr@2:         *   - @p KPosLmOperationNotComplete if the step has completed but more
williamr@2:         *   steps are needed before the operation will be completed. 
williamr@2:         *   - @p KErrNone if the operation has finished successfully. 
williamr@2:         *   - An error code if the operation has failed.
williamr@2:         * @param[out] aProgress Upon request completion is set to the progress 
williamr@2:         *   of the operation.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosInvalidOperationMode 
williamr@2:         *   The function is called when the operation is already complete.
williamr@2:         */
williamr@2:         virtual void NextStep(
williamr@2:             TRequestStatus& aStatus,
williamr@2:             TReal32& aProgress
williamr@2:         ) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Synchronous execution of the operation.
williamr@2:         *
williamr@2:         * When this function returns, the operation has finished.
williamr@2:         *
williamr@2:         * @panic "Landmarks Client"-EPosInvalidOperationMode 
williamr@2:         *   -# This function is called when the operation is already complete
williamr@2:         *   -# The operation has already been started incrementally using @ref NextStep().
williamr@2:         */
williamr@2:         virtual void ExecuteL() = 0;
williamr@2: 
williamr@2:     protected:
williamr@2: 
williamr@2:         // C++ constructor.
williamr@2:         IMPORT_C CPosLmOperation();
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         // Prohibit copy constructor
williamr@2:         CPosLmOperation( const CPosLmOperation& );
williamr@2:         // Prohibit assigment operator
williamr@2:         CPosLmOperation& operator= ( const CPosLmOperation& );
williamr@2: 
williamr@2:     };
williamr@2: 
williamr@2: #include "EPos_CPosLmOperation.inl"
williamr@2: 
williamr@2: #endif      // CPOSLMOPERATION_H
williamr@2: 
williamr@2: