Objets automation (Win32 seulement)
Remonter à Interfaces d'objets - Index
Un objet dont la classe implémente l'interface IDispatch (déclarée dans l'unité System) est appelé un objet automation.
Utilisez des variants pour accéder aux objets automation. Quand un variant référence un objet automation, vous pouvez appeler les méthodes de l'objet et lire ou modifier ses propriétés via le variant. Pour ce faire, vous devez inclure ComObj dans la clause uses de votre unité, de votre programme ou de votre bibliothèque.
Sommaire
Types interface de répartition
Les types interface de répartition définissent les méthodes et propriétés qu'un objet automation implémente via IDispatch. Les appels à une interface de répartition sont routés à l'exécution par la méthode Invoke de IDispatch. Une classe ne peut pas implémenter une interface de répartition.
La déclaration d'une interface de répartition a la forme suivante :
type InterfaceName = dispinterface
['{GUID}']
// …
end;
où
['{GUID}']
est facultatif et memberList est constitué de déclarations de propriétés et de méthodes. La déclaration d'une interface de répartition est semblable à celle d'une interface normale, mais elle ne peut pas spécifier d'ancêtre. Par exemple,
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;
Méthodes des interfaces de répartition
Les méthodes des interfaces de répartition sont le prototype d'appels de la méthode Invoke de l'implémentation IDispatch sous-jacente. Pour spécifier l'identificateur de répartition automation d'une méthode, utilisez la directive dispid dans sa déclaration en la faisant suivre d'une constante entière ; la spécification d'un identificateur déjà utilisé provoque une erreur.
Une méthode déclarée dans une interface de répartition ne peut contenir d'autres directives que dispid. Le type des paramètres et du résultat doit être un type automatisable : Byte, Currency, Real, Double, Longint, Integer, Single, Smallint, AnsiString, WideString, Borland.Delphi.System.TDateTime, Variant, OleVariant, WordBool ou tout type interface.
Propriétés des interfaces de répartition
Les propriétés des interfaces de répartition ne doivent pas indiquer de spécificateurs d'accès. Elles peuvent être déclarées comme read only ou write only. Pour spécifier l'identificateur de répartition d'une propriété, spécifiez dans la déclaration de la propriété la directive dispid suivie d'une constante entière. La spécification d'un identificateur déjà utilisé provoque une erreur. Les propriétés tableau peuvent être déclarées comme default. Toutes les autres directives sont interdites dans la déclaration des propriétés des interfaces de répartition.
Accès aux objets automation
Les appels des méthodes automation sont reliés uniquement à l'exécution et ne nécessitent pas de déclaration de méthode préalable. La validité de ces appels n'est donc pas vérifiée à la compilation.
L'exemple suivant illustre l'utilisation d'appels de méthodes automation. La fonction CreateOleObject (définie dans ComObj) renvoie une référence IDispatch à un objet automation compatible pour l'assignation avec le 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;
Il est possible de transmettre des paramètres de type interface aux méthodes automation.
Les tableaux variant dont le type d'élément est varByte constituent le meilleur moyen de transmettre des données binaires entre un contrôleur et un serveur automation. De tels tableaux ne peuvent être sujets à des conversions de données, et ils peuvent être facilement accédés en utilisant les routines VarArrayLock et VarArrayUnlock.
Syntaxe des appels de méthode d'objet automation
La syntaxe de l'appel d'une méthode d'un objet automation ou de l'accès à l'une de ses propriétés est similaire à la syntaxe normale d'un appel de méthode ou de l'accès à une propriété. Cependant, les appels de méthodes peuvent utiliser des paramètres par position et des paramètres nommés. Certains serveurs automation ne prennent pas en charge les paramètres nommés.
Un paramètre par position est simplement une expression. Un paramètre nommé est constitué d'un identificateur de paramètre suivi du symbole := et d'une expression. Dans un appel de méthode, les paramètres par position doivent précéder les paramètres nommés. Les paramètres nommés peuvent être spécifiés dans un ordre quelconque.
Certains serveurs automation vous autorisent à omettre des paramètres dans un appel de méthode en utilisant alors des valeurs par défaut. Par exemple,
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');
Les paramètres d'appel des méthodes automation peuvent être de type entier, réel, chaîne, booléen ou variant. Un paramètre est transmis par référence si l'expression du paramètre est constituée uniquement d'une référence de variable et si la référence de variable est de type Byte, Smallint, Integer, Single, Double, Currency, System.TDateTime, AnsiString, WordBool ou Variant. Si l'expression n'est pas de l'un de ces types ou si elle n'est pas composée uniquement d'une variable, le paramètre est transmis par valeur. Le transfert d'un paramètre par adresse à une méthode qui attend un paramètre par valeur oblige COM à extraire la valeur du paramètre par adresse. Le transfert d'un paramètre par valeur à une méthode qui attend un paramètre par adresse déclenche une erreur.
Interfaces doubles
Une interface double est une interface qui gère à la fois la liaison à la compilation et la liaison à l'exécution en utilisant l'automation. Les interfaces doubles doivent dériver de IDispatch.
Toutes les méthodes d'une interface double (à l'exception de celles héritées de IInterface et de IDispatch) doivent utiliser la convention safecall et le type du résultat et des paramètres doit être automatisable. Les types automatisables sont Byte, Currency, Real, Double, Real48, Integer, Single, Smallint, AnsiString, ShortString, System.TDateTime, Variant, OleVariant et WordBool.)