1.1 --- a/epoc32/include/mw/epos_cposlmoperation.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/epos_cposlmoperation.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,149 @@
1.4 -epos_cposlmoperation.h
1.5 +/*
1.6 +* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: CPosLmOperation class
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef CPOSLMOPERATION_H
1.24 +#define CPOSLMOPERATION_H
1.25 +
1.26 +#include <e32base.h>
1.27 +
1.28 +class CPosLmOperation;
1.29 +
1.30 +/**
1.31 +* Executes the operation synchronously and then deletes it.
1.32 +*
1.33 +* All functions which return a @ref CPosLmOperation object can be run
1.34 +* incrementally. If the client is not interested in running it
1.35 +* incrementally, it can call @ref CPosLmOperation::ExecuteL to run the
1.36 +* whole operation in one batch. This can be simplified by using
1.37 +* @ref ExecuteAndDeleteLD. It runs the operation and deletes the object
1.38 +* when it is done.
1.39 +*
1.40 +* For instance, to use this function for
1.41 +* @ref CPosLandmarkDatabase::InitializeL, the client would call
1.42 +*
1.43 +* ExecuteAndDeleteLD( database->InitializeL() );
1.44 +*
1.45 +* The operation object should not be on the cleanup stack when this function
1.46 +* is called.
1.47 +*
1.48 +* @since S60 3.0
1.49 +* @param aOperation The operation to handle. It will be deleted when the
1.50 +* function returns.
1.51 +*/
1.52 +inline void ExecuteAndDeleteLD( CPosLmOperation* aOperation );
1.53 +
1.54 +
1.55 +/**
1.56 +* Base class for handles to landmark operations.
1.57 +*
1.58 +* Long running operations in the Landmarks API returns an object of this class
1.59 +* so that the client can run it incrementally and check the progress of the
1.60 +* operation.
1.61 +*
1.62 +* The operation must explicitly be run by the client. The operation can
1.63 +* be run incrementally by calling @ref NextStep until it does not return
1.64 +* the status @p KPosLmOperationNotComplete. Alternately the operation can be
1.65 +* run synchronously by calling @ref ExecuteL.
1.66 +*
1.67 +* @ref ExecuteAndDeleteLD can be used to handle the operation object if
1.68 +* it is run in synchronous mode.
1.69 +*
1.70 +* @lib eposlandmarks.lib
1.71 +* @since S60 3.0
1.72 +*/
1.73 +class CPosLmOperation : public CBase
1.74 + {
1.75 + public:
1.76 +
1.77 + /**
1.78 + * Destructor.
1.79 + */
1.80 + IMPORT_C virtual ~CPosLmOperation();
1.81 +
1.82 + public:
1.83 +
1.84 + /**
1.85 + * Incremental execution of the operation.
1.86 + *
1.87 + * The client should use an active object and call this function until
1.88 + * it does not complete with status @p KPosLmOperationNotComplete.
1.89 + *
1.90 + * When the operation has finished, this function will complete with
1.91 + * status @p KErrNone if the operation was successful, or an error code
1.92 + * if some error was encountered.
1.93 + *
1.94 + * This function also returns a progress of the operation. Progress is a
1.95 + * floating point number in the interval [0.0,1.0]. 0.0 indicates that
1.96 + * the operation has not started and 1.0 indicates that the operation
1.97 + * has completed.
1.98 + *
1.99 + * Note that this function is asynchronous which means that status and
1.100 + * progress may not be set when the function returns. They are only
1.101 + * guaranteed to be set when the request is completed.
1.102 + *
1.103 + * The only way to cancel an operation is to delete the operation
1.104 + * object. This will also cancel any outstanding request to
1.105 + * NextStep().
1.106 + *
1.107 + * @param[out] aStatus The request status. Upon request completion contains
1.108 + * step status:
1.109 + * - @p KPosLmOperationNotComplete if the step has completed but more
1.110 + * steps are needed before the operation will be completed.
1.111 + * - @p KErrNone if the operation has finished successfully.
1.112 + * - An error code if the operation has failed.
1.113 + * @param[out] aProgress Upon request completion is set to the progress
1.114 + * of the operation.
1.115 + *
1.116 + * @panic "Landmarks Client"-EPosInvalidOperationMode
1.117 + * The function is called when the operation is already complete.
1.118 + */
1.119 + virtual void NextStep(
1.120 + TRequestStatus& aStatus,
1.121 + TReal32& aProgress
1.122 + ) = 0;
1.123 +
1.124 + /**
1.125 + * Synchronous execution of the operation.
1.126 + *
1.127 + * When this function returns, the operation has finished.
1.128 + *
1.129 + * @panic "Landmarks Client"-EPosInvalidOperationMode
1.130 + * -# This function is called when the operation is already complete
1.131 + * -# The operation has already been started incrementally using @ref NextStep().
1.132 + */
1.133 + virtual void ExecuteL() = 0;
1.134 +
1.135 + protected:
1.136 +
1.137 + // C++ constructor.
1.138 + IMPORT_C CPosLmOperation();
1.139 +
1.140 + private:
1.141 +
1.142 + // Prohibit copy constructor
1.143 + CPosLmOperation( const CPosLmOperation& );
1.144 + // Prohibit assigment operator
1.145 + CPosLmOperation& operator= ( const CPosLmOperation& );
1.146 +
1.147 + };
1.148 +
1.149 +#include "EPos_CPosLmOperation.inl"
1.150 +
1.151 +#endif // CPOSLMOPERATION_H
1.152 +
1.153 +