Anatomie einer IDL-Datei

Diese Beispiel-IDL-Dateien veranschaulichen die grundlegenden Konstrukte der Schnittstellendefinition. Speicherzuweisung, benutzerdefiniertes Marshalling und asynchrones Messaging sind nur einige der Features, die Sie in einer benutzerdefinierten COM-Schnittstelle implementieren können. MIDL-Attribute werden zum Definieren von COM-Schnittstellen verwendet. Weitere Informationen zum Implementieren von Schnittstellen und Typbibliotheken, einschließlich einer Zusammenfassung von MIDL-Attributen, finden Sie unter Schnittstellendefinitionen und Typbibliotheken im MIDL-Programmierhandbuch und -Referenz. Eine vollständige Referenz aller MIDL-Attribute, Schlüsselwörter und Direktiven finden Sie in der MIDL Language Reference.

Example.idl

Die folgende BEISPIEL-IDL-Datei definiert zwei COM-Schnittstellen. Aus dieser IDL-Datei generieren Midl.exe Proxy-/Stub- und Marshallingcode- und Headerdateien. Eine Zeilen-nach-Zeilen-Dissection folgt dem Beispiel.

//
// Example.idl 
//
import "mydefs.h","unknwn.idl"; 
[
object,
uuid(a03d1420-b1ec-11d0-8c3a-00c04fc31d2f),
] interface IFace1 : IUnknown
{
HRESULT MethodA([in] short Bread, [out] BKFST * pBToast);
HRESULT MethodB([in, out] BKFST * pBPoptart);
};
 
[
object,
uuid(a03d1421-b1ec-11d0-8c3a-00c04fc31d2f),
pointer_default(unique)
] interface IFace2 : IUnknown
{
HRESULT MethodC([in] long Max,
                [in, max_is(Max)] BkfstStuff[ ],
                [out] long * pSize,
                [out, size_is( , *pSize)] BKFST ** ppBKFST);
}; 
 

Die IDL-import Anweisung wird hier verwendet, um eine Headerdatei, Mydefs.h, die benutzerdefinierte Typen enthält, und Unknwn.idl, die die Definition von IUnknownenthält, von der IFace1 und IFace2 abgeleitet sind.

Das -Objekt--Attribut identifiziert die Schnittstelle als Objektschnittstelle und weist den MIDL-Compiler an, Proxy-/Stubcode anstelle von RPC-Client- und Server-Stubs zu generieren. Objektschnittstellenmethoden müssen über einen Rückgabetyp von HRESULT-verfügen, damit der zugrunde liegende RPC-Mechanismus Fehler für Aufrufe melden kann, die aufgrund von Netzwerkproblemen nicht abgeschlossen werden können.

Das attribut uuid gibt den Schnittstellenbezeichner (IID) an. Jede Schnittstelle, Klasse und Typbibliothek muss mit einem eigenen eindeutigen Bezeichner identifiziert werden. Verwenden Sie das Hilfsprogramm Uuidgen.exe, um eine Reihe eindeutiger IDs für Ihre Schnittstellen und andere Komponenten zu generieren.

Die Schnittstelle Schlüsselwort definiert den Schnittstellennamen. Alle Objektschnittstellen müssen direkt oder indirekt von IUnknownabgeleitet werden.

Der in Richtungsparameter gibt einen Parameter an, der nur vom Aufrufer festgelegt wird. Der Parameter gibt Daten an, die an den Aufrufer übergeben werden. Wenn Sie beide Richtungsattribute für einen Parameter verwenden, wird angegeben, dass der Parameter sowohl zum Senden von Daten an die Methode als auch zum Zurückgeben von Daten an den Aufrufer verwendet wird.

Das attribut pointer_default gibt den Standardzeigertyp (eindeutigen, refoder ptr) für alle Zeiger mit Ausnahme der in Parameterlisten enthaltenen Zeiger an. Wenn kein Standardtyp angegeben ist, geht MIDL davon aus, dass einzelne Zeiger eindeutigensind. Wenn Sie jedoch über mehrere Zeigerebenen verfügen, müssen Sie explizit einen Standardzeigertyp angeben, auch wenn der Standardtyp eindeutigensein soll.

