ProgressImpl.h revision c461a5e1d5095c611743c913ccf069cfc085f7d6
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * VirtualBox COM class implementation
a0a3a26a4065b9401681a8c99a11bd83e08f94ccvboxsync * Copyright (C) 2006-2009 Sun Microsystems, Inc.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * available from http://www.virtualbox.org. This file is free software;
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * you can redistribute it and/or modify it under the terms of the GNU
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * General Public License (GPL) as published by the Free Software
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
f632be0ea31134f1ce343e84c90d7984d2bf96b2vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * additional information or have any questions.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync////////////////////////////////////////////////////////////////////////////////
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * Base component class for progress objects.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT (ProgressBase)
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // protected initializer/uninitializer for internal purposes only
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync HRESULT protectedInit (AutoInitSpan &aAutoInitSpan,
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync HRESULT protectedInit (AutoInitSpan &aAutoInitSpan);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync void protectedUninit (AutoUninitSpan &aAutoUninitSpan);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync // IProgress properties
63a3c5be7ac89d0d5b3386988f8c2f78df0cacf6vboxsync STDMETHOD(COMGETTER(Description)) (BSTR *aDescription);
63a3c5be7ac89d0d5b3386988f8c2f78df0cacf6vboxsync STDMETHOD(COMGETTER(Initiator)) (IUnknown **aInitiator);
63a3c5be7ac89d0d5b3386988f8c2f78df0cacf6vboxsync // IProgress properties
63a3c5be7ac89d0d5b3386988f8c2f78df0cacf6vboxsync STDMETHOD(COMGETTER(Cancelable)) (BOOL *aCancelable);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync STDMETHOD(COMGETTER(TimeRemaining)) (LONG *aTimeRemaining);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync STDMETHOD(COMGETTER(Completed)) (BOOL *aCompleted);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync STDMETHOD(COMGETTER(ResultCode)) (LONG *aResultCode);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync STDMETHOD(COMGETTER(ErrorInfo)) (IVirtualBoxErrorInfo **aErrorInfo);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync STDMETHOD(COMGETTER(OperationCount)) (ULONG *aOperationCount);
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync STDMETHOD(COMGETTER(OperationDescription)) (BSTR *aOperationDescription);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync STDMETHOD(COMGETTER(OperationPercent)) (ULONG *aOperationPercent);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // public methods only for internal purposes
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync static HRESULT setErrorInfoOnThread (IProgress *aProgress);
5eb36887f6970e0033f63fa135f3bb8fbfd6059bvboxsync bool setCancelCallback(void (*pfnCallback)(void *), void *pvUser);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // unsafe inline public methods for internal purposes only (ensure there is
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // a caller and a read lock before calling them!)
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync /** Weak parent. */
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync uint64_t m_ullTimestamp; // progress object creation timestamp, for ETA computation
63a3c5be7ac89d0d5b3386988f8c2f78df0cacf6vboxsync void (*m_pfnCancelCallback)(void *);
ed82223f8f7be1435bf9b203a0ee4fbdfc856dc8vboxsync /* The fields below are to be properly initalized by subclasses */
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync ULONG m_cOperations; // number of operations (so that progress dialog can display something like 1/3)
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync ULONG m_ulTotalOperationsWeight; // sum of weights of all operations, given to constructor
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync ULONG m_ulOperationsCompletedWeight; // summed-up weight of operations that have been completed; initially 0
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync ULONG m_ulCurrentOperation; // operations counter, incremented with each setNextOperation()
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync Bstr m_bstrOperationDescription; // name of current operation; initially from constructor, changed with setNextOperation()
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync ULONG m_ulCurrentOperationWeight; // weight of current operation, given to setNextOperation()
f3abe19bdaeea1b354674327ee95707281a6ad83vboxsync ULONG m_ulOperationPercent; // percentage of current operation, set with setCurrentOperationProgress()
f3abe19bdaeea1b354674327ee95707281a6ad83vboxsync////////////////////////////////////////////////////////////////////////////////
f3abe19bdaeea1b354674327ee95707281a6ad83vboxsync * Normal progress object.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync public com::SupportErrorInfoDerived<ProgressBase, Progress, IProgress>,
25c15196ec95f6a53e802167c815286cecfeb278vboxsync // public initializer/uninitializer for internal purposes only
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync * Simplified constructor for progress objects that have only one
ae5fc6ddd3d2ccdb941b1aacd23f6791fecc3354vboxsync * operation as a task.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aParent
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aInitiator
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aDescription
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aCancelable
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aId
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * Not quite so simplified constructor for progress objects that have
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * more than one operation, but all sub-operations are weighed the same.
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aParent
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aInitiator
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aDescription
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aCancelable
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param cOperations
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param bstrFirstOperationDescription
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync * @param aId
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync cOperations, // ulTotalOperationsWeight = cOperations
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync bstrFirstOperationDescription, // bstrFirstOperationDescription
a0a3a26a4065b9401681a8c99a11bd83e08f94ccvboxsync 1, // ulFirstOperationWeight: weigh them all the same
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // IProgress methods
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync STDMETHOD(WaitForOperationCompletion)(ULONG aOperation, LONG aTimeout);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync STDMETHOD(SetCurrentOperationProgress)(ULONG aPercent);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync STDMETHOD(SetNextOperation)(IN_BSTR bstrNextOperationDescription, ULONG ulNextOperationsWeight);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // public methods only for internal purposes
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync const char *aText, ...);
221f7b41140948bedfb450353dcefb70c014e12avboxsync /** For com::SupportErrorInfoImpl. */
221f7b41140948bedfb450353dcefb70c014e12avboxsync static const char *ComponentName() { return "Progress"; }
221f7b41140948bedfb450353dcefb70c014e12avboxsync////////////////////////////////////////////////////////////////////////////////
221f7b41140948bedfb450353dcefb70c014e12avboxsync * The CombinedProgress class allows to combine several progress objects to a
221f7b41140948bedfb450353dcefb70c014e12avboxsync * single progress component. This single progress component will treat all
221f7b41140948bedfb450353dcefb70c014e12avboxsync * operations of individual progress objects as a single sequence of operations
221f7b41140948bedfb450353dcefb70c014e12avboxsync * that follow each other in the same order as progress objects are passed to
221f7b41140948bedfb450353dcefb70c014e12avboxsync * the #init() method.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * Individual progress objects are sequentially combined so that this progress
221f7b41140948bedfb450353dcefb70c014e12avboxsync * - is cancelable only if all progresses are cancelable.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * - is canceled once a progress that follows next to successfully completed
221f7b41140948bedfb450353dcefb70c014e12avboxsync * ones reports it was canceled.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * - is completed successfully only after all progresses are completed
221f7b41140948bedfb450353dcefb70c014e12avboxsync * successfully.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * - is completed unsuccessfully once a progress that follows next to
221f7b41140948bedfb450353dcefb70c014e12avboxsync * successfully completed ones reports it was completed unsuccessfully;
221f7b41140948bedfb450353dcefb70c014e12avboxsync * the result code and error info of the unsuccessful progress
221f7b41140948bedfb450353dcefb70c014e12avboxsync * will be reported as the result code and error info of this progress.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * - returns N as the operation number, where N equals to the number of
221f7b41140948bedfb450353dcefb70c014e12avboxsync * operations in all successfully completed progresses starting from the
221f7b41140948bedfb450353dcefb70c014e12avboxsync * first one plus the operation number of the next (not yet complete)
221f7b41140948bedfb450353dcefb70c014e12avboxsync * progress; the operation description of the latter one is reported as
221f7b41140948bedfb450353dcefb70c014e12avboxsync * the operation description of this progress object.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * - returns P as the percent value, where P equals to the sum of percents
221f7b41140948bedfb450353dcefb70c014e12avboxsync * of all successfully completed progresses starting from the
221f7b41140948bedfb450353dcefb70c014e12avboxsync * first one plus the percent value of the next (not yet complete)
221f7b41140948bedfb450353dcefb70c014e12avboxsync * progress, normalized to 100%.
221f7b41140948bedfb450353dcefb70c014e12avboxsync * @note It's the respoisibility of the combined progress object creator to
221f7b41140948bedfb450353dcefb70c014e12avboxsync * complete individual progresses in the right order: if, let's say, the
221f7b41140948bedfb450353dcefb70c014e12avboxsync * last progress is completed before all previous ones,
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * #WaitForCompletion(-1) will most likely give 100% CPU load because it
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * will be in a loop calling a method that returns immediately.
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync public com::SupportErrorInfoDerived<ProgressBase, CombinedProgress, IProgress>,
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync public VirtualBoxSupportTranslation<CombinedProgress>
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync VIRTUALBOXSUPPORTTRANSLATION_OVERRIDE (CombinedProgress)
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync // public initializer/uninitializer for internal purposes only
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * Initializes the combined progress object given the first and the last
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * normal progress object from the list.
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * @param aParent See ProgressBase::init().
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * @param aInitiator See ProgressBase::init().
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * @param aDescription See ProgressBase::init().
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * @param aFirstProgress Iterator of the first normal progress object.
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * @param aSecondProgress Iterator of the last normal progress object.
d074b9bd5c1fffc376db9d56ff9d090fb9ced642vboxsync * @param aId See ProgressBase::init().
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync InputIterator aFirstProgress, InputIterator aLastProgress,
f632be0ea31134f1ce343e84c90d7984d2bf96b2vboxsync /* Enclose the state transition NotReady->InInit->Ready */
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync mProgresses = ProgressVector (aFirstProgress, aLastProgress);
f632be0ea31134f1ce343e84c90d7984d2bf96b2vboxsync /* Confirm a successful initialization when it's the case */
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync HRESULT protectedInit (AutoInitSpan &aAutoInitSpan,
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync // IProgress properties
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync STDMETHOD(COMGETTER(Completed)) (BOOL *aCompleted);
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync STDMETHOD(COMGETTER(ResultCode)) (LONG *aResultCode);
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync STDMETHOD(COMGETTER(ErrorInfo)) (IVirtualBoxErrorInfo **aErrorInfo);
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync STDMETHOD(COMGETTER(OperationDescription)) (BSTR *aOperationDescription);
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync STDMETHOD(COMGETTER(OperationPercent)) (ULONG *aOperationPercent);
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync // IProgress methods
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync STDMETHOD(WaitForOperationCompletion) (ULONG aOperation, LONG aTimeout);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync STDMETHOD(SetCurrentOperationProgress)(ULONG aPercent)
f632be0ea31134f1ce343e84c90d7984d2bf96b2vboxsync STDMETHOD(SetNextOperation)(IN_BSTR bstrNextOperationDescription, ULONG ulNextOperationsWeight)
f632be0ea31134f1ce343e84c90d7984d2bf96b2vboxsync NOREF(bstrNextOperationDescription); NOREF(ulNextOperationsWeight);
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync // public methods only for internal purposes
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync /** For com::SupportErrorInfoImpl. */
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync static const char *ComponentName() { return "CombinedProgress"; }
30a23dfc653298a09d77d3045cf873b1bd6ddecfvboxsync typedef std::vector <ComPtr<IProgress> > ProgressVector;
23ff0a80f28ba27da3cb458face82665fe65e96cvboxsync#endif /* ____H_PROGRESSIMPL */