IdL-fájl anatómiája

Ezek a példa IDL-fájlok a felületdefiníció alapvető szerkezeteit mutatják be. A memóriafoglalás, az egyéni marshaling és az aszinkron üzenetkezelés csak néhány az egyéni COM-felületen implementálható funkciók közül. A MIDL-attribútumok COM-felületek definiálására szolgálnak. Az interfészek és típuskódtárak implementálásával kapcsolatos további információkért, beleértve a MIDL-attribútumok összegzését, tekintse meg felületdefiníciókat és típuskódtárakat a MIDL programozói útmutatójában és referenciájában. Az összes MIDL-attribútumra, kulcsszóra és irányelvre vonatkozó teljes hivatkozásért tekintse meg a MIDL nyelvi referencia.

Example.idl

Az alábbi PÉLDA IDL-fájl két COM-felületet határoz meg. Ebből az IDL-fájlból Midl.exe proxy-/csonk- és marshaling kódot és fejlécfájlokat hoz létre. Egy sorról sorra történő boncció követi a példát.

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

Az IDL importálási utasítással be lehet állítani egy mydefs.h fejlécfájlt, amely felhasználó által definiált típusokat tartalmaz, és az Unknwn.idl, amely tartalmazza IUnknowndefinícióját, amelyből az IFace1 és az IFace2 származik.

Az objektum attribútum objektum-interfészként azonosítja az interfészt, és arra utasítja a MIDL-fordítót, hogy RPC-ügyfél és kiszolgálócsomó helyett proxy-/stub kódot hozzon létre. Az objektumillesztő metódusoknak HRESULTvisszatérési típussal kell rendelkezniük, hogy a mögöttes RPC-mechanizmus jelentse a hálózati problémák miatt sikertelen hívások hibáit.

Az uuid attribútum adja meg a felület azonosítóját (IID). Minden illesztő-, osztály- és típustárat saját egyedi azonosítóval kell azonosítani. A segédprogram Uuidgen.exe segítségével egyedi azonosítókat hozhat létre az interfészekhez és más összetevőkhöz.

A felület kulcsszó határozza meg a felület nevét. Minden objektumillesztőnek közvetlenül vagy közvetve IUnknownkell származnia.

Azirányparaméterolyan paramétert határoz meg, amelyet csak a hívó állít be. A paraméter a hívónak visszaadott adatokat adja meg. Ha mindkét irányattribútumot egy paraméteren használja, az azt határozza meg, hogy a paraméter egyszerre küld adatokat a metódusnak, és az adatokat visszaadhatja a hívónak.

A pointer_default attribútum az alapértelmezett mutatótípust (egyedi, refvagy ptr) adja meg az összes mutatóhoz, kivéve a paraméterlistákban szereplőket. Ha nincs megadva alapértelmezett típus, a MIDL feltételezi, hogy az egyetlen mutató egyedi. Ha azonban több mutatószinttel rendelkezik, explicit módon meg kell adnia egy alapértelmezett mutatótípust, még akkor is, ha azt szeretné, hogy az alapértelmezett típus egyedi.

Az előző példában a BkfstStuff[] tömb egy megfelelő tömb, amelynek méretét futásidőben határozzuk meg. A max_is attribútum határozza meg azt a változót, amely a tömbindex maximális értékét tartalmazza.

A size_is attribútum egy tömb méretének megadására is szolgál, vagy az előző példához hasonlóan több mutatószintre is. A példában a hívás anélkül indítható el, hogy előre tudná, mennyi adatot ad vissza.

Example2.idl

Az alábbi IDL-példa (amely újra felhasználja az előző IDL-példában leírt felületeket) a felületek típustár-információinak létrehozásának különböző módjait mutatja be.

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

A súgósztring attribútum nem kötelező; segítségével röviden ismertetheti az objektumot, vagy megadhat egy állapotsort. Ezek a súgósztringek egy objektumböngészővel olvashatók, például a Microsoft Visual Basic szolgáltatásban.

Az IFace3 kettős attribútuma egy olyan felületet hoz létre, amely egyszerre küldőfelület és COM-felület. Mivel IDispatchszármazik, a kettős interfész támogatja az Automationt, amit az oleautomation attribútuma határoz meg. Az IFace3 importálja az Oaidl.idl-t az IDispatchdefiníciójának lekéréséhez.

A kódtár utasítása határozza meg az ExampleLib típusú kódtárat, amely saját uuid, súgószúrásiés verzió attribútumokkal rendelkezik.

A típustár definíciójában az importlib irányelv egy lefordított típustárat hoz létre. Minden típustár-definíciónak be kell állítania a Stdole32.tlb-ben definiált alaptípustárat.

Ez a típustár-definíció három különböző módszert mutat be a felületek típustárba való beépítésére. Az IFace3 csak a kódtár-nyilatkozatban való hivatkozással érhető el.

A coclass utasítás egy teljesen új, BkfstComponent összetevőosztályt határoz meg, amely két korábban definiált felületet tartalmaz, az IFace1-et és az IFace2-t. Az alapértelmezett attribútum az IFace1-et jelöli meg alapértelmezett felületként.

Az IFace4-et a kódtár-utasítás ismerteti. A MethodD propput attribútum azt jelzi, hogy a metódus egy megadott műveletet hajt végre egy azonos nevű tulajdonságon. A propget attribútum azt jelzi, hogy a metódus a metódussal azonos nevű tulajdonságból kér le adatokat. A MethodD újraértékelési attribútuma a függvény visszatérési értékét tartalmazó kimeneti paramétert jelöl ki.