COMDefs.h revision f72cbd6a549c34992fa79cce84600fe2b92b3299
/** @file
*
* VBox frontends: Qt GUI ("VirtualBox"):
* Various COM definitions and COM wrapper class declarations
*
* This header is used in conjunction with the header generated from
* XIDL expressed interface definitions to provide cross-platform Qt-based
* interface wrapper classes.
*/
/*
* Copyright (C) 2006-2008 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 __COMDefs_h__
#define __COMDefs_h__
/** @defgroup grp_QT_COM Qt-COM Support Layer
* @{
*
* The Qt-COM support layer provides a set of definitions and smart classes for
* components through exposed COM interfaces. This layer is based on the
*
* ...
*
* @defgroup grp_QT_COM_arrays Arrays
* @{
*
* with a type that corresponds to the COM type of elements in the array using
* normal Qt-COM type mapping rules. Here is a code example that demonstrates
* how to call interface methods that take and return arrays (this example is
* based on examples given in @ref grp_COM_arrays):
* @code
CSomething component;
// ...
QVector <LONG> in (3);
in [0] = -1;
in [1] = -2;
in [2] = -3;
QVector <LONG> out;
QVector <LONG> ret;
ret = component.TestArrays (in, out);
for (size_t i = 0; i < ret.size(); ++ i)
LogFlow (("*** ret[%u]=%d\n", i, ret [i]));
* @endcode
* @}
*/
* Either of them can be already included here, so try to shut them up. */
/* Qt includes */
#include <QString>
#include <QUuid>
#include <QVector>
/*
* Additional COM / XPCOM defines and includes
*/
#if !defined (VBOX_WITH_XPCOM)
#else /* !defined (VBOX_WITH_XPCOM) */
#include <nsXPCOM.h>
#include <nsMemory.h>
#include <nsIComponentManager.h>
#endif /* !defined (VBOX_WITH_XPCOM) */
/* VirtualBox interfaces declarations */
#if !defined (VBOX_WITH_XPCOM)
#include <VirtualBox.h>
#else /* !defined (VBOX_WITH_XPCOM) */
#include <VirtualBox_XPCOM.h>
#endif /* !defined (VBOX_WITH_XPCOM) */
#include "VBoxDefs.h"
/////////////////////////////////////////////////////////////////////////////
/** Represents extended error information */
{
: mIsNull (true)
, mIsBasicAvailable (false), mIsFullAvailable (false)
, mResultCode (S_OK) {}
/* the default copy ctor and assignment op are ok */
bool isBasicAvailable() const { return mIsBasicAvailable; }
bool isFullAvailable() const { return mIsFullAvailable; }
bool mIsNull : 1;
bool mIsBasicAvailable : 1;
bool mIsFullAvailable : 1;
};
/////////////////////////////////////////////////////////////////////////////
/**
* Base COM class the CInterface template and all wrapper classes are derived
* from. Provides common functionality for all COM wrappers.
*/
{
static HRESULT InitializeCOM();
static HRESULT CleanupCOM();
/**
* Returns the result code of the last interface method called by the
* wrapper instance or the result of CInterface::createInstance()
* operation.
*/
#if !defined (VBOX_WITH_XPCOM)
/** Converts a GUID value to QUuid */
{
}
#else /* !defined (VBOX_WITH_XPCOM) */
/** Converts a GUID value to QUuid */
{
}
#endif /* !defined (VBOX_WITH_XPCOM) */
/* Arrays of arbitrary types */
{
AssertMsgFailedReturnVoid (("No conversion!\n"));
}
{
AssertMsgFailedReturnVoid (("No conversion!\n"));
}
{
AssertMsgFailedReturnVoid (("No conversion!\n"));
}
{
AssertMsgFailedReturnVoid (("No conversion!\n"));
}
/* Arrays of equal types */
{
}
{
}
/* Arrays of strings */
/* Arrays of GUID */
/* Arrays of enums. Does a cast similar to what ENUMOut does. */
{
}
{
}
/* Arrays of interface pointers. Note: we need a separate pair of names
* only because the MSVC8 template matching algorithm is poor and tries to
* instantiate a com::SafeIfaceArray <BSTR> (!!!) template otherwise for
* *no* reason and fails. Note that it's also not possible to choose the
* correct function by specifying template arguments explicitly because then
* it starts to try to instantiate the com::SafeArray <I> template for
* *no* reason again and fails too. Definitely, broken. Works in GCC like a
* charm. */
{
{
if (aArr [i])
}
}
{
}
/* no arbitrary instance creations */
#if defined (VBOX_WITH_XPCOM)
static XPCOMEventQSocketListener *sSocketListener;
#endif
/** Adapter to pass QString as input BSTR params */
{
~BSTRIn()
{
if (bstr)
}
};
/** Adapter to pass QString as output BSTR params */
{
~BSTROut()
{
if (bstr) {
}
}
};
/**
* Adapter to pass K* enums as output COM enum params (*_T).
*
* @param QE K* enum.
* @param CE COM enum.
*/
{
};
#if !defined (VBOX_WITH_XPCOM)
/** Adapter to pass QUuid as input GUID params */
/** Adapter to pass QUuid as output GUID params */
{
{
}
~GUIDOut()
{
}
};
#else /* !defined (VBOX_WITH_XPCOM) */
/** Adapter to pass QUuid as input GUID params */
{
}
/** Adapter to pass QUuid as output GUID params */
{
~GUIDOut()
{
if (nsid)
{
}
}
};
#endif /* !defined (VBOX_WITH_XPCOM) */
};
/////////////////////////////////////////////////////////////////////////////
/**
* Alternative base class for the CInterface template that adds the errorInfo()
* method for providing extended error info about unsuccessful invocation of the
* last called interface method.
*/
{
/**
* Returns error info set by the last unsuccessfully invoked interface
* method. Returned error info is useful only if CInterface::lastRC()
* represents a failure or a warning (i.e. CInterface::isReallyOk() is
* false).
*/
/* no arbitrary instance creation */
COMBaseWithEI() : COMBase () {};
{
}
};
/////////////////////////////////////////////////////////////////////////////
/**
* Simple class that encapsulates the result code and COMErrorInfo.
*/
{
/**
* Queries the current result code from the given component.
*/
/**
* Queries the current result code and error info from the given component.
*/
/**
* Queries the current result code from the given component.
*/
{
return *this;
}
/**
* Queries the current result code and error info from the given component.
*/
{
return *this;
}
/**
* Returns @c true if the result code represents success (with or without
* warnings).
*/
/**
* Returns @c true if the result code represents success with one or more
* warnings.
*/
/**
* Returns @c true if the result code represents success with no warnings.
*/
};
/////////////////////////////////////////////////////////////////////////////
/**
* Wrapper template class for all interfaces.
*
* All interface methods named as they are in the original, i.e. starting
* with the capital letter. All utility non-interface methods are named
* starting with the small letter. Utility methods should be not normally
* called by the end-user client application.
*
* @param I Interface class (i.e. IUnknown/nsISupports derivant).
* @param B Base class, either COMBase (by default) or COMBaseWithEI.
*/
{
typedef B Base;
typedef I Iface;
// constructors & destructor
{
}
// utility methods
{
if (!mIface)
{
#if !defined (VBOX_WITH_XPCOM)
_ATL_IIDOF (I), (void **) &mIface);
#else /* !defined (VBOX_WITH_XPCOM) */
(void **) &mIface);
#endif /* !defined (VBOX_WITH_XPCOM) */
/* fetch error info, but don't assert if it's missing -- many other
* reasons can lead to an error (w/o providing error info), not only
* the instance initialization code (that should always provide it) */
}
}
/**
* Attaches to the given foreign interface pointer by querying the own
* interface on it. The operation may fail.
*/
{
/* be aware of self assignment */
if (aIface)
{
#if !defined (VBOX_WITH_XPCOM)
#else /* !defined (VBOX_WITH_XPCOM) */
#endif /* !defined (VBOX_WITH_XPCOM) */
}
else
{
}
};
/** Specialization of attach() for our own interface I. Never fails. */
{
/* be aware of self assignment */
};
/** Detaches from the underlying interface pointer. */
/** Returns @c true if not attached to any interface pointer. */
/**
* Returns @c true if the result code represents success (with or without
* warnings).
*/
/**
* Returns @c true if the result code represents success with one or more
* warnings.
*/
/**
* Returns @c true if the result code represents success with no warnings.
*/
// utility operators
{
return *this;
}
{
return *this;
}
/**
* Returns the raw interface pointer. Not intended to be used for anything
* else but in generated wrappers and for debugging. You've been warned.
*/
};
/////////////////////////////////////////////////////////////////////////////
{
CUnknown() {}
/** Creates an instance given another CInterface-based instance. */
{
{
/* preserve old error info if any */
}
}
/** Constructor specialization for IUnknown. */
/** Creates an instance given a foreign interface pointer. */
{
}
/** Constructor specialization for IUnknown. */
/** Assigns from another CInterface-based instance. */
{
{
/* preserve old error info if any */
}
return *this;
}
/** Assignment specialization for CUnknown. */
{
return *this;
}
/** Assigns from a foreign interface pointer. */
{
return *this;
}
/** Assignment specialization for IUnknown. */
{
return *this;
}
/* @internal Used in generated wrappers. Never use directly. */
};
/////////////////////////////////////////////////////////////////////////////
/* include the generated header containing concrete wrapper definitions */
#include "COMWrappers.h"
/** @} */
#endif // __COMDefs_h__