Wrapper class allows creating and using any Automation COM object. More...

Inheritance diagram for MAutomation:

Classes
class	COMInitializer
	Initialize and uninitialize COM in constructor and destructor. More...

Public Member Functions
	MAutomation (IDispatch *dispatch)
	Constructor that takes the dispatch interface, used internally by CreateObject method. More...

	MAutomation (const MAutomation &other)
	Copy constructor that creates a new dispatch interface. More...

virtual	~MAutomation ()
	Destroy the object and decrement reference, as OLE requires.

MAutomation &	operator= (const MAutomation &other)
	Assignment operator that makes this automation object point to some other interface. More...

IDispatch *	GetDispatch () const
	Access the native dispatch interface of the automation object.

MStdString	GetProgId () const
	Program ID, reconstructed from the automation interface. More...

virtual MVariant	GetProperty (const MStdString &name) const
	Overloaded to provide access to COM properties.

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Overloaded to allow changing COM properties.

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Overloaded to provide implementation of all Call methods.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists in the Automation interface. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists in the Automation interface. More...

MVariant	GetAutomationProperty (const MStdString &name) const
	Get proper property of the automation object. More...

void	SetAutomationProperty (const MStdString &name, const MVariant &value)
	Set proper property of the automation object. More...

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

virtual unsigned	GetEmbeddedSizeof () const
	For embedded object types, return the size of the class. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Static Public Member Functions
static MAutomation *	CreateObject (const MStdString &objectNameOrGUID)
	Public creator of the automation object. More...

static void	RegisterMeterObjectsComponentCategory ()
	Register meter objects component category, as required by COM Registration. More...

static SAFEARRAY *	ToSafeArray (const char *data, unsigned size)
	Convert the given buffer and length into a safe array, handled by COM Automation interface. More...

static SAFEARRAY *	ToSafeArray (const MByteString &data)
	Convert the given byte string into a safe array, handled by COM Automation interface. More...

static MByteString	ToByteString (const SAFEARRAY *safeArray)
	Convert the given COM safe array into a byte string. More...

static MByteString	ToByteString (const BSTR b)
	Convert COM BSTR into a byte string using MeteringSDK convention. More...

static MByteString	ToByteString (const VARIANT *b)
	Convert COM VARIANT into a byte string using MeteringSDK convention. More...

static BSTR	ToBSTR (const MStdString &str)
	Convert the given standard string into COM BSTR. More...

static BSTR	ToByteStringBSTR (const MByteString &str)
	Convert the given byte string into COM BSTR according to MeteringSDK rules for Byte String. More...

static MStdString	ToStdString (const BSTR b)
	Convert COM BSTR into a string. More...

static VARIANT_BOOL	ToOleBool (bool value)
	Convert a boolean into COM boolean type. More...

static bool	ToBool (VARIANT_BOOL value)
	Convert COM boolean into C++ bool value. More...

static MVariant	ToTimeOrTimeSpan (DATE date)
	Convert COM DATE into MTime or MTimeSpan. More...

static DATE	ToOleDate (const MTime &time)
	Convert MTime into COM DATE object. More...

static MVariant	ToMVariant (const VARIANT &value)
	Convert the COM/OLE variant into MeteringSDK MVariant type. More...

static CComVariant	ToOleVariant (const MVariant &value, bool treatByteStringAsString=false)
	Convert MeteringSDK MVariant into COM/OLE variant type. More...

static void	CheckParameterExists (void *o, MConstChars argumentName)
	Check if the parameter is given, defined. More...


static MVariant	ToMVariant (const SAFEARRAY *, VARTYPE vt)

static MVariant	ToMVariant (const SAFEARRAY *)

Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Static Public Attributes
static CATID	CATID_MeterObjects
	Globally define Meter Objects Category IID.

Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Additional Inherited Members
Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Detailed Description

Wrapper class allows creating and using any Automation COM object.

As the class is Reflection-enabled, COM properties and methods can be accessed exactly in the same way as native Reflection properties and methods.

This class exists only on Windows.

Constructor & Destructor Documentation

MAutomation::MAutomation ( IDispatch * dispatch )

inline

