Anatomía de un archivo IDL

Estos archivos IDL de ejemplo muestran las construcciones fundamentales de la definición de interfaz. La asignación de memoria, las referencias personalizadas y la mensajería asincrónica son solo algunas de las características que puede implementar en una interfaz COM personalizada. Los atributos MIDL se usan para definir interfaces COM. Para obtener más información sobre la implementación de interfaces y bibliotecas de tipos, incluido un resumen de los atributos MIDL, vea Interface Definitions and Type Libraries in the MIDL Programador's Guide and Reference. Para obtener una referencia completa de todos los atributos, palabras clave y directivas MIDL, vea el referencia del lenguaje MIDL.

Example.idl

El siguiente archivo IDL de ejemplo define dos interfaces COM. A partir de este archivo IDL, Midl.exe generará código proxy/código auxiliar y serialización de código y archivos de encabezado. Una disección de línea a línea sigue el ejemplo.

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

Aquí se usa la instrucción IDL import para incluir un archivo de encabezado, Mydefs.h, que contiene tipos definidos por el usuario y Unknwn.idl, que contiene la definición de IUnknown, desde el que se deriva IFace1 e IFace2.

El objeto atributo identifica la interfaz como una interfaz de objeto y indica al compilador MIDL que genere código proxy/código auxiliar en lugar de código auxiliar de servidor y cliente RPC. Los métodos de interfaz de objeto deben tener un tipo de valor devuelto de HRESULT, para permitir que el mecanismo RPC subyacente notifique los errores de las llamadas que no se completan debido a problemas de red.

El atributo uuid especifica el identificador de interfaz (IID). Cada interfaz, clase y biblioteca de tipos debe identificarse con su propio identificador único. Use la utilidad Uuidgen.exe para generar un conjunto de identificadores únicos para las interfaces y otros componentes.

La palabra clave interfaz define el nombre de la interfaz. Todas las interfaces de objeto deben derivar, directa o indirectamente, de IUnknown.

El en parámetro direccional especifica un parámetro que solo establece el autor de la llamada. El parámetro especifica los datos que se devuelven al autor de la llamada. El uso de ambos atributos direccionales en un parámetro especifica que el parámetro se usa tanto para enviar datos al método como para devolver datos al autor de la llamada.

El atributo pointer_default especifica el tipo de puntero predeterminado (único, ref, o ptr) para todos los punteros excepto los incluidos en listas de parámetros. Si no se especifica ningún tipo predeterminado, MIDL supone que los punteros únicos son únicos. Sin embargo, cuando tenga varios niveles de punteros, debe especificar explícitamente un tipo de puntero predeterminado, incluso si desea que el tipo predeterminado sea único.

En el ejemplo anterior, la matriz BkfstStuff[ ] es un matriz conforme, cuyo tamaño se determina en tiempo de ejecución. El atributo max_is especifica la variable que contiene el valor máximo para el índice de matriz.

El atributo size_is también se usa para especificar el tamaño de una matriz o, como en el ejemplo anterior, varios niveles de punteros. En el ejemplo, la llamada se puede realizar sin saber con antelación cuántos datos se devolverán.

Example2.idl

En el siguiente ejemplo de IDL (que reutiliza las interfaces descritas en el ejemplo anterior de IDL), se muestran las distintas formas de generar información de biblioteca de tipos para interfaces.

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

El atributo helpstring es opcional; se usa para describir brevemente el objeto o para proporcionar una línea de estado. Estas cadenas de ayuda son legibles con un explorador de objetos como el proporcionado con Microsoft Visual Basic.

El atributo dual en IFace3 crea una interfaz que es una interfaz de distribución y una interfaz COM. Dado que se deriva de IDispatch, una interfaz dual admite Automation, que es lo que especifica el atributooleautomation. IFace3 importa Oaidl.idl para obtener la definición de IDispatch.

La instrucciónbiblioteca dedefine la biblioteca de tipos ExampleLib, que tiene sus propios atributos uuid, helpstringy versión.

Dentro de la definición de la biblioteca de tipos, la directiva importlib incluye una biblioteca de tipos compilada. Todas las definiciones de biblioteca de tipos deben incluir la biblioteca de tipos base definida en Stdole32.tlb.

Esta definición de biblioteca de tipos muestra tres maneras diferentes de incluir interfaces en la biblioteca de tipos. IFace3 se incluye simplemente haciendo referencia a ella dentro de la instrucción library.

La instrucción coclase define una clase de componente completamente nueva, BkfstComponent, que incluye dos interfaces definidas anteriormente, IFace1 e IFace2. El atributo predeterminado designa IFace1 como la interfaz predeterminada.

IFace4 se describe dentro de la instrucción library. El atributo propput en MethodD indica que el método realiza una acción de conjunto en una propiedad del mismo nombre. El atributo propget indica que el método recupera información de una propiedad del mismo nombre que el método. El atributo retval de MethodD designa un parámetro de salida que contiene el valor devuelto de la función.