VirtualBox

source: vbox/trunk/src/VBox/Main/include/ProgressCombinedImpl.h@ 34808

Last change on this file since 34808 was 33540, checked in by vboxsync, 14 years ago

*: spelling fixes, thanks Timeless!

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.9 KB
Line 
1/* $Id: ProgressCombinedImpl.h 33540 2010-10-28 09:27:05Z vboxsync $ */
2/** @file
3 *
4 * VirtualBox COM class implementation
5 */
6
7/*
8 * Copyright (C) 2006-2010 Oracle Corporation
9 *
10 * This file is part of VirtualBox Open Source Edition (OSE), as
11 * available from http://www.virtualbox.org. This file is free software;
12 * you can redistribute it and/or modify it under the terms of the GNU
13 * General Public License (GPL) as published by the Free Software
14 * Foundation, in version 2 as it comes in the "COPYING" file of the
15 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
16 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
17 */
18
19#ifndef ____H_PROGRESSCOMBINEDIMPL
20#define ____H_PROGRESSCOMBINEDIMPL
21
22#include "ProgressImpl.h"
23#include "AutoCaller.h"
24
25#include <vector>
26
27/**
28 * The CombinedProgress class allows to combine several progress objects to a
29 * single progress component. This single progress component will treat all
30 * operations of individual progress objects as a single sequence of operations
31 * that follow each other in the same order as progress objects are passed to
32 * the #init() method.
33 *
34 * @note CombinedProgress is legacy code and deprecated. It does not support
35 * weighted operations, all suboperations are assumed to take the same
36 * amount of time. For new code, please use IProgress directly which
37 * has supported multiple weighted suboperations since VirtualBox 3.0.
38 *
39 * Individual progress objects are sequentially combined so that this progress
40 * object:
41 *
42 * - is cancelable only if all progresses are cancelable.
43 * - is canceled once a progress that follows next to successfully completed
44 * ones reports it was canceled.
45 * - is completed successfully only after all progresses are completed
46 * successfully.
47 * - is completed unsuccessfully once a progress that follows next to
48 * successfully completed ones reports it was completed unsuccessfully;
49 * the result code and error info of the unsuccessful progress
50 * will be reported as the result code and error info of this progress.
51 * - returns N as the operation number, where N equals to the number of
52 * operations in all successfully completed progresses starting from the
53 * first one plus the operation number of the next (not yet complete)
54 * progress; the operation description of the latter one is reported as
55 * the operation description of this progress object.
56 * - returns P as the percent value, where P equals to the sum of percents
57 * of all successfully completed progresses starting from the
58 * first one plus the percent value of the next (not yet complete)
59 * progress, normalized to 100%.
60 *
61 * @note It's the responsibility of the combined progress object creator to
62 * complete individual progresses in the right order: if, let's say, the
63 * last progress is completed before all previous ones,
64 * #WaitForCompletion(-1) will most likely give 100% CPU load because it
65 * will be in a loop calling a method that returns immediately.
66 */
67class ATL_NO_VTABLE CombinedProgress :
68 public Progress
69{
70
71public:
72 VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(CombinedProgress, IProgress)
73
74 DECLARE_NOT_AGGREGATABLE(CombinedProgress)
75
76 DECLARE_PROTECT_FINAL_CONSTRUCT()
77
78 BEGIN_COM_MAP (CombinedProgress)
79 COM_INTERFACE_ENTRY (ISupportErrorInfo)
80 COM_INTERFACE_ENTRY (IProgress)
81 COM_INTERFACE_ENTRY2 (IDispatch, IProgress)
82 END_COM_MAP()
83
84 HRESULT FinalConstruct();
85 void FinalRelease();
86
87 // public initializer/uninitializer for internal purposes only
88
89 HRESULT init (
90#if !defined (VBOX_COM_INPROC)
91 VirtualBox *aParent,
92#endif
93 IUnknown *aInitiator,
94 CBSTR aDescription,
95 IProgress *aProgress1, IProgress *aProgress2,
96 OUT_GUID aId = NULL);
97
98 /**
99 * Initializes the combined progress object given the first and the last
100 * normal progress object from the list.
101 *
102 * @param aParent See ProgressBase::init().
103 * @param aInitiator See ProgressBase::init().
104 * @param aDescription See ProgressBase::init().
105 * @param aFirstProgress Iterator of the first normal progress object.
106 * @param aSecondProgress Iterator of the last normal progress object.
107 * @param aId See ProgressBase::init().
108 */
109 template <typename InputIterator>
110 HRESULT init (
111#if !defined (VBOX_COM_INPROC)
112 VirtualBox *aParent,
113#endif
114 IUnknown *aInitiator,
115 CBSTR aDescription,
116 InputIterator aFirstProgress, InputIterator aLastProgress,
117 OUT_GUID aId = NULL)
118 {
119 /* Enclose the state transition NotReady->InInit->Ready */
120 AutoInitSpan autoInitSpan (this);
121 AssertReturn (autoInitSpan.isOk(), E_FAIL);
122
123 mProgresses = ProgressVector (aFirstProgress, aLastProgress);
124
125 HRESULT rc = protectedInit (autoInitSpan,
126#if !defined (VBOX_COM_INPROC)
127 aParent,
128#endif
129 aInitiator, aDescription, aId);
130
131 /* Confirm a successful initialization when it's the case */
132 if (SUCCEEDED(rc))
133 autoInitSpan.setSucceeded();
134
135 return rc;
136 }
137
138protected:
139
140 HRESULT protectedInit (AutoInitSpan &aAutoInitSpan,
141#if !defined (VBOX_COM_INPROC)
142 VirtualBox *aParent,
143#endif
144 IUnknown *aInitiator,
145 CBSTR aDescription, OUT_GUID aId);
146
147public:
148
149 void uninit();
150
151 // IProgress properties
152 STDMETHOD(COMGETTER(Percent)) (ULONG *aPercent);
153 STDMETHOD(COMGETTER(Completed)) (BOOL *aCompleted);
154 STDMETHOD(COMGETTER(Canceled)) (BOOL *aCanceled);
155 STDMETHOD(COMGETTER(ResultCode)) (LONG *aResultCode);
156 STDMETHOD(COMGETTER(ErrorInfo)) (IVirtualBoxErrorInfo **aErrorInfo);
157 STDMETHOD(COMGETTER(Operation)) (ULONG *aCount);
158 STDMETHOD(COMGETTER(OperationDescription)) (BSTR *aOperationDescription);
159 STDMETHOD(COMGETTER(OperationPercent)) (ULONG *aOperationPercent);
160 STDMETHOD(COMSETTER(Timeout)) (ULONG aTimeout);
161 STDMETHOD(COMGETTER(Timeout)) (ULONG *aTimeout);
162
163 // IProgress methods
164 STDMETHOD(WaitForCompletion) (LONG aTimeout);
165 STDMETHOD(WaitForOperationCompletion) (ULONG aOperation, LONG aTimeout);
166 STDMETHOD(Cancel)();
167
168 STDMETHOD(SetCurrentOperationProgress)(ULONG aPercent)
169 {
170 NOREF(aPercent);
171 return E_NOTIMPL;
172 }
173
174 STDMETHOD(SetNextOperation)(IN_BSTR bstrNextOperationDescription, ULONG ulNextOperationsWeight)
175 {
176 NOREF(bstrNextOperationDescription); NOREF(ulNextOperationsWeight);
177 return E_NOTIMPL;
178 }
179
180 // public methods only for internal purposes
181
182private:
183
184 HRESULT checkProgress();
185
186 typedef std::vector <ComPtr<IProgress> > ProgressVector;
187 ProgressVector mProgresses;
188
189 size_t mProgress;
190 ULONG mCompletedOperations;
191};
192
193#endif /* ____H_PROGRESSCOMBINEDIMPL */
194
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette