Объекты автоматизации

Перевод раздела Automation Objects (Win32 Only) из справочной системы Delphi

Объект, класс которого поддерживает интерфейс IDispatch (объявлен в модуле System), является объектом автоматизации (Automation object).

Для обращения к объектам автоматизации следует использовать переменные типа вариант. Когда переменная типа вариант ссылается на объект автоматизации, с ее помощью вы можете вызывать методы этого объекта, читать и записывать значения его свойств. Для того чтобы сделать это, подключите модуль ComObj в раздел uses вашей программы или библиотеки.

Диспетчеризация интерфейсных типов

Диспетчеризация интерфейсных типов определяет методы и свойства, которые объект автоматизации поддерживает через IDispatch. Вызовы методов интерфейса диспетчеризации при выполнении программы направляются через метод Invoke интерфейса IDispatch, так как класс не может поддерживать интерфейс диспетчеризации.

Объявление интерфейса диспетчеризации имеет вид:

type interfaceName = dispinterface
  ['{GUID}']
  memberList
end;

где [{GUID}] – опционален, а memberList состоит из объявлений свойств и методов. Объявления интерфейсов диспетчеризации схожи с объявлениями обычных интерфейсов, но в них не может быть указан интерфейс-предок. То есть:

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;

Методы интерфейса диспетчеризации

Методы интерфейса диспетчеризации являются прототипами метода Invoke в "подложенной" реализации IDispatch. Для того чтобы определить ID диспетчера автоматизации для метода, необходимо включить в его объявление dispid, следом за которым указывается целочисленная константа. При указании константы, которая уже была использована, возникает ошибка.

Объявление метода в интерфейсе диспетчеризации не может содержать никаких директив, кроме dispid. Параметр и тип результата должны быть автоматизируемы. Иначе говоря, они не могут иметь типы, отличные от Byte,Currency, Real, Double, Longint, Integer, Single, Smallint, AnsiString, WideString, TDateTime, Variant, OleVariant, WordBool или другого интерфейсного типа.

Свойства интерфейса диспетчеризации

Объявления свойств интерфейса диспетчеризации не могут содержать спецификаторов доступа. Они могут объявляться как свойства только для чтения или только для записи (read only или write only). Для указания ID диспетчеризации для свойства в его объявление необходимо включить директиву dispid, следом за которой указывается целочисленная константа. При указании константы, которая уже была использована, возникает ошибка. Свойства-массивы могут быть объявлены с директивой default. Использование прочих директив в объявлении свойств интерфейсов диспетчеризации не разрешается.

Доступ к объектам автоматизации

Связывание вызовов методов объектов автоматизации происходит в режиме выполнения программы и не требует наличия объявления предыдущих методов. Допустимость таких вызовов при компиляции не проверяется.

Следующий пример показывает вызовы автоматизированных методов. Функция CreateOleObject (объявленная в ComObj) возвращает ссылку IDispatch на объект автоматизации. Она совместима по присваиванию с переменной вариантного типа 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;

Вы можете передавать параметры типа интерфейс в методы автоматизации.

Вариантные массивы с элементами типа varByte являются предпочтительным вариантом для передачи двоичных данных между контроллерами автоматизации и серверами. Данные из этих массивов не нуждаются в трансляции, а доступ к ним может быть эффективно организован при помощи подпрограмм VarArrayLock и VarArrayUnlock.

Синтаксис вызова методов объектов автоматизации

Синтаксис вызова методов объектов автоматизации или доступа к их свойствам схож с обычным вызовом методов или доступом к свойствам. Тем не менее, при вызове методов автоматизации могут быть использованы как позиционные, так и именованные параметры (некоторые сервера автоматизации не поддерживают именованных параметров).

Позиционный параметр – это обычное выражение. Именованный параметр состоит из идентификатора параметра, за которым указывается символ :=, за которым следует выражение. При вызове метода перед позиционными параметрами необходимо включать любые именованные параметры. Именованные параметры могут быть указаны в любом порядке.

Некоторые сервера автоматизации позволяют при вызове методов опускать параметры, принимая значения по умолчанию. Например:

     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');

Параметры для вызова метода автоматизации могут иметь типы: integer, real, string, Boolean и variant. Параметр передается по ссылке, в том случае, если выражение параметра состоит только из переменной или ссылки на переменную типа Byte, Smallint, Integer, Single, Double, Currency, System.TDateTime, AnsiString, WordBool или Variant. Если выражение не возвращает значение перечисленных типов или если это не только переменная, параметр передается по значению. Передача параметра по ссылке методу, принимающего параметр-значение, приводит к тому, что COM получает значение из ссылочного параметра. Передача параметра по значению в метод, принимающий ссылочный параметр, вызывает ошибку.

Двойные интерфейсы

Двойной интерфейс – это интерфейс, поддерживающий через автоматизацию связывание как во время компиляции, так и связывание времени выполнения. Двойные интерфейсы должны наследоваться от IDispatch.

Все методы двойного интерфейса (за исключением наследуемых от IInterface и IDispatch) должны использовать конвенцию safecall, а их параметры и результат должны иметь автоматизируемые типы (Byte, Currency, Real, Double, Real48, Integer, Single, Smallint, AnsiString, ShortString, System/TDateTime, Variant, OleVariant и WordBool.)