Automation Objects (Win32 Only)
Go Up to Object Interfaces Index
An object whose class implements the IDispatch interface (declared in the System unit) is an Automation object.
Use variants to access Automation objects. When a variant references an Automation object, you can call the object's methods and read or write to its properties through the variant. To do this, you must include ComObj in the uses clause of one of your units or your program or library.
Contents
Dispatch Interface Types
Dispatch interface types define the methods and properties that an Automation object implements through IDispatch. Calls to methods of a dispatch interface are routed through IDispatch's Invoke method at run time; a class cannot implement a dispatch interface.
A dispatch interface type declaration has the form:
type InterfaceName = dispinterface
['{GUID}']
// …
end;
where
['{GUID}']
is optional and the interface contains property and method declarations. Dispatch interface declarations are similar to regular interface declarations, but they cannot specify an ancestor. For example:
type
IStringsDisp = dispinterface
['{EE05DFE2-5549-11D0-9EA9-0020AF3D82DA}']
property ControlDefault[Index: Integer]: OleVariant dispid 0; default;
function Count: Integer; dispid 1;
property Item[Index: Integer]: OleVariant dispid 2;
procedure Remove(Index: Integer); dispid 3;
procedure Clear; dispid 4;
function Add(Item: OleVariant): Integer; dispid 5;
function _NewEnum: IUnknown; dispid -4;
end;
Dispatch interface methods
Methods of a dispatch interface are prototypes for calls to the Invoke method of the underlying IDispatch implementation. To specify an Automation dispatch ID for a method, include the dispid directive in its declaration, followed by an integer constant; specifying an already used ID causes an error.
A method declared in a dispatch interface cannot contain directives other than dispid. Parameter and result types must be automatable. In other words, they must be Byte, Currency, Real, Double, Longint, Integer, Single, Smallint, AnsiString, WideString, TDateTime, Variant, OleVariant, WordBool, or any interface type.
Dispatch interface properties
Properties of a dispatch interface do not include access specifiers. They can be declared as readonly or writeonly. To specify a dispatch ID for a property, include the dispid directive in its declaration, followed by an integer constant; specifying an already used ID causes an error. Array properties can be declared as default. No other directives are allowed in dispatch-interface property declarations.
Accessing Automation Objects
Automation object method calls are bound at run time and require no previous method declarations. The validity of these calls is not checked at compile time.
The following example illustrates Automation method calls. The CreateOleObject function (defined in ComObj) returns an IDispatch reference to an Automation object and is assignment-compatible with the variant Word:
var
Word: Variant;
begin
Word := CreateOleObject('Word.Basic');
Word.FileNew('Normal');
Word.Insert('This is the first line'#13);
Word.Insert('This is the second line'#13);
Word.FileSaveAs('c:\temp\test.txt', 3);
end;
You can pass interface-type parameters to Automation methods.
Variant arrays with an element type of varByte are the preferred method of passing binary data between Automation controllers and servers. Such arrays are subject to no translation of their data, and can be efficiently accessed using the VarArrayLock and VarArrayUnlock routines.
Automation Object Method-Call Syntax
The syntax of an Automation object method call or property access is similar to that of a normal method call or property access. Automation method calls, however, can use both positional and named parameters. (But some Automation servers do not support named parameters.)
A positional parameter is simply an expression. A named parameter consists of a parameter identifier, followed by the := symbol, followed by an expression. Positional parameters must precede any named parameters in a method call. Named parameters can be specified in any order.
Some Automation servers allow you to omit parameters from a method call, accepting their default values. For example:
Word.FileSaveAs('test.doc');
Word.FileSaveAs('test.doc', 6);
Word.FileSaveAs('test.doc',,,'secret');
Word.FileSaveAs('test.doc', Password := 'secret');
Word.FileSaveAs(Password := 'secret', Name := 'test.doc');
Automation method call parameters can be of integer, real, string, Boolean, and variant types. A parameter is passed by reference if the parameter expression consists only of a variable reference, and if the variable reference is of type Byte, Smallint, Integer, Single, Double, Currency, System.TDateTime, AnsiString, WordBool, or Variant. If the expression is not of one of these types, or if it is not just a variable, the parameter is passed by value. Passing a parameter by reference to a method that expects a value parameter causes COM to fetch the value from the reference parameter. Passing a parameter by value to a method that expects a reference parameter causes an error.
Dual Interfaces
A dual interface is an interface that supports both compile-time binding and runtime binding through Automation. Dual interfaces must descend from IDispatch.
All methods of a dual interface (except from those inherited from IInterface and IDispatch) must use the safecall convention, and all method parameter and result types must be automatable. (The automatable types are Byte, Currency, Real, Double, Real48, Integer, Single, Smallint, AnsiString, ShortString, System/TDateTime, Variant, OleVariant, and WordBool.)