ProgressImpl.h revision b2c92fb03e119c7de54f86a32fae9c1d59bc479e
/* $Id$ */
/** @file
*
* VirtualBox COM class implementation
*/
/*
* Copyright (C) 2006-2009 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ____H_PROGRESSIMPL
#define ____H_PROGRESSIMPL
#include "VirtualBoxBase.h"
#include <iprt/semaphore.h>
#include <vector>
////////////////////////////////////////////////////////////////////////////////
/**
* Base component class for progress objects.
*/
{
// protected initializer/uninitializer for internal purposes only
#if !defined (VBOX_COM_INPROC)
#endif
// IProgress properties
// IProgress properties
// public methods only for internal purposes
// unsafe inline public methods for internal purposes only (ensure there is
// a caller and a read lock before calling them!)
double calcTotalPercent();
void checkForAutomaticTimeout(void);
#if !defined (VBOX_COM_INPROC)
/** Weak parent. */
#endif
const Bstr mDescription;
void (*m_pfnCancelCallback)(void *);
void *m_pvCancelUserArg;
/* The fields below are to be properly initalized by subclasses */
ULONG m_cOperations; // number of operations (so that progress dialog can display something like 1/3)
ULONG m_ulOperationsCompletedWeight; // summed-up weight of operations that have been completed; initially 0
Bstr m_bstrOperationDescription; // name of current operation; initially from constructor, changed with setNextOperation()
ULONG m_ulOperationPercent; // percentage of current operation, set with setCurrentOperationProgress()
};
////////////////////////////////////////////////////////////////////////////////
/**
* Normal progress object.
*/
{
void FinalRelease();
// public initializer/uninitializer for internal purposes only
/**
* Simplified constructor for progress objects that have only one
* operation as a task.
* @param aParent
* @param aInitiator
* @param aDescription
* @param aCancelable
* @param aId
* @return
*/
#if !defined (VBOX_COM_INPROC)
#endif
{
return init(
#if !defined (VBOX_COM_INPROC)
#endif
1, // cOperations
1, // ulTotalOperationsWeight
aDescription, // bstrFirstOperationDescription
1, // ulFirstOperationWeight
aId);
}
/**
* Not quite so simplified constructor for progress objects that have
* more than one operation, but all sub-operations are weighed the same.
* @param aParent
* @param aInitiator
* @param aDescription
* @param aCancelable
* @param cOperations
* @param bstrFirstOperationDescription
* @param aId
* @return
*/
#if !defined (VBOX_COM_INPROC)
#endif
{
return init(
#if !defined (VBOX_COM_INPROC)
#endif
cOperations, // cOperations
cOperations, // ulTotalOperationsWeight = cOperations
bstrFirstOperationDescription, // bstrFirstOperationDescription
1, // ulFirstOperationWeight: weigh them all the same
aId);
}
#if !defined (VBOX_COM_INPROC)
#endif
void uninit();
// IProgress methods
// public methods only for internal purposes
const Bstr &aComponent,
const char *aText, ...);
bool notifyPointOfNoReturn(void);
/** For com::SupportErrorInfoImpl. */
static const char *ComponentName() { return "Progress"; }
};
////////////////////////////////////////////////////////////////////////////////
/**
* The CombinedProgress class allows to combine several progress objects to a
* single progress component. This single progress component will treat all
* operations of individual progress objects as a single sequence of operations
* that follow each other in the same order as progress objects are passed to
* the #init() method.
*
* Individual progress objects are sequentially combined so that this progress
* object:
*
* - is cancelable only if all progresses are cancelable.
* - is canceled once a progress that follows next to successfully completed
* ones reports it was canceled.
* - is completed successfully only after all progresses are completed
* successfully.
* - is completed unsuccessfully once a progress that follows next to
* successfully completed ones reports it was completed unsuccessfully;
* the result code and error info of the unsuccessful progress
* will be reported as the result code and error info of this progress.
* - returns N as the operation number, where N equals to the number of
* operations in all successfully completed progresses starting from the
* first one plus the operation number of the next (not yet complete)
* progress; the operation description of the latter one is reported as
* the operation description of this progress object.
* - returns P as the percent value, where P equals to the sum of percents
* of all successfully completed progresses starting from the
* first one plus the percent value of the next (not yet complete)
* progress, normalized to 100%.
*
* @note It's the respoisibility of the combined progress object creator to
* complete individual progresses in the right order: if, let's say, the
* last progress is completed before all previous ones,
* #WaitForCompletion(-1) will most likely give 100% CPU load because it
* will be in a loop calling a method that returns immediately.
*/
{
void FinalRelease();
// public initializer/uninitializer for internal purposes only
#if !defined (VBOX_COM_INPROC)
#endif
/**
* Initializes the combined progress object given the first and the last
* normal progress object from the list.
*
* @param aParent See ProgressBase::init().
* @param aInitiator See ProgressBase::init().
* @param aDescription See ProgressBase::init().
* @param aFirstProgress Iterator of the first normal progress object.
* @param aSecondProgress Iterator of the last normal progress object.
* @param aId See ProgressBase::init().
*/
#if !defined (VBOX_COM_INPROC)
#endif
{
/* Enclose the state transition NotReady->InInit->Ready */
#if !defined (VBOX_COM_INPROC)
#endif
/* Confirm a successful initialization when it's the case */
return rc;
}
#if !defined (VBOX_COM_INPROC)
#endif
void uninit();
// IProgress properties
// IProgress methods
{
return E_NOTIMPL;
}
{
return E_NOTIMPL;
}
// public methods only for internal purposes
/** For com::SupportErrorInfoImpl. */
static const char *ComponentName() { return "CombinedProgress"; }
};
#endif /* ____H_PROGRESSIMPL */