Antarmuka C++ Model Data Debugger
Topik ini menyediakan dan gambaran umum tentang cara menggunakan Antarmuka C++ Model Data Debugger untuk memperluas dan menyesuaikan kemampuan debugger.
Antarmuka Host C++ Model Data Debugger
The Debugger Data Model Host
Model Data Debugger dirancang untuk menjadi sistem komponen yang dapat dihosting dalam berbagai konteks yang berbeda. Biasanya, Model Data dihosting dalam konteks aplikasi debugger. Untuk menjadi host model data, sejumlah antarmuka perlu diimplementasikan untuk mengekspos aspek inti debugger: penargetannya, ruang memorinya, evaluatornya, sistem simbolis dan jenisnya, dll... Meskipun antarmuka ini diimplementasikan oleh aplikasi apa pun yang ingin menghosting model data, antarmuka tersebut dikonsumsi oleh model data inti serta ekstensi apa pun yang interoperabilitas dengan model data.
Kumpulan antarmuka inti adalah:
| Nama Antarmuka | Deskripsi |
|---|---|
| IDebugHost | Antarmuka inti ke host debug. |
| IDebugHostStatus | Antarmuka yang memungkinkan klien untuk mengkueri status host. |
| IDebugHostContext | Abstraksi konteks dalam host (misalnya: target tertentu, proses tertentu, ruang alamat tertentu, dll...) |
| IDebugHostErrorSink | Antarmuka yang diimplementasikan oleh penelepon untuk menerima kesalahan dari bagian tertentu dari host dan model data |
| IDebugHostEvaluator / IDebugHostEvaluator2 | Evaluator ekspresi host debug. |
| IDebugHostExtensibility | Antarmuka untuk memperluas kemampuan host atau bagiannya (seperti evaluator ekspresi). |
Sistem jenis dan antarmuka simbolis adalah:
| InterfaceName | Deskripsi |
|---|---|
| IDebugHostSymbols | Antarmuka inti yang menyediakan akses ke dan resolusi simbol |
| IDebugHostSymbol / IDebugHostSymbol2 | Mewakili simbol tunggal dalam bentuk apa pun. Simbol tertentu adalah turunan dari antarmuka ini. |
| IDebugHostModule | Mewakili modul yang dimuat dalam proses. Ini semacam simbol. |
| IDebugHostType / IDebugHostType2 | Mewakili jenis asli/bahasa. |
| IDebugHostConstant | Mewakili konstanta dalam informasi simbolis (misalnya: argumen templat non-jenis di C++) |
| IDebugHostField | Mewakili bidang dalam struktur atau kelas. |
| IDebugHostData | Mewakili data dalam modul (apakah ini dalam struktur atau kelas itu akan menjadi IDebugHostField) |
| IDebugHostBaseClass | Mewakili kelas dasar. |
| IDebugHostPublic | Mewakili simbol dalam tabel publik PDB. Ini tidak memiliki informasi jenis yang terkait dengannya. Ini adalah nama dan alamat. |
| IDebugHostModuleSignature | Mewakili tanda tangan modul -- definisi yang akan cocok dengan sekumpulan modul berdasarkan nama dan/atau versi |
| IDebugHostTypeSignature | Mewakili tanda tangan jenis -- definisi yang akan cocok dengan sekumpulan jenis menurut modul dan/atau nama |
Antarmuka Host Inti: IDebugHost
Antarmuka IDebugHost adalah antarmuka inti dari host model data apa pun. Ini didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHost, IUnknown)
{
STDMETHOD(GetHostDefinedInterface)(_COM_Outptr_ IUnknown** hostUnk) PURE;
STDMETHOD(GetCurrentContext)(_COM_Outptr_ IDebugHostContext** context) PURE;
STDMETHOD(GetDefaultMetadata)(_COM_Outptr_ IKeyStore** defaultMetadataStore) PURE;
}
Metode GetHostDefinedInterface mengembalikan antarmuka privat utama host, jika ada untuk host yang diberikan. Untuk Alat Debugging untuk Windows, antarmuka yang dikembalikan di sini adalah IDebugClient (ditransmisikan ke IUnknown).
Metode GetCurrentContext mengembalikan antarmuka yang mewakili status host debugger saat ini. Arti pasti dari ini diserahkan ke host, tetapi biasanya mencakup hal-hal seperti sesi, proses, dan ruang alamat yang aktif di antarmuka pengguna host debug. Objek konteks yang dikembalikan sebagian besar buram bagi pemanggil tetapi merupakan objek penting untuk diteruskan di antara panggilan ke host debug. Ketika penelepon, misalnya, membaca memori, penting untuk mengetahui proses dan ruang alamat tempat memori dibaca. Gagasan itu dienkapsulasi dalam gagasan objek konteks yang dikembalikan dari metode ini.
Metode GetDefaultMetadata mengembalikan penyimpanan metadata default yang dapat digunakan untuk operasi tertentu (misalnya: konversi string) ketika tidak ada metadata eksplisit yang telah dilewatkan. Ini memungkinkan host debug memiliki kontrol atas cara beberapa data disajikan. Misalnya, metadata default dapat menyertakan kunci PreferredRadix, memungkinkan host untuk menunjukkan apakah ordinal harus ditampilkan dalam desimal atau heksadesimal jika tidak ditentukan sebaliknya.
Perhatikan bahwa nilai properti pada penyimpanan metadata default harus diselesaikan secara manual dan harus meneruskan objek yang metadata defaultnya sedang dikueri. Metode GetKey harus digunakan sebagai pengganti GetKeyValue.
Antarmuka Status: IDebugHostStatus
Antarmuka IDebugHostStatus memungkinkan klien model data atau host debug untuk menanyakan aspek tertentu dari status host debug. Antarmuka didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostStatus, IUnknown)
{
STDMETHOD(PollUserInterrupt)(_Out_ bool* interruptRequested) PURE;
}
Metode PollUserInterrupt digunakan untuk menanyakan apakah pengguna host debug telah meminta gangguan operasi saat ini. Pengakses properti dalam model data dapat, misalnya, memanggil kode arbitrer (misalnya: metode JavaScript). Kode tersebut mungkin memakan waktu sesegan-segan. Untuk menjaga host debug tetap responsif, kode apa pun yang mungkin memakan waktu sewenang-wenang harus memeriksa permintaan interupsi melalui panggilan metode ini. Jika nilai interruptRequested kembali sebagai true, pemanggil harus segera membatalkan dan mengembalikan hasil E_ABORT.
Antarmuka Konteks: IDebugHostContext
Konteks adalah salah satu aspek terpenting dari model data dan host debug yang mendasar. Ketika Anda memegang objek, penting untuk dapat mengetahui dari mana objek berasal -- proses apa itu, ruang alamat apa yang terkait dengannya. Mengetahui informasi ini memungkinkan interpretasi yang benar dari hal-hal seperti nilai penunjuk. Objek jenis IDebugHostContext harus diteruskan ke banyak metode pada host debug. Antarmuka ini dapat diperoleh dengan sejumlah cara:
- Dengan mendapatkan konteks debugger saat ini: memanggil metode GetCurrentContext dari IDebugHost
- Dengan mendapatkan konteks objek: memanggil metode GetContext dari IModelObject
- Dengan mendapatkan konteks simbol: memanggil metode GetContext dari IDebugHostSymbol
Selain itu, ada dua nilai yang memiliki arti khusus dalam konteks antarmuka IDebugHostContext yang dikembalikan dari atau diteruskan ke model data atau metode host debug:
nullptr: indikasi bahwa tidak ada konteks. Ini sangat valid bagi beberapa objek untuk tidak memiliki konteks. Objek Debugger di namespace layanan akar model data tidak merujuk apa pun dalam proses atau ruang alamat tertentu. Ini tidak memiliki konteks.
USE_CURRENT_HOST_CONTEXT: nilai sentinel yang menunjukkan bahwa seseorang harus menggunakan konteks UI host debug saat ini. Nilai ini tidak akan pernah dikembalikan dari host debug. Namun, ini dapat diteruskan ke metode host debug apa pun yang mengambil input IDebugHostContext sebagai pengganti secara eksplisit memanggil metode GetCurrentContext dari IDebugHost. Perhatikan bahwa secara eksplisit melewati USE_CURRENT_HOST_CONTEXT sering kali lebih berkinerja daripada secara eksplisit mendapatkan konteks saat ini.
Konteks konteks host sebagian besar buram bagi pemanggil. Satu-satunya operasi yang dapat dilakukan pemanggil di luar host debug inti adalah membandingkannya dengan konteks host lain.
Antarmuka IDebugHostContext didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostContext, IUnknown)
{
STDMETHOD(IsEqualTo)(_In_ IDebugHostContext *pContext, _Out_ bool *pIsEqual) PURE;
}
Metode IsEqualTo membandingkan konteks host dengan konteks host lain. Jika kedua konteks tersebut setara, indikasi ini dikembalikan. Perhatikan bahwa perbandingan ini bukan kesetaraan antarmuka. Ini membandingkan konten buram yang mendasar dari konteks itu sendiri.
Sink Kesalahan: IDebugHostErrorSink
IDebugHostErrorSink adalah sarana di mana klien dapat menerima pemberitahuan kesalahan yang terjadi selama operasi tertentu dan merutekan kesalahan tersebut jika diperlukan. Antarmuka didefinisikan sebagai berikut:
enum ErrorClass
{
ErrorClassWarning,
ErrorClassError
}
DECLARE_INTERFACE_(IDebugHostErrorSink, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrError, _In_ PCWSTR message) PURE;
}
Metode ReportError adalah panggilan balik pada sink kesalahan untuk memberi tahu bahwa kesalahan telah terjadi dan memungkinkan sink untuk merutekan kesalahan ke UI atau mekanisme apa pun yang sesuai.
Evaluator Host: IDebugHostEvaluator / IDebugHostEvaluator2
Salah satu fungsionalitas terpenting yang disediakan host debug kepada klien adalah akses ke evaluator ekspresi berbasis bahasanya. Antarmuka IDebugHostEvaluator dan IDebugHostEvaluator2 adalah sarana untuk mengakses fungsionalitas tersebut dari host debug.
Antarmuka didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostEvaluator2, IDebugHostEvaluator)
{
//
// IDebugHostEvaluator:
//
STDMETHOD(EvaluateExpression)(_In_ IDebugHostContext* context, _In_ PCWSTR expression, _In_opt_ IModelObject* bindingContext, _COM_Errorptr_ IModelObject** result, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(EvaluateExtendedExpression)(_In_ IDebugHostContext* context, _In_ PCWSTR expression, _In_opt_ IModelObject* bindingContext, _COM_Errorptr_ IModelObject** result, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
//
// IDebugHostEvaluator2:
//
STDMETHOD(AssignTo)(_In_ IModelObject* assignmentReference, _In_ IModelObject* assignmentValue, _COM_Errorptr_ IModelObject** assignmentResult, _COM_Outptr_opt_result_maybenull_ IKeyStore** assignmentMetadata) PURE;
}
Metode EvaluateExpression memungkinkan permintaan host debug untuk mengevaluasi ekspresi bahasa (misalnya: C++) dan mengembalikan nilai yang dihasilkan dari evaluasi ekspresi yang dikotak sebagai IModelObject. Varian khusus metode ini hanya memungkinkan konstruksi bahasa. Fungsionalitas tambahan apa pun yang disajikan dalam evaluator ekspresi host debug yang tidak ada dalam bahasa (misalnya: metode kueri LINQ) dinonaktifkan untuk evaluasi.
Metode EvaluateExtendedExpression mirip dengan metode EvaluateExpression kecuali bahwa metode tersebut kembali pada fungsionalitas non-bahasa tambahan yang dipilih host debug tertentu untuk ditambahkan ke evaluator ekspresinya. Untuk Alat Debugging untuk Windows, misalnya, ini memungkinkan jenis anonim, kueri LINQ, kualifikasi modul, penentu format, dan fungsi non-C/C++ lainnya.
IDebugHostEvaluator2
Metode AssignTo melakukan penugasan sesuai dengan semantik bahasa yang sedang di-debug.
Antarmuka Ekstensibilitas Host: IDebugHostExtensibility
Fungsionalitas tertentu dari host debug secara opsional tunduk pada ekstensibilitas. Ini dapat, misalnya, menyertakan evaluator ekspresi. Antarmuka IDebugHostExtensibility adalah sarana di mana titik ekstensibilitas ini diakses. Antarmuka didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostExtensibility, IUnknown)
{
STDMETHOD(CreateFunctionAlias)(_In_ PCWSTR aliasName, _In_ IModelObject *functionObject) PURE;
STDMETHOD(DestroyFunctionAlias)(_In_ PCWSTR aliasName) PURE;
}
Metode CreateFunctionAlias membuat "alias fungsi", "alias cepat" untuk metode yang diterapkan dalam beberapa ekstensi. Arti alias ini khusus untuk host. Ini dapat memperluas evaluator ekspresi host dengan fungsi atau mungkin melakukan sesuatu yang sama sekali berbeda.
Metode DestroyFunctionAlias membatalkan panggilan sebelumnya ke metode CreateFunctionAlias. Fungsi tidak akan lagi tersedia di bawah nama alias cepat.
Mengakses Model Data
Pertama dan terdepan, API ekstensibilitas model data dirancang untuk netral terhadap aplikasi (biasanya debugger) yang bertindak sebagai host model data. Secara teori, aplikasi apa pun dapat menghosting model data dengan menyediakan sekumpulan API host yang mengekspos sistem jenis target debug aplikasi dan sekumpulan objek yang diproyeksikan ke dalam namespace model data tentang target, proses, utas, dll... berada di target debug tersebut.
Meskipun API model data -- yang memulai IDataModel, IDebugHost, dan offshoot IModelObject -- dirancang agar portabel, mereka tidak menentukan apa itu "ekstensi debugger". Saat ini, komponen yang ingin memperluas Alat Debugging untuk Windows dan mesin yang disediakannya harus menulis ekstensi mesin untuk mendapatkan akses ke model data. Ekstensi mesin itu hanya perlu menjadi ekstensi mesin sebanyak yang merupakan mekanisme pemuatan dan bootstrapping untuk ekstensi. Dengan demikian, implementasi minimal akan memberikan:
- DebugExtensionInitialize: Metode yang menggunakan IDebugClient yang dibuat untuk mendapatkan akses ke model data dan menyiapkan manipulasi model objek.
- DebugExtensionUninitialize: Metode yang membatalkan manipulasi model objek yang dilakukan dalam DebugExtensionInitialize.
- DebugExtensionCanUnload: Metode yang mengembalikan apakah ekstensi dapat dibongkar. Jika masih ada objek COM langsung dalam ekstensi, itu harus menunjukkan ini. Ini adalah debugger yang setara dengan DLLCanUnloadNow COM. Jika ini mengembalikan indikasi S_FALSE ketidakmampuan untuk membongkar, debugger dapat meminta ini nanti untuk melihat apakah bongkar aman atau mungkin menginisialisasi ulang ekstensi dengan memanggil DebugExtensionInitialize lagi. Ekstensi harus disiapkan untuk menangani kedua jalur.
- DebugExtensionUnload: Metode yang melakukan pembersihan akhir yang diperlukan tepat sebelum DLL dibongkar
Antarmuka Penghubung: IHostDataModelAccess
Seperti disebutkan, ketika DebugExtensionInitialize dipanggil, ia membuat klien debug dan mendapatkan akses ke model data. Akses tersebut disediakan oleh antarmuka penghubung antara antarmuka IDebug* warisan Alat Debugging untuk Windows dan model data. Antarmuka jembatan ini adalah 'IHostDataModelAccess dan didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IHostDataModelAccess, IUnknown)
{
STDMETHOD(GetDataModel)(_COM_Outptr_ IDataModelManager** manager, _COM_Outptr_ IDebugHost** host) PURE;
}
Metode GetDataModel adalah metode pada antarmuka penghubung yang menyediakan akses ke kedua sisi model data: Host debug (tepi bawah debugger) dinyatakan oleh antarmuka IDebugHost yang dikembalikan Komponen utama model data -- manajer model data dinyatakan oleh antarmuka IDataModelManager yang dikembalikan
Antarmuka Sistem Model Data Debugger
The Data Model Host
Model Data Debugger dirancang untuk menjadi sistem komponen yang dapat dihosting dalam berbagai konteks yang berbeda. Biasanya, Model Data dihosting dalam konteks aplikasi debugger. Untuk menjadi host model data, sejumlah antarmuka perlu diimplementasikan untuk mengekspos aspek inti debugger: penargetannya, ruang memorinya, evaluatornya, sistem simbolis dan jenisnya, dll... Meskipun antarmuka ini diimplementasikan oleh aplikasi apa pun yang ingin menghosting model data, antarmuka tersebut dikonsumsi oleh model data inti serta ekstensi apa pun yang interoperabilitas dengan model data.
Sistem jenis dan antarmuka simbolis adalah:
| Nama Antarmuka | Deskripsi |
|---|---|
| IDebugHostSymbols | Antarmuka inti yang menyediakan akses ke dan resolusi simbol |
| IDebugHostSymbol / IDebugHostSymbol2 | Mewakili simbol tunggal dalam bentuk apa pun. Simbol tertentu adalah turunan dari antarmuka ini. |
| IDebugHostModule | Mewakili modul yang dimuat dalam proses. Ini semacam simbol. |
| IDebugHostType / IDebugHostType2 | Mewakili jenis asli/bahasa. |
| IDebugHostConstant | Mewakili konstanta dalam informasi simbolis (misalnya: argumen templat non-jenis di C++) |
| IDebugHostField | Mewakili bidang dalam struktur atau kelas. |
| IDebugHostData | Mewakili data dalam modul (apakah ini dalam struktur atau kelas itu akan menjadi IDebugHostField) |
| IDebugHostBaseClass | Mewakili kelas dasar. |
| IDebugHostPublic | Mewakili simbol dalam tabel publik PDB. Ini tidak memiliki informasi jenis yang terkait dengannya. Ini adalah nama dan alamat. |
| IDebugHostModuleSignature | Mewakili tanda tangan modul -- definisi yang akan cocok dengan sekumpulan modul berdasarkan nama dan/atau versi |
| IDebugHostTypeSignature | Mewakili tanda tangan jenis -- definisi yang akan cocok dengan sekumpulan jenis menurut modul dan/atau nama |
Antarmuka inti lainnya adalah:
| Nama Antarmuka | Deskripsi |
|---|---|
| IDebugHost | Antarmuka inti ke host debug. |
| IDebugHostStatus | Antarmuka yang memungkinkan klien untuk mengkueri status host. |
| IDebugHostContext | Abstraksi konteks dalam host (misalnya: target tertentu, proses tertentu, ruang alamat tertentu, dll...) |
| IDebugHostErrorSink | Antarmuka yang diimplementasikan oleh penelepon untuk menerima kesalahan dari bagian tertentu dari host dan model data |
| IDebugHostEvaluator / IDebugHostEvaluator2 | Evaluator ekspresi host debug. |
| IDebugHostExtensibility | Antarmuka untuk memperluas kemampuan host atau bagiannya (seperti evaluator ekspresi). |
Antarmuka Simbolis Utama: IDebugHostSymbols
Antarmuka IDebugHostSymbols adalah titik awal utama untuk mengakses simbol dalam target debug. Antarmuka ini dapat dikueri dari instans IDebugHost dan didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostSymbols, IUnknown)
{
STDMETHOD(CreateModuleSignature)(_In_z_ PCWSTR pwszModuleName, _In_opt_z_ PCWSTR pwszMinVersion, _In_opt_z_ PCWSTR pwszMaxVersion, _Out_ IDebugHostModuleSignature** ppModuleSignature) PURE;
STDMETHOD(CreateTypeSignature)(_In_z_ PCWSTR signatureSpecification, _In_opt_ IDebugHostModule* module, _Out_ IDebugHostTypeSignature** typeSignature) PURE;
STDMETHOD(CreateTypeSignatureForModuleRange)(_In_z_ PCWSTR signatureSpecification, _In_z_ PCWSTR moduleName, _In_opt_z_ PCWSTR minVersion, _In_opt_z_ PCWSTR maxVersion, _Out_ IDebugHostTypeSignature** typeSignature) PURE;
STDMETHOD(EnumerateModules)(_In_ IDebugHostContext* context, _COM_Outptr_ IDebugHostSymbolEnumerator** moduleEnum) PURE;
STDMETHOD(FindModuleByName)(_In_ IDebugHostContext* context, _In_z_ PCWSTR moduleName, _COM_Outptr_ IDebugHostModule **module) PURE;
STDMETHOD(FindModuleByLocation)(_In_ IDebugHostContext* context, _In_ Location moduleLocation, _COM_Outptr_ IDebugHostModule **module) PURE;
STDMETHOD(GetMostDerivedObject)(_In_opt_ IDebugHostContext *pContext, _In_ Location location, _In_ IDebugHostType* objectType, _Out_ Location* derivedLocation, _Out_ IDebugHostType** derivedType) PURE;
}
Metode CreateModuleSignature membuat tanda tangan yang dapat digunakan untuk mencocokkan sekumpulan modul tertentu berdasarkan nama dan secara opsional, berdasarkan versi. Ada tiga komponen untuk tanda tangan modul:
- Nama: modul yang cocok harus memiliki nama yang merupakan kecocokan tidak peka huruf besar/kecil yang tepat terhadap nama dalam tanda tangan
- Versi minimum: jika ditentukan, modul yang cocok harus memiliki versi minimum yang setidaknya setingkat versi ini. Versi ditentukan dalam format "A.B.C.D" dengan setiap bagian berikutnya kurang penting daripada sebelumnya. Hanya segmen pertama yang wajib.
- Versi maksimum: jika ditentukan, modul yang cocok harus memiliki versi maksimum yang tidak lebih tinggi dari versi ini. Versi ditentukan dalam format "A.B.C.D" dengan setiap bagian berikutnya kurang penting daripada sebelumnya. Hanya segmen pertama yang wajib.
Metode CreateTypeSignature membuat tanda tangan yang dapat digunakan untuk mencocokkan sekumpulan jenis beton dengan berisi modul dan nama jenis. Format string tanda tangan nama jenis khusus untuk bahasa yang di-debug (dan host debug). Untuk C/C++, string tanda tangan setara dengan Spesifikasi Jenis NatVis. Artinya, string tanda tangan adalah nama jenis di mana kartubebas (ditentukan sebagai *) diizinkan untuk argumen templat.
CreateTypeSignatureForModuleRange
Metode CreateTypeSignatureForModuleRange membuat tanda tangan yang dapat digunakan untuk mencocokkan sekumpulan jenis beton berdasarkan tanda tangan modul dan nama jenis. Ini mirip dengan metode CreateTypeSignature kecuali bahwa alih-alih meneruskan modul tertentu agar cocok dengan tanda tangan, pemanggil meneruskan argumen yang diperlukan untuk membuat tanda tangan modul (seolah-olah tanda tangan modul dibuat dengan metode CreateModuleSignature).
Metode EnumerateModules membuat enumerator yang akan menghitung setiap modul yang tersedia dalam konteks host tertentu. Konteks host tersebut mungkin merangkum konteks proses atau mungkin merangkum sesuatu seperti kernel Windows.
Metode FindModuleByName akan melihat melalui konteks host yang diberikan dan menemukan modul yang memiliki nama yang ditentukan dan mengembalikan antarmuka ke dalamnya. Adalah legal untuk mencari modul berdasarkan nama dengan atau tanpa ekstensi file.
Metode FindModuleByLocation akan melihat melalui konteks host yang diberikan dan menentukan modul apa yang berisi alamat yang diberikan oleh lokasi yang ditentukan. Kemudian akan mengembalikan antarmuka ke modul tersebut.
GetMostDerivedObject akan menggunakan sistem jenis debugger untuk menentukan jenis runtime objek dari jenis statisnya. Metode ini hanya akan menggunakan informasi simbolis dan heuristik yang tersedia pada lapisan sistem jenis untuk melakukan analisis ini. Informasi tersebut dapat mencakup C++ RTTI (informasi jenis run time) atau analisis bentuk tabel fungsi virtual objek. Ini tidak termasuk hal-hal seperti konsep jenis runtime yang disukai pada IModelObject. Jika analisis tidak dapat menemukan jenis runtime atau tidak dapat menemukan jenis runtime yang berbeda dari jenis statis yang diteruskan ke metode , lokasi input dan jenis mungkin pingsan. Metode ini tidak akan gagal karena alasan ini.
Antarmuka Simbol Individu Inti: IDebugHostSymbol
Setiap simbol yang dapat dikembalikan dari host model data akan berasal dari beberapa mode dari IDebugHostSymbol. Ini adalah antarmuka inti yang diterapkan setiap simbol terlepas dari jenis simbol. Tergantung pada jenis simbol, simbol tertentu dapat mengimplementasikan sekumpulan antarmuka lain yang mengembalikan atribut yang lebih unik untuk jenis simbol tertentu yang diwakili oleh antarmuka ini. Antarmuka IDebugHostSymbol2 / IDebugHostSymbol didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostSymbol2, IDebugHostSymbol)
{
//
// IDebugHostSymbol:
//
STDMETHOD(GetContext)(_COM_Outptr_ IDebugHostContext** context) PURE;
STDMETHOD(EnumerateChildren)(_In_ SymbolKind kind, _In_opt_z_ PCWSTR name, _Out_ IDebugHostSymbolEnumerator **ppEnum) PURE;
STDMETHOD(GetSymbolKind)(_Out_ SymbolKind *kind) PURE;
STDMETHOD(GetName)(_Out_ BSTR* symbolName) PURE;
STDMETHOD(GetType)(_Out_ IDebugHostType** type) PURE;
STDMETHOD(GetContainingModule)(_Out_ IDebugHostModule **containingModule) PURE;
STDMETHOD(CompareAgainst)(_In_ IDebugHostSymbol *pComparisonSymbol, _In_ ULONG comparisonFlags, _Out_ bool *pMatches) PURE;
//
// IDebugHostSymbol2
//
STDMETHOD(EnumerateChildrenEx)(_In_ SymbolKind kind, _In_opt_z_ PCWSTR name, _In_opt_ SymbolSearchInfo* searchInfo, _Out_ IDebugHostSymbolEnumerator **ppEnum) PURE;
}
Sangat penting untuk dicatat bahwa antarmuka ini mewakili banyak jenis simbol -- yang digambarkan oleh enumerasi SymbolKind yang memiliki nilai sebagai berikut:
| Enumarant | Makna |
|---|---|
| Simbol | Jenis simbol yang tidak ditentukan |
| SymbolModule | Simbol adalah modul dan dapat dikueri untuk IDebugHostModule |
| SymbolType | Simbol adalah jenis dan dapat dikueri untuk IDebugHostType |
| SymbolField | Simbol adalah bidang (anggota data dalam struktur atau kelas) dan dapat dikueri untuk IDebugHostField |
| SymbolConstant | Simbol adalah nilai konstanta dan dapat dikueri untuk IDebugHostConstant |
| SymbolData | Simbol adalah data yang bukan anggota struktur atau kelas dan dapat dikueri untuk IDebugHostData |
| SymbolBaseClass | Simbol adalah kelas dasar dan dapat dikueri untuk IDebugHostBaseClass |
| SymbolPublic | Simbol adalah entri dalam tabel publik modul (tidak memiliki informasi jenis) dan dapat dikueri untuk IDebugHostPublic |
| SymbolFunction | Simbol adalah fungsi dan dapat dikueri untuk IDebugHostData |
Metode GetContext mengembalikan konteks di mana simbol valid. Meskipun ini akan mewakili hal-hal seperti target debug dan ruang proses/alamat di mana simbol ada, mungkin tidak spesifik seperti konteks yang diambil dari cara lain (misalnya: dari IModelObject).
Metode EnumerateChildren mengembalikan enumerator yang akan menghitung semua anak dari simbol tertentu. Untuk jenis C++, misalnya, kelas dasar, bidang, fungsi anggota, dan sejenisnya semuanya dianggap sebagai anak dari simbol jenis.
Antarmuka Modul: IDebugHostModule
Gagasan debugger tentang modul yang dimuat dalam beberapa ruang alamat diwakili dengan dua cara berbeda dalam model data: Pada tingkat sistem jenis melalui antarmuka IDebugHostModule. Di sini, modul adalah simbol dan atribut inti modul adalah panggilan metode antarmuka yang Diproyeksikan pada tingkat model data melalui model data Debugger.Models.Module. Ini adalah enkapulasi yang dapat diperluas dari sistem jenis representasi IDebugHostModule dari modul.
Antarmuka IDebugHostModule didefinisikan sebagai berikut (mengabaikan metode yang umum untuk IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostModule, IDebugHostSymbol)
{
//
// IDebugHostModule:
//
STDMETHOD(GetImageName)(_In_ bool allowPath, _Out_ BSTR* imageName) PURE;
STDMETHOD(GetBaseLocation)(_Out_ Location* moduleBaseLocation) PURE;
STDMETHOD(GetVersion)(_Out_opt_ ULONG64* fileVersion, _Out_opt_ ULONG64* productVersion) PURE;
STDMETHOD(FindTypeByName)(_In_z_ PCWSTR typeName, _Out_ IDebugHostType** type) PURE;
STDMETHOD(FindSymbolByRVA)(_In_ ULONG64 rva, _Out_ IDebugHostSymbol** symbol) PURE;
STDMETHOD(FindSymbolByName)(_In_z_ PCWSTR symbolName, _Out_ IDebugHostSymbol** symbol) PURE;
}
Metode GetImageName mengembalikan nama gambar modul. Bergantung pada nilai argumen allowPath, nama gambar yang dikembalikan mungkin atau mungkin tidak menyertakan jalur lengkap ke gambar.
Metode GetBaseLocation mengembalikan alamat beban dasar modul sebagai struktur lokasi. Struktur lokasi yang dikembalikan untuk modul biasanya akan merujuk ke alamat virtual.
Metode GetVersion mengembalikan informasi versi tentang modul (dengan asumsi bahwa informasi tersebut dapat berhasil dibaca dari header). Jika versi tertentu diminta (melalui penunjuk output non-nullptr) dan tidak dapat dibaca, kode kesalahan yang sesuai akan dikembalikan dari panggilan metode.
Metode FindTypeByName menemukan jenis yang ditentukan dalam modul dengan nama jenis dan mengembalikan simbol jenis untuknya. Metode ini dapat mengembalikan IDebugHostType yang valid yang tidak akan pernah dikembalikan melalui rekursi eksplisit anak-anak modul. Host debug dapat memungkinkan pembuatan jenis turunan -- jenis yang tidak pernah digunakan dalam modul itu sendiri tetapi berasal dari jenis yang. Sebagai contoh, jika struktur MyStruct didefinisikan dalam simbol modul tetapi jenis MyStruct ** tidak pernah digunakan, metode FindTypeByName mungkin secara sah mengembalikan simbol jenis untuk MyStruct ** meskipun nama jenis tersebut tidak pernah secara eksplisit muncul dalam simbol untuk modul.
Metode FindSymbolByRVA akan menemukan simbol pencocokan tunggal di alamat virtual relatif yang diberikan dalam modul. Jika tidak ada simbol tunggal di RVA yang disediakan (misalnya: ada beberapa kecocokan), kesalahan akan dikembalikan oleh metode ini. Perhatikan bahwa metode ini akan lebih suka mengembalikan simbol privat daripada simbol dalam tabel publik.
Metode FindSymbolByName akan menemukan simbol global tunggal dari nama yang diberikan dalam modul. Jika tidak ada simbol tunggal yang cocok dengan nama yang diberikan, kesalahan akan dikembalikan oleh metode ini. Perhatikan bahwa metode ini akan lebih memilih mengembalikan simbol privat daripada simbol dalam tabel publik.
Akses ke Sistem Jenis: IDebugHostType2 / IDebugHostType
Jenis bahasa/asli tertentu dijelaskan oleh antarmuka IDebugHostType2 atau IDebugHostType. Perhatikan bahwa beberapa metode pada antarmuka ini hanya berlaku untuk jenis jenis tertentu. Simbol jenis tertentu dapat merujuk ke salah satu jenis berikut seperti yang dijelaskan oleh enumerasi TypeKind:
| Jenis Jenis | Deskripsi |
|---|---|
| TypeUDT | Jenis yang ditentukan pengguna (struct, class, union, dll...). Objek model yang memiliki jenis asli yang jenisnya adalah TypeUDT memiliki representasi kanonis ObjectTargetObject di mana jenis selalu disimpan di dalam IModelObject yang sesuai. |
| TypePointer | Sebuah penunjuk. Objek model yang memiliki jenis asli yang jenisnya adalah TypePointer memiliki representasi kanonis ObjectIntrinsic di mana nilai pointer nol diperluas ke VT_UI8 dan disimpan sebagai data intrinsik dalam bentuk 64-bit ini. Simbol jenis apa pun dari TypePointer memiliki jenis dasar (seperti yang dikembalikan oleh metode GetBaseType) dari jenis yang dituju penunjuk. |
| TypeMemberPointer | Penunjuk ke anggota kelas. Objek model yang memiliki jenis asli yang jenisnya adalah TypeMemberPointer memiliki representasi kanonis yang intrinsik (nilainya sama dengan nilai pointer). Arti pasti dari nilai ini adalah spesifik host compiler/debug. |
| TypeArray | Array. Objek model yang memiliki jenis asli yang jenisnya adalah TypeArray memiliki representasi kanonis ObjectTargetObject. Alamat dasar array adalah lokasi objek (diambil melalui metode GetLocation) dan jenis array selalu disimpan. Simbol jenis apa pun dari TypeArray memiliki jenis dasar (seperti yang dikembalikan oleh metode GetBaseType) dari jenis array yang merupakan array. |
| TypeFunction | Sebuah fungsi. |
| TypeTypedef | Typedef. Objek model yang memiliki jenis asli yang jenisnya adalah TypeTypedef memiliki representasi kanonis yang identik dengan representasi kanonis dari jenis akhir yang mendasar typedef. Ini tampak benar-benar transparan untuk pengguna akhir objek dan informasi jenis kecuali metode typedef eksplisit IDebugHostType2 digunakan untuk mengkueri informasi typedef atau ada model data eksplisit yang terdaftar terhadap typedef. Perhatikan bahwa metode GetTypeKind tidak akan pernah mengembalikan TypeTypedef. Setiap metode akan mengembalikan apa yang akan dikembalikan oleh typedef akhir. Ada metode khusus typedef pada IDebugHostType2 yang dapat digunakan untuk mendapatkan informasi spesifik typedef. |
| TypeEnum | Sebuah enum. Objek model yang memiliki jenis asli yang jenisnya adalah TypeEnum memiliki representasi kanonis ObjectIntrinsic di mana nilai dan jenis intrinsik identik dengan nilai enum. |
| TypeIntrinsic | Intrinsik (jenis dasar). Objek model yang memiliki jenis asli yang jenisnya adalah TypeIntrinsic memiliki representasi kanonis ObjectIntrinsic. Informasi jenis mungkin atau mungkin tidak disimpan -- terutama jika jenis yang mendasar sepenuhnya dijelaskan oleh jenis data varian (VT_*) dari data intrinsik yang disimpan di IModelObject |
Antarmuka IDebugHostType2 / IDebugHostType secara keseluruhan didefinisikan sebagai berikut (tidak termasuk metode IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostType2, IDebugHostType)
{
//
// IDebugHostType:
//
STDMETHOD(GetTypeKind)(_Out_ TypeKind *kind) PURE;
STDMETHOD(GetSize)(_Out_ ULONG64* size) PURE;
STDMETHOD(GetBaseType)(_Out_ IDebugHostType** baseType) PURE;
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
STDMETHOD(GetIntrinsicType)(_Out_opt_ IntrinsicKind *intrinsicKind, _Out_opt_ VARTYPE *carrierType) PURE;
STDMETHOD(GetBitField)(_Out_ ULONG* lsbOfField, _Out_ ULONG* lengthOfField) PURE;
STDMETHOD(GetPointerKind)(_Out_ PointerKind* pointerKind) PURE;
STDMETHOD(GetMemberType)(_Out_ IDebugHostType** memberType) PURE;
STDMETHOD(CreatePointerTo)(_In_ PointerKind kind, _COM_Outptr_ IDebugHostType** newType) PURE;
STDMETHOD(GetArrayDimensionality)(_Out_ ULONG64* arrayDimensionality) PURE;
STDMETHOD(GetArrayDimensions)(_In_ ULONG64 dimensions, _Out_writes_(dimensions) ArrayDimension *pDimensions) PURE;
STDMETHOD(CreateArrayOf)(_In_ ULONG64 dimensions, _In_reads_(dimensions) ArrayDimension *pDimensions, _COM_Outptr_ IDebugHostType** newType) PURE;
STDMETHOD(GetFunctionCallingConvention)(_Out_ CallingConventionKind* conventionKind) PURE;
STDMETHOD(GetFunctionReturnType)(_COM_Outptr_ IDebugHostType** returnType) PURE;
STDMETHOD(GetFunctionParameterTypeCount)(_Out_ ULONG64* count) PURE;
STDMETHOD(GetFunctionParameterTypeAt)(_In_ ULONG64 i, _Out_ IDebugHostType** parameterType) PURE;
STDMETHOD(IsGeneric)(_Out_ bool* isGeneric) PURE;
STDMETHOD(GetGenericArgumentCount)(_Out_ ULONG64* argCount) PURE;
STDMETHOD(GetGenericArgumentAt)(_In_ ULONG64 i, _Out_ IDebugHostSymbol** argument) PURE;
//
// IDebugHostType2:
//
STDMETHOD(IsTypedef)(_Out_ bool* isTypedef) PURE;
STDMETHOD(GetTypedefBaseType)(_Out_ IDebugHostType2** baseType) PURE;
STDMETHOD(GetTypedefFinalBaseType)(_Out_ IDebugHostType2** finalBaseType) PURE;
STDMETHOD(GetFunctionVarArgsKind)(_Out_ VarArgsKind* varArgsKind) PURE;
}
Metode Umum IDebugHostType2/IDebugHostType
Metode IDebugHostType berikut umum untuk semua jenis terlepas dari jenis apa yang dikembalikan dari metode GetTypeKind:
STDMETHOD(GetTypeKind)(_Out_ TypeKind *kind) PURE;
STDMETHOD(GetSize)(_Out_ ULONG64* size) PURE;
STDMETHOD(GetBaseType)(_Out_ IDebugHostType** baseType) PURE;
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
Metode GetTypeKind mengembalikan jenis seperti apa (pointer, array, intrinsik, dll...) simbol yang dirujuk.
Metode GetSize mengembalikan ukuran jenis (seolah-olah seseorang telah melakukan sizeof(type) di C++).
Jika jenis adalah turunan dari jenis tunggal lain (misalnya: sebagai MyStruct * berasal dari MyStruct'), metode GetBaseType mengembalikan jenis dasar derivasi. Untuk penunjuk, ini mengembalikan jenis yang ditujukkan. Untuk array, ini mengembalikan array sebagai array. Jika jenisnya bukan jenis turunan seperti itu, kesalahan akan dikembalikan.
Metode GetHashCode mengembalikan kode hash 32-bit untuk jenis tersebut. Dengan pengecualian kecocokan global (misalnya: tanda tangan jenis yang setara dengan * yang cocok dengan semuanya jika diizinkan oleh host), instans jenis apa pun yang dapat cocok dengan tanda tangan jenis tertentu harus mengembalikan kode hash yang sama. Metode ini digunakan bersama dengan tanda tangan jenis untuk mencocokkan tanda tangan jenis dengan instans jenis.
Metode Intrinsik IDebugHostType2/IDebugHostType
Metode IDebugHostType berikut ini khusus untuk jenis intrinsik (atau jenis yang menyimpan data intrinsik seperti enum):
STDMETHOD(GetIntrinsicType)(_Out_opt_ IntrinsicKind *intrinsicKind, _Out_opt_ VARTYPE *carrierType) PURE;
Metode GetIntrinsicType mengembalikan informasi tentang jenis intrinsik jenis tersebut. Dua nilai dikembalikan dari metode ini:
- Jenis intrinsik menunjukkan jenis keseluruhan (misalnya: bilangan bulat, tidak ditandatangani, titik mengambang) tetapi bukan ukuran jenis (misalnya: 8 bit, 16 bit, 32 bit, 64 bit)
- Jenis operator menunjukkan bagaimana jenis intrinsik dikemas ke dalam struktur VARIAN. Ini adalah konstanta VT_*.
Kombinasi kedua nilai ini menyediakan sekumpulan informasi lengkap tentang intrinsik.
Metode Bitfield IDebugHostType2/IDebugHostType
Metode IDebugHostType berikut ini khusus untuk jenis yang menyimpan data di bitfields. Informasi tentang penempatan bitfield dalam intrinsik disimpan sebagai bagian dari simbol jenis dalam model data daripada menjadi atribut lokasi.
STDMETHOD(GetBitField)(_Out_ ULONG* lsbOfField, _Out_ ULONG* lengthOfField) PURE;
Jika anggota tertentu dari struktur data adalah bitfield (misalnya: ULONG MyBits:8), informasi jenis untuk bidang membawa informasi tentang penempatan bitfield. Metode GetBitField dapat digunakan untuk mengambil informasi tersebut. Metode ini akan gagal pada jenis apa pun yang bukan bitfield. Ini adalah satu-satunya alasan metode akan gagal. Cukup memanggil metode ini dan melihat keberhasilan/kegagalan cukup untuk membedakan sedikit bidang dari bidang non-bit. Jika jenis tertentu memang kebetulan bitfield, posisi bidang didefinisikan oleh setengah set terbuka (lsbOfField + lengthOfField : lsbOfField]
Metode Terkait IDebugHostType2/IDebugHostType Pointer
Metode IDebugHostType berikut ini khusus untuk jenis penunjuk. Seperti jenis di mana GetTypeKind mengembalikan TypePointer atau TypeMemberPointer':
STDMETHOD(GetPointerKind)(_Out_ PointerKind* pointerKind) PURE;
STDMETHOD(GetMemberType)(_Out_ IDebugHostType** memberType) PURE;
Untuk jenis yang merupakan pointer, metode GetPointerKind mengembalikan jenis pointer. Ini didefinisikan oleh enumerasi PointerKind.
Untuk jenis yang merupakan pointer-to-member (seperti yang ditunjukkan oleh jenis TypeMemberPointer), metode GetMemberType mengembalikan kelas penunjuk adalah pointer-to-member.
Metode Terkait IDebugHostType2/IDebugHostType Array
Array adalah jenis di mana GetTypeKind mengembalikan TypeArray. Perhatikan bahwa array seperti yang didefinisikan oleh sistem jenis host debug tidak sama dengan dimensi tunggal, tanpa indeks berbasis, dikemas linier satu array dimensi yang digunakan C. Array gaya C cocok dengan definisi tetapi cakupan keseluruhan array lebih luas di IDebugHostType. Array dalam host debug dapat multi-dimensi dan setiap dimensi dalam array ditentukan oleh deskriptor yang dikenal sebagai deskriptor ArrayDimensionThis memiliki bidang berikut:
| Bidang | Makna |
|---|---|
| Hilir | Indeks dasar array sebagai nilai 64-bit yang ditandatangani. Untuk array gaya C, ini akan selalu nol. Ini tidak perlu. Dimensi individual array dapat dipertimbangkan untuk memulai pada indeks 64-bit apa pun, bahkan yang negatif. |
| Panjang | Panjang dimensi array sebagai nilai 64-bit yang tidak ditandatangani. Indeks array mencakup setengah set terbuka [LowerBound, LowerBound + Length). |
| Langkahnya | Menentukan langkah dimensi array. Untuk peningkatan satu (dari N ke N + 1) dalam indeks dimensi ini, ini menunjukkan berapa banyak byte untuk bergerak maju dalam memori. Untuk array gaya C, ini akan menjadi ukuran setiap elemen array. Tidak perlu begitu. Padding antar elemen dapat diekspresikan sebagai langkah yang lebih besar dari ukuran setiap elemen individu. Untuk array multidimensi, nilai ini akan menunjukkan cara memindahkan seluruh dimensi ke depannya. Pertimbangkan matriks M x N. Ini mungkin dijelaskan dalam bentuk utama baris sebagai dua dimensi: |
{ [LowerBound: 0, Length: M, Stride: N \* sizeof(element)], [LowerBound: 0, Length: N, Stride: sizeof(element)]}
atau mungkin secara alternatif dijelaskan dalam bentuk utama kolom sebagai dua dimensi:
{ [LowerBound: 0, Length: M, Stride: sizeof(element)], [LowerBound: 0, Length: N, Stride: M \* sizeof(element)]}
Konsep ArrayDimension memungkinkan tingkat fleksibilitas ini.
Metode IDebugHostType berikut ini khusus untuk jenis array.
STDMETHOD(GetArrayDimensionality)(\_Out_ ULONG64\* arrayDimensionality) PURE;
STDMETHOD(GetArrayDimensions)(\_In_ ULONG64 dimensions, \_Out_writes_(dimensions) ArrayDimension \*pDimensions) PURE;
Metode GetArrayDimensionality mengembalikan jumlah dimensi tempat array diindeks. Untuk array gaya C, nilai yang dikembalikan di sini akan selalu 1.
Metode GetArrayDimensions mengembalikan sekumpulan deskriptor, satu untuk setiap dimensi array seperti yang ditunjukkan oleh metode GetArrayDimensionality. Setiap deskriptor adalah struktur ArrayDimension yang menjelaskan indeks awal, panjang, dan langkah maju dari setiap dimensi array. Ini memungkinkan deskripsi konstruksi array yang jauh lebih kuat daripada yang diizinkan dalam sistem jenis C.
Untuk array gaya C, dimensi array tunggal dikembalikan di sini dengan nilai yang selalu:
- Batas Bawah = 0
- Panjang = ARRAYSIZE(array)
- Stride = sizeof(elementType)
Metode Terkait Fungsi IDebugHostType2/IDebugHostType
Jenis yang menunjukkan bahwa mereka adalah jenis fungsi melalui semacam TypeFunction mendukung metode berikut di IDebugHostType dan IDebugHostType2.
//
// IDebugHostType:
//
STDMETHOD(GetFunctionCallingConvention)(_Out_ CallingConventionKind* conventionKind) PURE;
STDMETHOD(GetFunctionReturnType)(_COM_Outptr_ IDebugHostType** returnType) PURE;
STDMETHOD(GetFunctionParameterTypeCount)(_Out_ ULONG64* count) PURE;
STDMETHOD(GetFunctionParameterTypeAt)(_In_ ULONG64 i, _Out_ IDebugHostType** parameterType) PURE;
//
// IDebugHostType2:
//
STDMETHOD(GetFunctionVarArgsKind)(_Out_ VarArgsKind* varArgsKind) PURE;
Metode GetFunctionCallingConvention mengembalikan konvensi panggilan fungsi. Hal tersebut dikembalikan sebagai anggota enumerasi CallingConventionKind.
Metode GetFunctionReturnType mengembalikan jenis pengembalian fungsi.
Metode GetFunctionParameterTypeCount mengembalikan jumlah argumen yang diambil fungsi. Perhatikan bahwa penanda argumen variabel berbasis elipsis C/C++ tidak dipertimbangkan dalam hitungan ini. Kehadirannya harus dideteksi melalui metode GetFunctionVarArgsKind. Ini hanya akan mencakup argumen sebelum elipsis.
Metode GetFunctionParameterTypeAt mengembalikan jenis argumen i-th ke fungsi.
Metode GetFunctionVarArgsKind mengembalikan apakah fungsi tertentu menggunakan daftar argumen variabel, dan jika demikian, gaya argumen apa yang digunakannya. Demikian didefinisikan oleh anggota enumerasi VarArgsKind yang didefinisikan sebagai berikut:
| Enumeran | Makna |
|---|---|
| VarArgsNone | Fungsi ini tidak mengambil argumen variabel apa pun. |
| VarArgsCStyle | Fungsi ini adalah fungsi varargs gaya C (returnType(arg1, arg2, ...)). Jumlah argumen yang dilaporkan oleh fungsi tidak menyertakan argumen elipsis. Setiap argumen variabel yang diteruskan terjadi setelah jumlah argumen yang dikembalikan oleh metode GetFunctionParameterTypeCount. |
IDebugHostType2 GetFunctionVarArgsKind
Metode GetFunctionVarArgsKind mengembalikan apakah fungsi tertentu menggunakan daftar argumen variabel, dan jika demikian, gaya argumen apa yang digunakannya. Demikian didefinisikan oleh anggota enumerasi VarArgsKind yang didefinisikan sebagai berikut:
Metode Terkait IDebugHostType2/IDebugHostType Typedef
Jenis apa pun yang merupakan typedef akan bersifat seolah-olah jenisnya adalah jenis akhir yang mendasar typedef. Ini berarti bahwa metode seperti GetTypeKind tidak akan menunjukkan bahwa jenisnya adalah typedef. Demikian juga, GetBaseType tidak akan mengembalikan jenis yang dirujuk oleh definisi. Mereka sebaliknya akan menunjukkan perilaku seolah-olah mereka dipanggil pada definisi akhir yang mendasar typedef. Sebagai contoh:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
IDebugHostType untuk 'PMYSTRUCT atau PTRMYSTRUCT akan melaporkan informasi berikut:
- Metode GetTypeKind akan mengembalikan TypePointer. Jenis akhir yang mendasar MYSTRUCT * memang penunjuk.
- Metode 'GetBaseType akan mengembalikan jenis untuk MYSTRUCT. Jenis MYSTRUCT * yang mendasar adalah MYSTRUCT.
Satu-satunya perbedaan di sini adalah bagaimana metode khusus typedef pada IDebugHostType2 bertingkah laku. Metode tersebut adalah:
STDMETHOD(IsTypedef)(_Out_ bool* isTypedef) PURE;
STDMETHOD(GetTypedefBaseType)(_Out_ IDebugHostType2** baseType) PURE;
STDMETHOD(GetTypedefFinalBaseType)(_Out_ IDebugHostType2** finalBaseType) PURE;
Dalam contoh ini:
- Metode IsTypedef akan mengembalikan true untuk PMYSTRUCT dan PTRMYSTRUCT
- Metode GetTypedefBaseType akan mengembalikan MYSTRUCT * untuk PMYSTRUCT dan PMYSTRUCT untuk PTRMYSTRUCT
- Metode GetTypedefFinalBaseType akan mengembalikan MYSTRUCT * untuk kedua jenis
Metode IsTypedef adalah satu-satunya metode yang mampu melihat apakah jenis adalah typedef. Metode GetTypeKind akan berulah seolah-olah dipanggil pada jenis yang mendasar.
Metode GetTypedefBaseType akan mengembalikan definisi langsung dari typedef. Dalam contoh yang dijelaskan dalam dokumentasi:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
metode ini akan mengembalikan MYSTRUCT * untuk PMYSTRUCT dan PMYSTRUCT untuk PTRMYSTRUCT.
Metode GetTypedefFinalBaseType akan mengembalikan jenis akhir yang merupakan definisi dari typedef. Jika typedef adalah definisi dari typedef lain, ini akan terus mengikuti rantai definisi sampai mencapai jenis yang bukan typedef dan jenis tersebut akan dikembalikan. Dalam contoh yang dijelaskan dalam dokumentasi:
typedef MYSTRUCT *PMYSTRUCT;
typedef PMYSTRUCT PTRMYSTRUCT;
metode ini akan mengembalikan MYSTRUCT * ketika dipanggil pada PMYSTRUCT atau PTRMYSTRUCT.
Metode Pembuatan Jenis IDebugHostType2/IDebugHostType
STDMETHOD(CreatePointerTo)(_In_ PointerKind kind, _COM_Outptr_ IDebugHostType** newType) PURE;
STDMETHOD(CreateArrayOf)(_In_ ULONG64 dimensions, _In_reads_(dimensions) ArrayDimension *pDimensions, _COM_Outptr_ IDebugHostType** newType) PURE;
Nilai Simbol Konstan: IDebugHostConstant
Untuk lokasi di mana nilai konstanta ada dalam informasi simbolis (di mana nilai tertentu adalah simbol yang mungkin atau mungkin bukan nilai konstanta), antarmuka IDebugHostConstant mengekspresikan gagasan tentang konstanta tersebut. Ini biasanya digunakan di tempat-tempat seperti argumen templat di mana argumen tertentu biasanya merupakan jenis tetapi mungkin argumen templat non-jenis (misalnya: konstanta).
Antarmuka IDebugHostConstant didefinisikan sebagai berikut (mengabaikan metode generik yang diterapkan oleh IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostConstant, IDebugHostSymbol)
{
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Metode GetValue mengembalikan nilai konstanta yang dikemas ke dalam VARIAN. Penting untuk dicatat bahwa metode GetType pada IDebugHostSymbol dapat mengembalikan simbol jenis tertentu untuk konstanta. Dalam kasus seperti itu, tidak ada jaminan bahwa pengemasan nilai konstanta seperti yang didefinisikan oleh simbol jenis sama dengan pengemasan seperti yang dikembalikan oleh metode GetValue di sini.
Akses Anggota Data: IDebugHostField
Kelas IDebugHostField mewakili simbol yang merupakan anggota data dari kelas, struktur, serikat, atau konstruksi jenis lainnya. Ini tidak mewakili data gratis (misalnya: data global). Antarmuka didefinisikan sebagai berikut (mengabaikan metode generik ke IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostField, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetOffset)(_Out_ ULONG64* offset) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Metode GetLocationKind mengembalikan jenis lokasi simbol sesuai dengan enumerasi LocationKind. Enumerasi tersebut dapat menjadi salah satu nilai berikut:
| Enumeran | Makna |
|---|---|
| LocationMember | Bidang ini adalah anggota data reguler dari konstruksi kelas, struktur, serikat, atau jenis lainnya. Ini memiliki offset yang relatif terhadap alamat dasar konstruksi jenis yang berisi. Alamat dasar tersebut biasanya diwakili oleh penunjuk ini. Offset bidang dapat diambil melalui metode GetOffset. Metode GetLocation dan GetValue akan gagal untuk bidang yang merupakan LocationMember. |
| LocationStatic | Bidang ini statis dan memiliki alamatnya sendiri. Metode GetLocation akan mengembalikan lokasi abstrak (misalnya: alamat) dari bidang statis. Metode GetOffset dan GetValue akan gagal untuk bidang yang merupakan LocationStatic. |
| LocationConstant | Bidang adalah konstanta dan memiliki nilai. Metode GetValue akan mengembalikan nilai konstanta. Metode GetOffset dan GetLocation akan gagal untuk bidang yang merupakan LocationConstant |
| LocationNone | Bidang tidak memiliki lokasi. Ini mungkin telah dioptimalkan oleh pengkompilasi atau mungkin bidang statis yang dideklarasikan tetapi tidak pernah didefinisikan. Terlepas dari seberapa besar bidang tersebut, bidang tersebut tidak memiliki kehadiran atau nilai fisik. Ini hanya dalam simbol. Semua metode akuisisi (GetOffset, GetLocation, dan GetValue) akan gagal untuk bidang yang merupakan LocationNone. |
Untuk bidang yang memiliki offset (misalnya: bidang yang jenis lokasinya menunjukkan LocationMember), metode GetOffset akan mengembalikan offset dari alamat dasar jenis yang berisi (penunjuk ini) ke data untuk bidang itu sendiri. Offset tersebut selalu dinyatakan sebagai nilai 64-bit yang tidak ditandatangani. Jika bidang yang diberikan tidak memiliki lokasi yang merupakan offset dari alamat dasar dari jenis yang berisi, metode GetOffset akan gagal.
Untuk bidang yang memiliki alamat terlepas dari instans jenis tertentu (misalnya: bidang yang jenis lokasinya menunjukkan LocationStatic), metode GetLocation akan mengembalikan lokasi abstrak (alamat) bidang. Jika bidang yang diberikan tidak memiliki lokasi statis, metode GetLocation akan gagal.
Untuk bidang yang memiliki nilai konstanta yang ditentukan dalam informasi simbolis (misalnya: bidang yang jenis lokasinya menunjukkan LocationConstant), metode GetValue akan mengembalikan nilai konstanta bidang. Jika bidang yang diberikan tidak memiliki nilai konstanta, metode GetValue akan gagal.
Akses Data Gratis: IDebugHostData
Data dalam modul yang bukan anggota dari jenis lain diwakili oleh antarmuka IDebugHostData. Antarmuka tersebut didefinisikan sebagai berikut (mengabaikan metode generik ke IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostData, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
STDMETHOD(GetValue)(_Out_ VARIANT* value) PURE;
}
Semua metode ini secara semantik setara dengan rekan-rekan mereka di IDebugHostField. Satu-satunya perbedaan adalah bahwa metode GetLocationKind tidak akan pernah mengembalikan LocationMember untuk data gratis.
Metode GetLocationKind mengembalikan lokasi seperti apa simbol tersebut sesuai dengan enumerasi LocationKind. Deskripsi enumerasi ini dapat ditemukan dalam dokumentasi untuk IDebugHostField.
Untuk data yang memiliki alamat, metode GetLocation akan mengembalikan lokasi abstrak (alamat) bidang. Jika data yang diberikan tidak memiliki lokasi statis, metode GetLocation akan gagal.
Untuk datayang memiliki nilai konstanta yang ditentukan dalam informasi simbolis (misalnya: data yang jenis lokasinya menunjukkan LocationConstant), metode GetValue akan mengembalikan nilai konstanta bidang. Jika data yang diberikan tidak memiliki nilai konstanta, metode GetValue akan gagal.
Kelas Dasar: IDebugHostBaseClass
Hierarki pewarisan dari jenis tertentu dinyatakan melalui turunan dari simbol jenis. Jika jenis tertentu berasal (pewarisan bijaksana) dari satu atau beberapa jenis, akan ada satu atau beberapa turunan SymbolBaseClass dari simbol jenis untuk jenis tersebut. Masing-masing simbol SymbolBaseClass mewakili warisan langsung dari jenis tertentu. Nama kelas dasar adalah nama simbol SymbolBaseClass serta simbol jenis untuk kelas dasar. Metode GetType pada simbol SymbolBaseClass dapat digunakan untuk mendapatkan simbol jenis untuk kelas dasar itu sendiri. Hierarki pewarisan penuh dapat dilalui dengan menjelajahi simbol anak SymbolBaseClass secara rekursif. Masing-masing simbol kelas dasar ini dinyatakan oleh antarmuka IDebugHostBaseClass yang didefinisikan sebagai berikut (mengabaikan metode generik ke IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostBaseClass, IDebugHostSymbol)
{
STDMETHOD(GetOffset)(_Out_ ULONG64* offset) PURE;
}
Metode GetOffset mengembalikan offset kelas dasar dari alamat dasar kelas turunan. Offset tersebut mungkin nol atau mungkin merupakan nilai 64-bit positif yang tidak ditandatangani.
Simbol Publik: IDebugHostPublic
Simbol publik mewakili hal-hal dalam tabel publik dalam file simbol. Mereka, berlaku, alamat ekspor. Tidak ada informasi jenis yang terkait dengan simbol publik -- hanya alamat. Kecuali simbol publik secara eksplisit diminta oleh pemanggil, host debug lebih suka mengembalikan simbol privat untuk setiap pertanyaan. Simbol publik dinyatakan oleh antarmuka IDebugHostPublic yang didefinisikan sebagai berikut (mengabaikan metode yang umum untuk IDebugHostSymbol):
DECLARE_INTERFACE_(IDebugHostPublic, IDebugHostSymbol)
{
STDMETHOD(GetLocationKind)(_Out_ LocationKind *locationKind) PURE;
STDMETHOD(GetLocation)(_Out_ Location* location) PURE;
}
Semua metode ini secara semantik setara dengan rekan-rekan mereka di IDebugHostField. Satu-satunya perbedaan adalah bahwa metode GetLocationKind tidak akan pernah mengembalikan LocationMember atau LocationConstant untuk simbol tersebut.
Metode GetLocationKind mengembalikan lokasi seperti apa simbol tersebut sesuai dengan enumerasi LocationKind. Deskripsi enumerasi ini dapat ditemukan dalam dokumentasi untuk IDebugHostField.
Untuk data yang memiliki alamat, metode GetLocation akan mengembalikan lokasi abstrak (alamat) bidang. Jika publik yang diberikan tidak memiliki lokasi statis, metode GetLocation akan gagal.
Tanda Tangan Modul dan Pencocokan Versi: IDebugHostModuleSignature
Tanda tangan modul mewakili sarana untuk memeriksa apakah modul tertentu memenuhi serangkaian kriteria mengenai penamaan dan penerapan versi. Tanda tangan modul dibuat melalui metode CreateModuleSignature pada IDebugHostSymbols. Ini dapat mencocokkan nama modul, dan rentang opsional nomor versi untuk modul. Setelah tanda tangan tersebut dibuat, klien menerima antarmuka IDebugHostModuleSignature yang didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostModuleSignature, IUnknown)
{
STDMETHOD(IsMatch)(_In_ IDebugHostModule* pModule, _Out_ bool* isMatch) PURE;
}
Metode IsMatch membandingkan modul tertentu (seperti yang diberikan oleh simbol IDebugHostModule) dengan tanda tangan, membandingkan nama dan versi modul dengan nama dan rentang versi yang ditunjukkan dalam tanda tangan. Indikasi apakah simbol modul yang diberikan cocok dengan tanda tangan dikembalikan.
Ketik Tanda Tangan dan Pencocokan Tipe: IDebugHostTypeSignature
Jenis tanda tangan mewakili sarana untuk memeriksa apakah instans jenis tertentu memenuhi serangkaian kriteria tentang nama jenis, argumen generik ke jenis, dan modul tempat jenis berada. Tanda tangan jenis dibuat melalui metode CreateTypeSignature di IDebugHostSymbols. Setelah tanda tangan tersebut dibuat, klien menerima antarmuka IDebugHostTypeSignature yang didefinisikan sebagai berikut:
DECLARE_INTERFACE_(IDebugHostTypeSignature, IUnknown)
{
STDMETHOD(GetHashCode)(_Out_ ULONG* hashCode) PURE;
STDMETHOD(IsMatch)(_In_ IDebugHostType* type, _Out_ bool* isMatch, _COM_Outptr_opt_ IDebugHostSymbolEnumerator** wildcardMatches) PURE;
STDMETHOD(CompareAgainst)(_In_ IDebugHostTypeSignature* typeSignature, _Out_ SignatureComparison* result) PURE;
}
Metode GetHashCode mengembalikan kode hash 32-bit untuk tanda tangan jenis. Host debug menjamin bahwa ada sinkronisasi dalam implementasi antara kode hash yang dikembalikan untuk instans jenis dan kode hash yang dikembalikan untuk tanda tangan jenis. Dengan pengecualian kecocokan global, jika instans jenis mampu mencocokkan tanda tangan jenis, keduanya akan memiliki kode hash 32-bit yang sama. Ini memungkinkan perbandingan cepat awal dan kecocokan antara instans jenis dan sejumlah besar tanda tangan jenis yang terdaftar di manajer model data.
Metode IsMatch mengembalikan indikasi apakah instans jenis tertentu cocok dengan kriteria yang ditentukan dalam tanda tangan jenis. Jika ya, indikasi ini dikembalikan serta enumerator yang akan menunjukkan semua bagian tertentu dari instans jenis (sebagai simbol) yang cocok dengan kartubebas dalam jenis tanda tangan.
Metode CompareAgainst membandingkan tanda tangan jenis dengan tanda tangan jenis lain dan mengembalikan perbandingan dua tanda tangan. Hasil perbandingan yang dikembalikan adalah anggota enumerasi SignatureComparison yang didefinisikan sebagai berikut:
| Enumeran | Makna |
|---|---|
| Tidak Terkait | Tidak ada hubungan antara dua tanda tangan atau jenis yang dibandingkan. |
| Ambigu | Satu tanda tangan atau jenis membandingkan secara ambigu dengan yang lain. Untuk dua jenis tanda tangan, ini berarti bahwa ada instans jenis potensial yang dapat mencocokkan salah satu tanda tangan dengan sama baiknya. Sebagai contoh, dua jenis tanda tangan yang ditunjukkan di bawah ini ambigu. Tanda tangan 1: std::pair<*, int> Tanda tangan 2: std::pair<int,*> karena instans std::pair<int, int> jenis cocok dengan satu sama baiknya (keduanya memiliki satu konkret dan satu kecocokan kartubebas). |
| LessSpecific | Satu tanda tangan atau jenis kurang spesifik daripada yang lain. Seringkali, ini berarti bahwa tanda tangan yang kurang spesifik memiliki kartubebas di mana yang lebih spesifik memiliki jenis beton. Sebagai contoh, tanda tangan pertama di bawah ini kurang spesifik daripada yang kedua. Tanda tangan 1: std::pair<*, int> Tanda tangan 2: std::pair<int, int> karena memiliki kartubebas ( *) di mana yang kedua memiliki jenis beton (int). |
| MoreSpecific | Satu tanda tangan atau jenis lebih spesifik daripada yang lain. Seringkali, ini berarti bahwa tanda tangan yang lebih spesifik memiliki jenis beton di mana yang kurang spesifik memiliki kartubebas. Sebagai contoh, tanda tangan pertama di bawah ini lebih spesifik daripada yang kedua. Tanda tangan 1: std::pair<int, int> Tanda tangan 2: std::pair<*, int> karena memiliki jenis beton (int) di mana yang kedua memiliki kartubebas ( *). |
| Identik | Dua tanda tangan atau jenis identik. |
Lihat juga
Topik ini adalah bagian dari seri yang menjelaskan antarmuka yang dapat diakses dari C++, cara menggunakannya untuk membangun ekstensi debugger berbasis C++, dan cara menggunakan konstruksi model data lainnya (misalnya: JavaScript atau NatVis) dari ekstensi model data C++.
Gambaran Umum Model Data Debugger C++
Antarmuka C++ Model Data Debugger
Model Data Debugger C++ Antarmuka Tambahan