Anatomi för en IDL-fil

De här IDL-exempelfilerna visar de grundläggande konstruktionerna av gränssnittsdefinitionen. Minnesallokering, anpassad marskalkering och asynkrona meddelanden är bara några av de funktioner som du kan implementera i ett anpassat COM-gränssnitt. MIDL-attribut används för att definiera COM-gränssnitt. Mer information om hur du implementerar gränssnitt och typbibliotek, inklusive en sammanfattning av MIDL-attribut, finns i Gränssnittsdefinitioner och typbibliotek i MIDL-programmerarens guide och referens. En fullständig referens för alla MIDL-attribut, nyckelord och direktiv finns i MIDL Language Reference.

Example.idl

I följande exempel-IDL-fil definieras två COM-gränssnitt. Från den här IDL-filen genererar Midl.exe proxy-/stub- och marshaling-kod- och huvudfiler. En rad-för-rad-dissekering följer exemplet.

//
// 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);
}; 
 

IDL-importera-instruktion används här för att ta in en rubrikfil, Mydefs.h, som innehåller användardefinierade typer, och Unknwn.idl, som innehåller definitionen av IUnknown, från vilken IFace1 och IFace2 härleds.

Attributet objekt identifierar gränssnittet som ett objektgränssnitt och instruerar MIDL-kompilatorn att generera proxy-/stub-kod i stället för RPC-klient- och serverstubbar. Objektgränssnittsmetoder måste ha en returtyp av HRESULT-, för att den underliggande RPC-mekanismen ska kunna rapportera fel för anrop som inte kan slutföras på grund av nätverksproblem.

Attributet uuid anger gränssnittsidentifieraren (IID). Varje gränssnitt, klass och typbibliotek måste identifieras med sin egen unika identifierare. Använd verktyget Uuidgen.exe för att generera en uppsättning unika ID:er för dina gränssnitt och andra komponenter.

Nyckelordet gränssnitt definierar gränssnittsnamnet. Alla objektgränssnitt måste direkt eller indirekt härledas från IUnknown.

Den i riktningsparameter anger en parameter som endast anges av anroparen. Parametern ut anger data som skickas tillbaka till anroparen. Med båda riktningsattributen på en parameter anges att parametern används både för att skicka data till metoden och för att skicka data tillbaka till anroparen.

Attributet pointer_default anger standardpekartypen (unik, refeller ptr) för alla pekare förutom de som ingår i parameterlistorna. Om ingen standardtyp anges förutsätter MIDL att enskilda pekare är unika. Men när du har flera pekarnivåer måste du uttryckligen ange en standardpekartyp, även om du vill att standardtypen ska vara unik.

I föregående exempel är matrisen BkfstStuff[ ] en överensstämmande matris, vars storlek bestäms vid körning. Attributet max_is anger variabeln som innehåller det maximala värdet för matrisindexet.

Attributet size_is används också för att ange storleken på en matris eller, som i föregående exempel, flera pekarnivåer. I exemplet kan anropet göras utan att du i förväg vet hur mycket data som ska returneras.

Exempel2.idl

Följande IDL-exempel (som återanvänder de gränssnitt som beskrivs i föregående IDL-exempel) visar de olika sätten att generera typbiblioteksinformation för gränssnitt.

//
// 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
 

Attributet helpstring är valfritt. du använder det för att kortfattat beskriva objektet eller för att ange en statusrad. Dessa hjälpsträngar kan läsas med en objektwebbläsare, till exempel den som tillhandahålls med Microsoft Visual Basic.

Attributet dubbla i IFace3 skapar ett gränssnitt som både är ett dispatch-gränssnitt och ett COM-gränssnitt. Eftersom det härleds från IDispatchstöder ett dubbelt gränssnitt Automation, vilket är vad attributet oleautomation anger. IFace3 importerar Oaidl.idl för att få definitionen av IDispatch.

-biblioteket-instruktionen definierar exempelbiblioteket av typen ExampleLib, som har egna uuid, helpstringoch version attribut.

I typbiblioteksdefinitionen innehåller importlib--direktivet ett kompilerat typbibliotek. Alla typbiblioteksdefinitioner ska innehålla bastypbiblioteket som definierats i Stdole32.tlb.

Den här typbiblioteksdefinitionen visar tre olika sätt att inkludera gränssnitt i typbiblioteket. IFace3 ingår bara genom att referera till det i biblioteksinstrukeringen.

Instruktionen coclass definierar en helt ny komponentklass, BkfstComponent, som innehåller två tidigare definierade gränssnitt, IFace1 och IFace2. Standardattributet anger IFace1 som standardgränssnitt.

IFace4 beskrivs i biblioteksuttryck. Attributet propput på MethodD anger att metoden utför en uppsättningsåtgärd på en egenskap med samma namn. Attributet propget anger att metoden hämtar information från en egenskap med samma namn som metoden. Attributet retval i MethodD anger en utdataparameter som innehåller funktionens returvärde.