juno.com.core Module

Provides support for COM (Component Object Model).

See MSDN for a glossary of terms.

Licence
See licence.txt for use and distribution terms.

bool SUCCEEDED(int hr);

Determines whether the operation was successful.

bool FAILED(int hr);

Determines whether the operation was unsuccessful.

class COMException: object.Exception;

The exception thrown when an unrecognized HRESULT is returned from a COM operation.

this(int errorCode);

Initializes a new instance with a specified error code.

Parameters
int errorCode
The error code (HRESULT) value associated with this exception.

this(string message, int errorCode);

Initializes a new instance with a specified message and error code.

Parameters
string message
The error message that explains this exception.
int errorCode
The error code (HRESULT) value associated with this exception.

int errorCode();

Gets the HRESULT of the error.

Returns
The HRESULT of the error.

Exception exceptionForHR(int errorCode);

Converts an HRESULT error code to a corresponding Exception object.

void throwExceptionForHR(int errorCode);

Throwns an exception with a specific failure HRESULT value.

struct GUID;

Represents a globally unique identifier.

static GUID empty;

A GUID whose value is all zeros.

static GUID opCall(uint a, ushort b, ushort c, ubyte d, ubyte e, ubyte f, ubyte g, ubyte h, ubyte i, ubyte j, ubyte k);

Initializes a new instance using the specified integers and bytes.

Parameters
uint a
The first 4 bytes.
ushort b
The next 2 bytes.
ushort c
The next 2 bytes.
ubyte d
The next byte.
ubyte e
The next byte.
ubyte f
The next byte.
ubyte g
The next byte.
ubyte h
The next byte.
ubyte i
The next byte.
ubyte j
The next byte.
ubyte k
The next byte.

Returns
The resulting GUID.

static GUID opCall(uint a, ushort b, ushort c, ubyte[] d);

Initializes a new instance using the specified integers and byte array.

Parameters
uint a
The first 4 bytes.
ushort b
The next 2 bytes.
ushort c
The next 2 bytes.
ubyte[] d
The remaining 8 bytes.

Returns
The resulting GUID.

Throws
IllegalArgumentException if d is not 8 bytes long.

static GUID opCall(char[] s);

Initializes a new instance using the value represented by the specified string.

Parameters
char[] s
A string containing a GUID in groups of 8, 4, 4, 4 and 12 digits with hyphens between the groups. The GUID can optionally be enclosed in braces.

Returns
The resulting GUID.

static GUID create();

Initializes a new instance of the GUID struct.

bool opEquals(GUID other);

Returns a value indicating whether two instances represent the same value.

Parameters
GUID other
A GUID to compare to this instance.

Returns
true if other is equal to this instance; otherwise, false.

int opCmp(GUID other);

Compares this instance to a specified GUID and returns an indication of their relative values.

Parameters
GUID other
A GUID to compare to this instance.

Returns
A number indicating the relative values of this instance and other.

char[] toString();
char[] toString(char[] format);

Returns a string representation of the value of this instance in registry format.

Returns
A string formatted in this pattern: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} where the GUID is represented as a series of lowercase hexadecimal digits in groups of 8, 4, 4, 4 and 12 and separated by hyphens.

uint toHash();

Retrieves the hash code for this instance.

Returns
The hash code for this instance.

char[] progIdFromClsid(GUID clsid);

Retrieves the ProgID for a given class identifier (CLSID).

GUID clsidFromProgId(char[] progId);

Retrieves the class identifier (CLSID) for a given ProgID.

char[] uuid(char[] g);

Associates a GUID with an interface.

Parameters
char[] g
A string representing the GUID in normal registry format with or without the { } delimiters.

Examples
 interface IXMLDOMDocument2 : IDispatch {
   mixin(uuid("2933bf95-7b36-11d2-b20e-00c04f983e60"));
 }

 // Expands to the following code:
 //
 // interface IXMLDOMDocument2 : IDispatch {
 //   static GUID IID = { 0x2933bf95, 0x7b36, 0x11d2, 0xb2, 0x0e, 0x00, 0xc0, 0x4f, 0x98, 0x3e, 0x60 };
 // }

template uuidof(alias T)

Retrieves the GUID associated with the specified variable or type.

Examples
 import juno.com.core,
   std.stdio;

 void main() {
   writefln("The GUID of IXMLDOMDocument2 is %s", uuidof!(IXMLDOMDocument2));
 }

 // Produces:
 // The GUID of IXMLDOMDocument2 is {2933bf95-7b36-11d2-b20e-00c04f983e60}

struct SAFEARRAY;

