epoc32/include/mw/epos_cposlmoperation.h
branchSymbian2
changeset 2 2fe1408b6811
parent 1 666f914201fb
child 4 837f303aceeb
equal deleted inserted replaced
1:666f914201fb 2:2fe1408b6811
     1 epos_cposlmoperation.h
     1 /*
       
     2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). 
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * 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
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description:  CPosLmOperation class
       
    15 *
       
    16 */
       
    17 
       
    18 
       
    19 #ifndef CPOSLMOPERATION_H
       
    20 #define CPOSLMOPERATION_H
       
    21 
       
    22 #include <e32base.h>
       
    23 
       
    24 class CPosLmOperation;
       
    25 
       
    26 /**
       
    27 *  Executes the operation synchronously and then deletes it.
       
    28 *
       
    29 *  All functions which return a @ref CPosLmOperation object can be run
       
    30 *  incrementally. If the client is not interested in running it
       
    31 *  incrementally, it can call @ref CPosLmOperation::ExecuteL to run the
       
    32 *  whole operation in one batch. This can be simplified by using
       
    33 *  @ref ExecuteAndDeleteLD. It runs the operation and deletes the object
       
    34 *  when it is done.
       
    35 *
       
    36 *  For instance, to use this function for
       
    37 *  @ref CPosLandmarkDatabase::InitializeL, the client would call
       
    38 *
       
    39 *  ExecuteAndDeleteLD( database->InitializeL() );
       
    40 *
       
    41 *  The operation object should not be on the cleanup stack when this function
       
    42 *  is called.
       
    43 *
       
    44 *  @since S60 3.0
       
    45 *  @param aOperation The operation to handle. It will be deleted when the
       
    46 *   function returns.
       
    47 */
       
    48 inline void ExecuteAndDeleteLD( CPosLmOperation* aOperation );
       
    49 
       
    50 
       
    51 /**
       
    52 *  Base class for handles to landmark operations.
       
    53 *
       
    54 *  Long running operations in the Landmarks API returns an object of this class
       
    55 *  so that the client can run it incrementally and check the progress of the
       
    56 *  operation.
       
    57 *
       
    58 *  The operation must explicitly be run by the client. The operation can
       
    59 *  be run incrementally by calling @ref NextStep until it does not return
       
    60 *  the status @p KPosLmOperationNotComplete. Alternately the operation can be
       
    61 *  run synchronously by calling @ref ExecuteL.
       
    62 *
       
    63 *  @ref ExecuteAndDeleteLD can be used to handle the operation object if
       
    64 *  it is run in synchronous mode.
       
    65 *
       
    66 *  @lib eposlandmarks.lib
       
    67 *  @since S60 3.0
       
    68 */
       
    69 class CPosLmOperation : public CBase
       
    70     {
       
    71     public:
       
    72 
       
    73         /**
       
    74         * Destructor.
       
    75         */
       
    76         IMPORT_C virtual ~CPosLmOperation();
       
    77 
       
    78     public:
       
    79 
       
    80         /**
       
    81         * Incremental execution of the operation.
       
    82         *
       
    83         * The client should use an active object and call this function until
       
    84         * it does not complete with status @p KPosLmOperationNotComplete.
       
    85         *
       
    86         * When the operation has finished, this function will complete with
       
    87         * status @p KErrNone if the operation was successful, or an error code
       
    88         * if some error was encountered.
       
    89         *
       
    90         * This function also returns a progress of the operation. Progress is a
       
    91         * floating point number in the interval [0.0,1.0]. 0.0 indicates that
       
    92         * the operation has not started and 1.0 indicates that the operation
       
    93         * has completed.
       
    94         *
       
    95         * Note that this function is asynchronous which means that status and
       
    96         * progress may not be set when the function returns. They are only
       
    97         * guaranteed to be set when the request is completed.
       
    98         *
       
    99         * The only way to cancel an operation is to delete the operation
       
   100         * object. This will also cancel any outstanding request to
       
   101         * NextStep().
       
   102         *
       
   103         * @param[out] aStatus The request status. Upon request completion contains
       
   104         *   step status: 
       
   105         *   - @p KPosLmOperationNotComplete if the step has completed but more
       
   106         *   steps are needed before the operation will be completed. 
       
   107         *   - @p KErrNone if the operation has finished successfully. 
       
   108         *   - An error code if the operation has failed.
       
   109         * @param[out] aProgress Upon request completion is set to the progress 
       
   110         *   of the operation.
       
   111         *
       
   112         * @panic "Landmarks Client"-EPosInvalidOperationMode 
       
   113         *   The function is called when the operation is already complete.
       
   114         */
       
   115         virtual void NextStep(
       
   116             TRequestStatus& aStatus,
       
   117             TReal32& aProgress
       
   118         ) = 0;
       
   119 
       
   120         /**
       
   121         * Synchronous execution of the operation.
       
   122         *
       
   123         * When this function returns, the operation has finished.
       
   124         *
       
   125         * @panic "Landmarks Client"-EPosInvalidOperationMode 
       
   126         *   -# This function is called when the operation is already complete
       
   127         *   -# The operation has already been started incrementally using @ref NextStep().
       
   128         */
       
   129         virtual void ExecuteL() = 0;
       
   130 
       
   131     protected:
       
   132 
       
   133         // C++ constructor.
       
   134         IMPORT_C CPosLmOperation();
       
   135 
       
   136     private:
       
   137 
       
   138         // Prohibit copy constructor
       
   139         CPosLmOperation( const CPosLmOperation& );
       
   140         // Prohibit assigment operator
       
   141         CPosLmOperation& operator= ( const CPosLmOperation& );
       
   142 
       
   143     };
       
   144 
       
   145 #include "EPos_CPosLmOperation.inl"
       
   146 
       
   147 #endif      // CPOSLMOPERATION_H
       
   148 
       
   149