Constructor that takes the dispatch interface, used internally by CreateObject method.

Use without CreateObject() shall be done with care, as there is no AddRef done here.

Parameters

dispatch The dispatch interface to use. Shall be nonzero (checked only in debug mode).

MAutomation::MAutomation ( const MAutomation & other )

inline

Copy constructor that creates a new dispatch interface.

Parameters

other The Automation interface from which to create a new object. There is a limited debug check present.

Member Function Documentation

static void MAutomation::CheckParameterExists	(	void *	o,
		MConstChars	argumentName
	)

static

Check if the parameter is given, defined.

Precondition: If passed object is null then an exception will be thrown.

static MAutomation* MAutomation::CreateObject ( const MStdString & objectNameOrGUID )

static

Public creator of the automation object.

Parameters

objectNameOrGUID Name of the Automation object such as "Scripting.FileSystemObject", or a GUID string such as "{ABB4186F-9130-11D3-8BD6-005004058322}". The GUID shall be wrapped into curly braces. The object shall exist in the system, or an exception is thrown.

Returns: The object wrapper, which can further be used just as regular Reflection-enabled class.

MVariant MAutomation::GetAutomationProperty ( const MStdString & name ) const

Get proper property of the automation object.

This service is helpful when MObject property has the same name as the automation object property.

MStdString MAutomation::GetProgId ( ) const

Program ID, reconstructed from the automation interface.

The call is always successful, but it can return a default value "Automation" if something is wrong with the registration of the object.

virtual bool MAutomation::IsPropertyPresent ( const MStdString & name ) const

virtual

Tell if the property with the given name exists in the Automation interface.

Due to OLE restriction, the service name is indistinguishable from property name. This way, the given name could actually be a property.

Reimplemented from MObject.

virtual bool MAutomation::IsServicePresent ( const MStdString & name ) const

virtual

Tell if the service with the given name exists in the Automation interface.

Due to OLE restriction, the service name is indistinguishable from property name. This way, the given name could actually be a property.

Reimplemented from MObject.

MAutomation& MAutomation::operator= ( const MAutomation & other )

inline

Assignment operator that makes this automation object point to some other interface.

Parameters

other The Automation interface from which to copy a new object. There is a limited debug check present.

static void MAutomation::RegisterMeterObjectsComponentCategory ( )

static

Register meter objects component category, as required by COM Registration.

This call is necessary to make from facades that expose the function of the library to COM clients.

void MAutomation::SetAutomationProperty	(	const MStdString &	name,
		const MVariant &	value
	)

Set proper property of the automation object.

This service is helpful when MObject property has the same name as the automation object property.

static bool MAutomation::ToBool ( VARIANT_BOOL value )

inlinestatic

Convert COM boolean into C++ bool value.

Parameters

value COM Boolean value to convert.

Returns: VARIANT_FALSE converts into false, and anything else is true.

static BSTR MAutomation::ToBSTR ( const MStdString & str )

static

Convert the given standard string into COM BSTR.

Parameters

str	String to convert into BSTR

Returns: Result BSTR, UNICODE string

static MByteString MAutomation::ToByteString ( const SAFEARRAY * safeArray )

static

Convert the given COM safe array into a byte string.

Parameters

safeArray Safe array to convert. There is a debug check to make sure the given safe array is not zero. The elements of the array should be bytes.

Returns: byte string to represent the safe array.

static MByteString MAutomation::ToByteString ( const BSTR b )

static

Convert COM BSTR into a byte string using MeteringSDK convention.

Parameters

b	BSTR string to convert, shall not be NULL and shall only have unicode characters in range 0 .. 255.

Returns: Result byte string

static MByteString MAutomation::ToByteString ( const VARIANT * b )

static

Convert COM VARIANT into a byte string using MeteringSDK convention.

Parameters

b	VARIANT of type byte array, variant array, or BSTR.

Returns: Result byte string

static BSTR MAutomation::ToByteStringBSTR ( const MByteString & str )

static

Convert the given byte string into COM BSTR according to MeteringSDK rules for Byte String.

Parameters

str	String to convert into Byte String BSTR

Returns: Result BSTR, string that has byte values in range 0 .. 255