Im vorherigen Beispiel ist das Array BkfstStuff[ ] ein konformes Array, dessen Größe zur Laufzeit bestimmt wird. Das attribut max_is gibt die Variable an, die den Maximalwert für den Arrayindex enthält.

Das attribut size_is wird auch verwendet, um die Größe eines Arrays oder, wie im vorherigen Beispiel, mehrere Ebenen von Zeigern anzugeben. Im Beispiel kann der Aufruf erfolgen, ohne vorher zu wissen, wie viele Daten zurückgegeben werden.

Example2.idl

Das folgende IDL-Beispiel (das die im vorherigen IDL-Beispiel beschriebenen Schnittstellen wiederverwendet) zeigt die verschiedenen Möglichkeiten zum Generieren von Typbibliotheksinformationen für Schnittstellen.

//
// Example2.idl
//

import "example.idl","oaidl.idl"; 

[
uuid(a03d1422-b1ec-11d0-8c3a-00c04fc31d2f),
helpstring("IFace3 interface"),
pointer_default(unique);
dual,
oleautomation
] 
interface IFace3 : IDispatch
{
   HRESULT MethodD([in] BSTR OrderIn,
                   [out, retval] * pTakeOut);
}; //end IFace3 def

[
uuid(a03d1423-b1ec-11d0-8c3a-00c04fc31d2f),
version(1.0),
helpstring("Example Type Library"),
] library ExampleLib
{
  importlib("stdole32.tlb");
  interface IFace3;
  [
  uuid(a03d1424-b1ec-11d0-8c3a-00c04fc31d2f),
  helpstring("Breakfast Component Class")
  ] coclass BkfstComponent
    {
    [default]interface IFace1;
    interfaceIFace2
    }; //end coclass def

[
uuid(a03d1424-b1ec-11d0-8c3a-00c04fc31d2f),
helpstring("IFace4 interface"),
pointer_default(unique);
dual,
oleautomation
] 
interface IFace4 : IDispatch
{
[propput] HRESULT MethodD([in] BSTR OrderIn);
[propget] HRESULT MethodE([out, retval] * pTakeOut);
}; //end IFace4 def
 
}; //end library def
 

Das Attributs "helpstring" ist optional; Sie verwenden es, um das Objekt kurz zu beschreiben oder eine Statuszeile anzugeben. Diese Hilfezeichenfolgen sind in einem Objektbrowser lesbar, z. B. die mit Microsoft Visual Basic bereitgestellte.

Das Dual--Attribut für IFace3 erstellt eine Schnittstelle, die sowohl eine Dispatch-Schnittstelle als auch eine COM-Schnittstelle ist. Da sie von IDispatch-abgeleitet wird, unterstützt eine duale Schnittstelle die Automatisierung, was das oleautomation-attribut angibt. IFace3 importiert Oaidl.idl, um die Definition von IDispatch-zu erhalten.

Die Library-Anweisung definiert die ExampleLib-Typbibliothek, die über eigene uuid-, Helpstring-und Version Attribute verfügt.

Innerhalb der Typbibliotheksdefinition bringt die importlib-Direktive eine kompilierte Typbibliothek ein. Alle Typbibliotheksdefinitionen sollten die in Stdole32.tlb definierte Basistypbibliothek enthalten.

Diese Typbibliotheksdefinition veranschaulicht drei verschiedene Methoden zum Einschließen von Schnittstellen in die Typbibliothek. IFace3 wird lediglich in der Bibliotheksanweisung enthalten.

Die coclass-Anweisung definiert eine völlig neue Komponentenklasse BkfstComponent, die zwei zuvor definierte Schnittstellen enthält: IFace1 und IFace2. Das Standardattribute bezeichnet IFace1 als Standardschnittstelle.

IFace4 wird in der Bibliotheksanweisung beschrieben. Das propput Attribut für MethodD gibt an, dass die Methode eine Set-Aktion für eine Eigenschaft mit demselben Namen ausführt. Das propget Attribut gibt an, dass die Methode Informationen aus einer Eigenschaft mit demselben Namen wie die Methode abruft. Das attribut "retval in MethodD" bezeichnet einen Ausgabeparameter, der den Rückgabewert der Funktion enthält.