Represents an array of elements.

SAFEARRAY* opCall(T)(T[] array);

Initializes a new instance using the specified array.

Parameters
array
The elements with which to initialize the instance.

Returns
A pointer to the new instance.

T[] toArray(T)();

Copies the elements of the SAFEARRAY to a new array of the specified type.

Returns
An array of the specified type containing copies of the elements of the SAFEARRAY.

void destroy();

Destroys the SAFEARRAY and all of its data.

Remarks:
If objects are stored in the array, Release is called on each object.

void lock();

Increments the lock count of an array.

void unlock();

Decrements the lock count of an array.

void length(int value);
int length();

Gets or sets the number of elements in the array.

Parameters
int value
The number of elements.

struct DECIMAL;

Represents a decimal number ranging from positive 79,228,162,514,264,337,593,543,950,335 to negative 79,228,162,514,264,337,593,543,950,335.

static DECIMAL min;

Represents the smallest possible value.

static DECIMAL max;

Represents the largest possible value.

static DECIMAL minusOne;

Represents -1.

static DECIMAL zero;

Represents 0.

static DECIMAL one;

Represents 1.

DECIMAL opCall(T)(T value);
DECIMAL opCall(T = void)(uint lo, uint mid, uint hi, bool isNegative, ubyte scale);

Initializes a new instance.

static DECIMAL parse(char[] s);

Converts the string representation of a number to its DECIMAL equivalent.

static DECIMAL round(DECIMAL d, int decimals = 0);

Rounds a value to the nearest or specific number of decimal places.

static DECIMAL floor(DECIMAL d);

Rounds a value to the closest integer toward negative infinity.

static DECIMAL truncate(DECIMAL d);

Returns the integral digits of a value.

static DECIMAL remainder(DECIMAL d1, DECIMAL d2);

Computes the remainder after dividing two values.

static DECIMAL add(DECIMAL d1, DECIMAL d2);

Adds two values.

static DECIMAL subtract(DECIMAL d1, DECIMAL d2);

Subtracts one value from another.

static DECIMAL multiply(DECIMAL d1, DECIMAL d2);

Multiplies two values.

static DECIMAL divide(DECIMAL d1, DECIMAL d2);

Divides two values.

static DECIMAL negate(DECIMAL d);

Returns the result of multiplying a value by -1.

char[] toString();

Converts the numeric value of this instance to its equivalent string representation.

static int compare(DECIMAL d1, DECIMAL d2);

Compares two values.

int compareTo(DECIMAL value);
int opCmp(DECIMAL d);

Compares this instance to a specified instance.

static bool equals(DECIMAL d1, DECIMAL d2);

Returns a value indicating whether two instances represent the same value.

bool equals(DECIMAL value);
bool opEquals(DECIMAL d);

Returns a value indicating whether this instance and a specified instance represent the same value.

VARIANT_TRUE

Represents the boolean value true (-1).

VARIANT_FALSE

Represents the boolean value false (0).

template VariantType(T)

Determines the equivalent COM type of a built-in type at compile-time.

Examples
 auto a = VariantType!(string);          // VT_BSTR
 auto b = VariantType!(bool);            // VT_BOOL
 auto c = VariantType!(typeof([1,2,3])); // VT_ARRAY | VT_I4

struct VARIANT;

A container for many different types.

Examples
 VARIANT var = 10;     // Instance contains VT_I4.
 var = "Hello, World"; // Instance now contains VT_BSTR.
 var = 234.5;          // Instance now contains VT_R8.

ushort vt;

Describes the type of the instance.

static VARIANT Missing;

Represents the missing value.

static VARIANT Nothing;

Represents the nothing value.

static VARIANT Null;

Represents the null value.

VARIANT opCall(T)(T value, ushort type = VariantType!(T));

Initializes a new instance using the specified value and type.

Parameters
value
A value of one of the acceptable types.
type
The ushort identifying the type of value.

Returns
The resulting VARIANT.

void clear();

Clears the value of this instance and releases any associated memory.

See Also
VariantClear.

void copyTo(out VARIANT dest);

Copies this instance into the destination value.

Parameters
VARIANT dest
The variant to copy into.

VARIANT changeType(ushort newType);

Convers a variant from one type to another.

Parameters
ushort newType
The type to change to.

char[] toString();

Converts the value contained in this instance to a string.

Returns
A string representation of the value contained in this instance.

V value(V)();

Returns the value contained in this instance.

bool isEmpty();

Determines whether this instance is empty.

bool isNull();

Determines whether this instance is null.

bool isNothing();

Determines whether this instance is Nothing.

enum ExceptionPolicy;

Specifies whether to throw exceptions or return null when COM operations fail.

NoThrow

Returns null on failure.

Throw

Throws an exception on failure.

template com_cast(T)

Invokes the conversion operation to convert from one COM type to another.

If the operand is a VARIANT, this function converts its value to the type represented by T. If the operand is an IUnknown-derived object, this function calls the object's QueryInterface method. If the conversion operation fails, the function returns T.init.

Examples
 // C++
 bool tryToMeow(Dog* dog) {
   Cat* cat = NULL;
   HRESULT hr = dog->QueryInterface(IID_Cat, static_cast<void**>(&cat));
   if (hr == S_OK) {
     hr = cat->meow();
     cat->Release();
   }
   return hr == S_OK;
 }

 // C#
 bool tryToMeow(Dog dog) {
   Cat cat = dog as Cat;
   if (cat != null)
     return cat.meow();
   return false;
 }

 // D
 bool tryToMeow(Dog dog) {
   if (auto cat = com_cast!(Cat)(dog)) {
     scope(exit) cat.Release();
     return cat.meow() == S_OK;
   }
   return false;
 }

template com_safe_cast(T)

Invokes the conversion operation to convert from one COM type to another, as above, but throws an exception if the cast fails.

Throws
COMException if the cast failed.

enum ExecutionContext;

Specifies the context in which the code that manages an object will run.

See Also
CLSCTX Enumeration.

InProcessServer

The code that creates and manages objects of this class is a DLL that runs in the same process as the caller of the function specifying the class context.

InProcessHandler

The code that manages objects of this class is an in-process handler. is a DLL that runs in the client process and implements client-side structures of this class when instances of the class are accessed remotely.

LocalServer

The code that creates and manages objects of this class runs on same machine but is loaded in a separate process space.

RemoteServer

A remote context. The code that creates and manages objects of this class is run on a different computer.

IUnknown coCreateInstance(GUID clsid, IUnknown outer, ExecutionContext context, GUID iid);

Creates an object of the class associated with a specified GUID.

Parameters
GUID clsid
The class associated with the object.
IUnknown outer
If null, indicates that the object is not being created as part of an aggregate.
ExecutionContext context
Context in which the code that manages the object will run.
GUID iid
The identifier of the interface to be used to communicate with the object.

Returns
The requested object.

See Also
CoCreateInstance.

IUnknown getActiveObject(char[] progId);

Returns a reference to a running object that has been registered with OLE.

See Also
GetActiveObject.

template coCreate(T,ExceptionPolicy policy = ExceptionPolicy.NoThrow)

Creates a COM object of the class associated with the specified CLSID.

Parameters
clsid
A CLSID associated with the coclass that will be used to create the object.
context
The context in which to run the code that manages the new object with run.

Returns
A reference to the interface identified by T.

Examples
 if (auto doc = coCreate!(IXMLDOMDocument3)(uuidof!(DOMDocument60))) {
   scope(exit) doc.Release();
 }

template IUnknownImpl(T...)

Provides an implementation of IUnknown suitable for using as mixin.

template IDispatchImpl(T...)

Provides an implementation of IDispatch suitable for using as mixin.

class Implements(T...): T;

The abstract base class for COM objects that derive from IUnknown or IDispatch.

The Implements class provides default implementations of methods required by those interfaces. Therefore, subclasses need only override them when they specifically need to provide extra functionality. This class also overrides the new operator so that instances are not garbage collected.

Examples
 class MyImpl : Implements!(IUnknown) {
 }

bool isCOMObject(Object obj);

Indicates whether the specified object represents a COM object.

Parameters
Object obj
The object to check.

Returns
true if obj is a COM type; otherwise, false.

class COMObject;

Wraps a manually reference counted IUnknown-derived object so that its memory can be managed automatically by the D runtime's garbage collector.

this(IUnknown obj);

Initializes a new instance with the specified IUnknown-derived object.

Parameters
IUnknown obj
The object to wrap.

IUnknown opCast();

Retrieves the original IUnknown-derived object.

Returns
The wrapped object.

void tryRelease(IUnknown obj);

Decrements the reference count for an object.

void finalRelease(IUnknown obj);

Decrements the reference count for an object until it reaches 0.

wchar* toBstr(char[] s);

Allocates a BSTR equivalent to s.

Parameters
char[] s
The string with which to initialize the BSTR.

Returns
The BSTR equivalent to s.

char[] fromBstr(wchar* s, bool free = true);

Converts a BSTR to a string, optionally freeing the original BSTR.

Parameters
bstr
The BSTR to convert.

Returns
A string equivalent to bstr.

void freeBstr(wchar* s);

Frees the memory occupied by the specified BSTR.

Parameters
bstr
The BSTR to free.

class COMStream: juno.com.core.Implements!(IStream).Implements;

Provides an implementation of the IStream interface.

enum DispatchFlags;

Specifies the type of member to that is to be invoked.

InvokeMethod

Specifies that a method is to be invoked.

GetProperty

Specifies that the value of a property should be returned.

PutProperty

Specifies that the value of a property should be set.

PutRefProperty

Specifies that the value of a property should be set by reference.

class MissingMemberException: object.Exception;

The exception thrown when there is an attempt to dynamically access a member that does not exist.

VARIANT invokeMemberById(int dispId, DispatchFlags flags, IDispatch target, VARIANT[] args...);

Invokes the specified member on the specified object.

Parameters
int dispId
The identifier of the method or property member to invoke.
DispatchFlags flags
The type of member to invoke.
IDispatch target
The object on which to invoke the specified member.
VARIANT[] args
A list containing the arguments to pass to the member to invoke.

Returns
The return value of the invoked member.

Throws
COMException if the call failed.

VARIANT invokeMember(char[] name, DispatchFlags flags, IDispatch target, VARIANT[] args...);

Invokes the specified member on the specified object.

Parameters
char[] name
The name of the method or property member to invoke.
DispatchFlags flags
The type of member to invoke.
IDispatch target
The object on which to invoke the specified member.
VARIANT[] args
A list containing the arguments to pass to the member to invoke.

Returns
The return value of the invoked member.

Throws
MissingMemberException if the member is not found.

R invokeMethod(R = VARIANT)(IDispatch target, string name,...);

Invokes the specified method on the specified object.

Parameters
target
The object on which to invoke the specified method.
name
The name of the method to invoke.
_argptr
A list containing the arguments to pass to the method to invoke.

Returns
The return value of the invoked method.

Throws
MissingMemberException if the method is not found.

Examples
 import juno.com.core;

 void main() {
   auto ieApp = coCreate!(IDispatch)("InternetExplorer.Application");
   invokeMethod(ieApp, "Navigate", "http://www.amazon.co.uk");
 }

R getProperty(R = VARIANT)(IDispatch target, string name,...);

Gets the value of the specified property on the specified object.

Parameters
target
The object on which to invoke the specified property.
name
The name of the property to invoke.
_argptr
A list containing the arguments to pass to the property.

Returns
The return value of the invoked property.

Throws
MissingMemberException if the property is not found.

Examples
 import juno.com.core, std.stdio;

 void main() {
   // Create an instance of the Microsoft Word automation object.
   IDispatch wordApp = coCreate!(IDispatch)("Word.Application");

   // Invoke the Documents property
   //   wordApp.Documents
   IDispatch documents = getProperty!(IDispatch)(target, "Documents");

   // Invoke the Count property on the Documents object
   //   documents.Count
   VARIANT count = getProperty(documents, "Count");

   // Display the value of the Count property.
   writefln("There are %s documents", count);
 }

void setProperty(IDispatch target, char[] name,...);
void setRefProperty(IDispatch target, char[] name,...);

Sets the value of a specified property on the specified object.

Parameters
IDispatch target
The object on which to invoke the specified property.
char[] name
The name of the property to invoke.
_argptr
A list containing the arguments to pass to the property.

Throws
MissingMemberException if the property is not found.

Examples
 import juno.com.core;

 void main() {
   // Create an Excel automation object.
   IDispatch excelApp = coCreate!(IDispatch)("Excel.Application");

   // Set the Visible property to true
   //   excelApp.Visible = true
   setProperty(excelApp, "Visible", true);

   // Get the Workbooks property
   //   workbooks = excelApp.Workbooks
   IDispatch workbooks = getProperty!(IDispatch)(excelApp, "Workbooks");

   // Invoke the Add method on the Workbooks property
   //   newWorkbook = workbooks.Add()
   IDispatch newWorkbook = invokeMethod!(IDispatch)(workbooks, "Add");

   // Get the Worksheets property and the Worksheet at index 1
   //   worksheet = excelApp.Worksheets[1]
   IDispatch worksheet = getProperty!(IDispatch)(excelApp, "Worksheets", 1);

   // Get the Cells property and set the Cell object at column 5, row 3 to a string
   //   worksheet.Cells[5, 3] = "data"
   setProperty(worksheet, "Cells", 5, 3, "data");
 }