static MVariant MAutomation::ToMVariant	(	const SAFEARRAY *	,
		VARTYPE	vt
	)

static

Convert a safe array into a variant.

The specified variant type may have VT_ARRAY bit set (it is ignored).

For byte arrays, MByteString variant is returned.
For BSTR arrays, MStdStringCollection variant is returned.
For the other types, MVariant::VariantVector variant is returned.

In Windows CE, there is no way to determine SAFEARRAY's data type on CE, this is why CE version has only one parameter.

Precondition: The safe array shall be of the supported type with one dimension. Otherwise an exception is thrown.

static MVariant MAutomation::ToMVariant ( const SAFEARRAY * )

static

Convert a safe array into a variant.

The specified variant type may have VT_ARRAY bit set (it is ignored).

For byte arrays, MByteString variant is returned.
For BSTR arrays, MStdStringCollection variant is returned.
For the other types, MVariant::VariantVector variant is returned.

In Windows CE, there is no way to determine SAFEARRAY's data type on CE, this is why CE version has only one parameter.

Precondition: The safe array shall be of the supported type with one dimension. Otherwise an exception is thrown.

static MVariant MAutomation::ToMVariant ( const VARIANT & value )

static

Convert the COM/OLE variant into MeteringSDK MVariant type.

The call tries to preserve type information as much as possible, however the conversions are done.

Parameters

value Value to convert. The variant has to be of Automation-compatible types, otherwise an exception is thrown.

Returns: MVariant to represent the given COM VARIANT.

static VARIANT_BOOL MAutomation::ToOleBool ( bool value )

inlinestatic

Convert a boolean into COM boolean type.

Parameters

value Boolean value to convert.

Returns: Result VARIANT_BOOL value, either VARIANT_TRUE or VARIANT_FALSE.

static DATE MAutomation::ToOleDate ( const MTime & time )

static

Convert MTime into COM DATE object.

COM DATE type is just a double precision value.

Parameters

time	The time and date to convert. If the value is MTime::IsNull, COM DATE is 0.0.

Returns: COM DATE is returned that corresponds to parameter.

static CComVariant MAutomation::ToOleVariant	(	const MVariant &	value,
		bool	treatByteStringAsString = `false`
	)

static

Convert MeteringSDK MVariant into COM/OLE variant type.

The call tries to preserve type information as much as possible, however the conversions are done.

Parameters

value	Value to convert. The variant has to be of Automation-compatible types, otherwise an exception is thrown.
treatByteStringAsString	If the given variant is a byte string, this boolean value tells if it has to be converted into a COM UNICODE string where each character will be within range 0 .. 255 to represent a byte. Default value for this parameter is false, do not convert byte string into UNICODE string.

static SAFEARRAY* MAutomation::ToSafeArray	(	const char *	data,
		unsigned	size
	)

static

Convert the given buffer and length into a safe array, handled by COM Automation interface.

Parameters

data	Data buffer to convert. There is a debug check whether the data is not NULL.
size	Size of the data buffer.

Returns: COM array object is created and returned, the elements are variants that have bytes.

See also: ToSafeArray(const MByteString&); ToByteString(const SAFEARRAY*)

static SAFEARRAY* MAutomation::ToSafeArray ( const MByteString & data )

inlinestatic

Convert the given byte string into a safe array, handled by COM Automation interface.

Parameters

data	Data array to convert.

Returns: COM array object is created and returned, the elements are variants that have bytes.

See also: ToSafeArray(const char* data, unsigned size); ToByteString(const SAFEARRAY*)

static MStdString MAutomation::ToStdString ( const BSTR b )

static

Convert COM BSTR into a string.

Parameters

b	BSTR string to convert, shall not be NULL.

Returns: Result string

static MVariant MAutomation::ToTimeOrTimeSpan ( DATE date )

static

Convert COM DATE into MTime or MTimeSpan.

COM DATE type is just a double precision value.

Parameters

date	The date parameter, shall be valid, otherwise an MTime::IsNull time is returned. MTime::IsNull will also result if COM DATE is 0.0.

Returns: Variant type is returned that contains either MTime or MTimeSpan.

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation