Anatomi File IDL
Contoh file IDL ini menunjukkan konstruksi dasar definisi antarmuka. Alokasi memori, marshaling kustom, dan olahpesan asinkron hanyalah beberapa fitur yang dapat Anda terapkan dalam antarmuka COM kustom. Atribut MIDL digunakan untuk menentukan antarmuka COM. Untuk informasi selengkapnya tentang menerapkan antarmuka dan jenis pustaka, termasuk ringkasan atribut MIDL, lihat Definisi Antarmuka dan Jenis Pustaka di Panduan dan Referensi Programmer MIDL. Untuk referensi lengkap semua atribut, kata kunci, dan arahan MIDL, lihat Referensi Bahasa MIDL.
Example.idl
Contoh file IDL berikut menentukan dua antarmuka COM. Dari file IDL ini, Midl.exe akan menghasilkan proxy/stub dan marshaling code dan file header. Pembagian baris demi baris mengikuti contoh.
//
// 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);
};
Pernyataan impor IDL digunakan di sini untuk membawa file header, Mydefs.h, yang berisi jenis yang ditentukan pengguna, dan Unknwn.idl, yang berisi definisi IUnknown, dari mana IFace1 dan IFace2 berasal.
Atribut objek mengidentifikasi antarmuka sebagai antarmuka objek dan memberi tahu pengkompilasi MIDL untuk menghasilkan kode proksi/stub alih-alih klien RPC dan stub server. Metode antarmuka objek harus memiliki jenis pengembalian HRESULT, untuk memungkinkan mekanisme RPC yang mendasar melaporkan kesalahan untuk panggilan yang gagal diselesaikan karena masalah jaringan.
Atribut uuid menentukan pengidentifikasi antarmuka (IID). Setiap antarmuka, kelas, dan pustaka jenis harus diidentifikasi dengan pengidentifikasi uniknya sendiri. Gunakan utilitas Uuidgen.exe untuk menghasilkan sekumpulan ID unik untuk antarmuka Anda dan komponen lainnya.
Kata kunci antarmuka menentukan nama antarmuka. Semua antarmuka objek harus berasal, secara langsung atau tidak langsung, dari IUnknown.
Parameter arah menentukan parameter yang hanya diatur oleh pemanggil. Parameter keluar menentukan data yang diteruskan kembali ke pemanggil. Menggunakan kedua atribut arah pada satu parameter menentukan bahwa parameter digunakan baik untuk mengirim data ke metode dan untuk meneruskan data kembali ke pemanggil.
Atribut pointer_default menentukan jenis penunjuk default (unik, ref, atau ptr) untuk semua pointer kecuali yang disertakan dalam daftar parameter. Jika tidak ada jenis default yang ditentukan, MIDL mengasumsikan bahwa penunjuk tunggal unik. Namun, ketika Anda memiliki beberapa tingkat penunjuk, Anda harus secara eksplisit menentukan jenis penunjuk default, bahkan jika Anda ingin jenis defaultnya unik.
Dalam contoh sebelumnya, array BkfstStuff[ ] adalah array yang sesuai, yang ukurannya ditentukan pada waktu proses. Atribut max_is menentukan variabel yang berisi nilai maksimum untuk indeks array.
Atribut size_is juga digunakan untuk menentukan ukuran array atau, seperti dalam contoh sebelumnya, beberapa tingkat pointer. Dalam contoh, panggilan dapat dilakukan tanpa mengetahui terlebih dahulu berapa banyak data yang akan dikembalikan.
Example2.idl
Contoh IDL berikut (yang menggunakan kembali antarmuka yang dijelaskan dalam contoh IDL sebelumnya) menunjukkan berbagai cara untuk menghasilkan informasi pustaka jenis untuk antarmuka.
//
// 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
Atribut helpstring bersifat opsional; Anda menggunakannya untuk menjelaskan objek secara singkat atau untuk menyediakan baris status. String bantuan ini dapat dibaca dengan browser objek seperti yang disediakan dengan Microsoft Visual Basic.
Atribut ganda pada IFace3 membuat antarmuka yang merupakan antarmuka pengiriman dan antarmuka COM. Karena berasal dari IDispatch, antarmuka ganda mendukung Automation, yang ditentukan atribut oleautomation. IFace3 mengimpor Oaidl.idl untuk mendapatkan definisi IDispatch.
Pernyataan pustaka mendefinisikan pustaka jenis ExampleLib, yang memiliki atribut uuid, helpstring, dan versinya sendiri.
Dalam definisi pustaka jenis, direktif importlib membawa pustaka jenis yang dikompilasi. Semua definisi pustaka jenis harus membawa pustaka jenis dasar yang ditentukan dalam Stdole32.tlb.
Definisi pustaka jenis ini menunjukkan tiga cara berbeda untuk menyertakan antarmuka dalam pustaka jenis. IFace3 hanya disertakan dengan merujuknya dalam pernyataan pustaka.
Pernyataan kolase mendefinisikan kelas komponen yang sama sekali baru, BkfstComponent, yang mencakup dua antarmuka yang ditentukan sebelumnya, IFace1 dan IFace2. Atribut default menunjuk IFace1 sebagai antarmuka default.
IFace4 dijelaskan dalam pernyataan pustaka. Atribut propput pada MethodD menunjukkan bahwa metode melakukan tindakan yang ditetapkan pada properti dengan nama yang sama. Atribut propget menunjukkan bahwa metode mengambil informasi dari properti dengan nama yang sama dengan metode . Atribut retval di MethodD menunjuk parameter output yang berisi nilai pengembalian fungsi.