Útmutató: Windows API-k meghívása (Visual Basic)

A Windows API-k dinamikus csatolású kódtárak (DLL-ek), amelyek a Windows operációs rendszer részét képezik. Olyan eszközöket használ, amelyekkel feladatokat hajthat végre, amikor nehéz saját eljárásokat írni. A Windows például egy olyan függvényt biztosít, FlashWindowEx amely lehetővé teszi az alkalmazások címsorának váltakozását a világos és a sötét árnyalatok között.

A Windows API-k kódban való használatának előnye, hogy időt takaríthatnak meg a fejlesztéshez, mivel több tucat olyan hasznos függvényt tartalmaznak, amelyek már meg vannak írva és használatra várnak. A hátránya, hogy a Windows API-k használata nehéz lehet, és megbocsáthatatlan, ha a dolgok rosszul mennek.

A Windows API-k az együttműködési képesség egy speciális kategóriáját képviselik. A Windows API-k nem használnak felügyelt kódot, nem rendelkeznek beépített típuskódtárakkal, és a Visual Studióban használttól eltérő adattípusokat használnak. Ezen különbségek miatt, és mivel a Windows API-k nem COM-objektumok, a Windows API-kkal és a .NET-keretrendszerrel való együttműködés platformhívás vagy PInvoke használatával történik. A platformhívás olyan szolgáltatás, amely lehetővé teszi, hogy a felügyelt kód meghívja a DLL-ben implementált nem felügyelt függvényeket. További információ: Nem felügyelt DLL-függvények használata. A PInvoke a Visual Basicben az utasítással Declare vagy az DllImport attribútum üres eljárásra való alkalmazásával használható.

A Windows API-hívások a Visual Basic programozás fontos részét képezték a múltban, de a Visual Basic .NET-hez ritkán van szükség. Amikor csak lehetséges, a .NET-keretrendszerből származó felügyelt kódot kell használnia a feladatok elvégzéséhez a Windows API-hívások helyett. Ez az útmutató tájékoztatást nyújt azokról a helyzetekről, amikor Windows API-k használata szükséges.

Megjegyzés:

Előfordulhat, hogy a számítógép különböző neveket vagy helyeket jelenít meg a Visual Studio felhasználói felületének egyes elemeihez az alábbi utasításokban. Ezeket az elemeket a Visual Studio-kiadás és a használt beállítások határozzák meg. További információért lásd: A fejlesztői környezet személyre szabása.

API-hívások a Deklarálás használatával

A Windows API-k meghívásának leggyakoribb módja az utasítás használata Declare .

DLL-eljárás deklarálása

1. Határozza meg a meghívni kívánt függvény nevét, valamint argumentumait, argumentumtípusait és visszatérési értékét, valamint a függvényt tartalmazó DLL nevét és helyét.

   Megjegyzés:

   A Windows API-kkal kapcsolatos teljes információkért tekintse meg a Windows PLATFORM SDK API Win32 SDK dokumentációját. A Windows API-k által használt állandókkal kapcsolatos további információkért vizsgálja meg a Platform SDK-hoz tartozó fejlécfájlokat, például a Windows.h-t.

2. Nyisson meg egy új Windows-alkalmazásprojektet a Fájl menü Új elemére kattintva, majd a Project parancsra kattintva. Megjelenik a New project (Új projekt) párbeszédpanel.

3. Válassza a Windows-alkalmazást a Visual Basic-projektsablonok listájából. Megjelenik az új projekt.

4. Adja hozzá a következő Declare függvényt ahhoz az osztályhoz vagy modulhoz, amelyben a DLL-t használni szeretné:

   Declare Auto Function MBox Lib "user32.dll" Alias "MessageBox" (
       ByVal hWnd As Integer,
       ByVal txt As String,
       ByVal caption As String,
       ByVal Typ As Integer) As Integer
   

A deklarált nyilatkozat részei

Az Declare utasítás a következő elemeket tartalmazza.

Automatikus módosító

A Auto módosító arra utasítja a futtatókörnyezetet, hogy a metódusnév alapján konvertálja a sztringet a közös nyelvi futtatókörnyezeti szabályok (vagy ha meg van adva aliasnév) szerint.

Lib és Alias kulcsszavak

A kulcsszót Function követő név az a név, amelyet a program az importált függvény eléréséhez használ. Ez megegyezhet a hívandó függvény valódi nevével, vagy bármilyen érvényes eljárásnévvel, majd a Alias kulcsszóval megadhatja a hívott függvény valódi nevét.

Adja meg a Lib kulcsszót, majd a meghívni kívánt függvényt tartalmazó DLL nevét és helyét. Nem kell megadnia a Windows rendszerkönyvtárakban található fájlok elérési útját.

Akkor használja a Alias kulcsszót, ha a hívott függvény neve nem érvényes Visual Basic-eljárásnév, vagy ütközik az alkalmazás többi elemének nevével. Alias a meghívandó függvény valódi nevét jelzi.

Argumentum- és adattípus-deklarációk

Deklarálja az argumentumokat és adattípusaikat. Ez a rész kihívást jelenthet, mert a Windows által használt adattípusok nem felelnek meg a Visual Studio adattípusainak. A Visual Basic sok munkát végez az argumentumok kompatibilis adattípusokká való konvertálásával, amely a marshaling nevű folyamat. Az argumentumok rendezésének módját explicit módon szabályozhatja a MarshalAsAttributeSystem.Runtime.InteropServices névtérben definiált attribútum használatával.

Megjegyzés:

A Visual Basic korábbi verziói lehetővé tették a paraméterek deklarálását As Any, ami azt jelenti, hogy bármilyen adattípusú adatok használhatók. A Visual Basic megköveteli, hogy az összes Declare utasításhoz egy adott adattípust használjon.

Windows API-konstansok

Egyes argumentumok az állandók kombinációjai. Az útmutatóban látható API például MessageBox elfogad egy egész szám argumentumot Typ , amely az üzenetmező megjelenítését szabályozza. Ezeknek az állandóknak a numerikus értékét a WinUser.h fájlban található utasítások vizsgálatával #define határozhatja meg. A numerikus értékek általában hexadecimális értékekben jelennek meg, ezért érdemes lehet egy számológép használatával hozzáadni őket, és decimálissá alakítani. Ha például össze szeretné kapcsolni a felkiáltójelstílus MB_ICONEXCLAMATION állandóit 0x00000030 és az Igen/Nem stílus MB_YESNO 0x00000004, felveheti a számokat, és 0x00000034 vagy 52 decimális eredményt kaphat. Bár a decimális eredményt közvetlenül is használhatja, jobb, ha ezeket az értékeket állandóként deklarálja az alkalmazásban, és kombinálja őket az Or operátorral.

Állandók deklarálása Windows API-hívásokhoz

1. Tekintse meg a hívott Windows-függvény dokumentációját. Határozza meg az általa használt állandók nevét és az állandók numerikus értékeit tartalmazó .h fájl nevét.

2. A fejlécfájl (.h) tartalmának megtekintéséhez és a használt állandókhoz társított értékek megkereséséhez használjon szövegszerkesztőt, például a Jegyzettömbet. Az API például az MessageBox állandó MB_ICONQUESTION használatával jeleníti meg a kérdőjelet az üzenetmezőben. A definíció a MB_ICONQUESTION WinUser.h fájlban található, és a következőképpen jelenik meg:

   #define MB_ICONQUESTION 0x00000020L

3. Adjon hozzá egyenértékű Const utasításokat az osztályhoz vagy modulhoz, hogy ezeket az állandókat elérhetővé tegye az alkalmazás számára. Például:

   Const MB_ICONQUESTION As Integer = &H20
   Const MB_YESNO As Integer = &H4
   Const IDYES As Integer = 6
   Const IDNO As Integer = 7
   

A DLL-eljárás meghívása

1. Adjon hozzá egy gombot Button1 a projekt indítási űrlapjához, majd kattintson rá duplán a kód megtekintéséhez. Megjelenik a gomb eseménykezelője.

2. Adjon hozzá kódot az Click eseménykezelőhöz a hozzáadott gombhoz, hogy meghívja az eljárást, és adja meg a megfelelő argumentumokat:

   Private Sub Button1_Click(ByVal sender As System.Object,
       ByVal e As System.EventArgs) Handles Button1.Click
   
       ' Stores the return value.
       Dim RetVal As Integer
       RetVal = MBox(0, "Declare DLL Test", "Windows API MessageBox",
           MB_ICONQUESTION Or MB_YESNO)
   
       ' Check the return value.
       If RetVal = IDYES Then
           MsgBox("You chose Yes")
       Else
           MsgBox("You chose No")
       End If
   End Sub
   

3. Futtassa a projektet az F5 billentyű lenyomásával. Az üzenetmező az Igen és a Nem válasz gombbal is megjelenik. Kattintson valamelyikre.

Adatrendezés

A Visual Basic automatikusan konvertálja a paraméterek adattípusait, és visszaadja a Windows API-hívások értékeit, de az MarshalAs attribútum használatával explicit módon megadhatja az API által elvárt nem felügyelt adattípusokat. További információ az interop marshallingról: Interop Marshaling.

"A Deklarálás és MarshalAs attribútum használata egy API hívásban"

1. Határozza meg a meghívni kívánt függvény nevét, valamint argumentumait, adattípusait és visszatérési értékét.

2. Az MarshalAs attribútumhoz való hozzáférés egyszerűsítése érdekében adjon hozzá egy utasítást Imports az osztály vagy modul kódjának elejéhez, ahogyan az alábbi példában is látható:

   Imports System.Runtime.InteropServices
   

3. Adjon hozzá egy függvény prototípust az importált függvényhez a használt osztályhoz vagy modulhoz, és alkalmazza az MarshalAs attribútumot a paraméterekre vagy a visszatérési értékre. Az alábbi példában egy API-hívás, amely azt várja, hogy a típus void* legyen, így van átalakítva: AsAny.

   Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
       ByVal x As Short,
       <MarshalAsAttribute(UnmanagedType.AsAny)>
           ByVal o As Object)
   

API-hívások DllImport használatával

Az DllImport attribútum egy második módot kínál a függvények típuskódtárak nélküli hívására a DLL-ekben. DllImport nagyjából egyenértékű egy Declare utasítás használatával, de nagyobb ellenőrzést biztosít a függvények meghívása felett.

A legtöbb Windows API-hívással használható DllImport , ha a hívás megosztott (néha statikus) metódusra hivatkozik. Nem használhat olyan metódusokat, amelyek osztálypéldányt igényelnek. Ellentétben az Declare utasításokkal, a DllImport hívások nem használhatják az MarshalAs attribútumot.

Windows API meghívása a DllImport attribútummal

1. Nyisson meg egy új Windows-alkalmazásprojektet a Fájl menü Új elemére kattintva, majd a Project parancsra kattintva. Megjelenik a New project (Új projekt) párbeszédpanel.

2. Válassza a Windows-alkalmazást a Visual Basic-projektsablonok listájából. Megjelenik az új projekt.

3. Adjon hozzá egy gombot Button2 az indítási űrlaphoz.

4. Kattintson duplán Button2 az űrlap kódnézetének megnyitásához.

5. A DllImport egyszerűsített elérése érdekében adjon hozzá egy Imports utasítást az indító űrlap osztály kódjának tetejére.

   Imports System.Runtime.InteropServices
   

6. Deklarál egy üres függvényt az End Class űrlap utasítása előtt, és nevezze el a függvényt MoveFile.

7. Alkalmazza a Public és Shared módosítókat a függvény deklarációjára, és állítsa be a MoveFile paramétereket az alapján, hogy milyen argumentumokat használ a Windows API függvény.

   Public Shared Function MoveFile(
       ByVal src As String,
       ByVal dst As String) As Boolean
       ' Leave the body of the function empty.
   End Function
   

   A függvény bármilyen érvényes eljárásnévvel rendelkezhet; az DllImport attribútum a DLL-ben adja meg a nevet. Emellett kezeli a paraméterek együttműködési rendezését és az értékek visszaadását is, így kiválaszthatja az API által használt adattípusokhoz hasonló Visual Studio-adattípusokat.

8. Alkalmazza az DllImport attribútumot az üres függvényre. Az első paraméter a meghívni kívánt függvényt tartalmazó DLL neve és helye. Nem kell megadnia a Windows rendszerkönyvtárakban található fájlok elérési útját. A második paraméter egy elnevezett argumentum, amely megadja a függvény nevét a Windows API-ban. Ebben a példában az DllImport attribútum arra kényszeríti a hívásokat, hogy a MoveFile-et a MoveFileW-re továbbítsa a KERNEL32.DLL-ben. A MoveFileW metódus átmásolja a fájlt az elérési útról src az elérési útra dst.

   <DllImport("KERNEL32.DLL", EntryPoint:="MoveFileW", SetLastError:=True,
       CharSet:=CharSet.Unicode, ExactSpelling:=True,
       CallingConvention:=CallingConvention.StdCall)>
   Public Shared Function MoveFile(
       ByVal src As String,
       ByVal dst As String) As Boolean
       ' Leave the body of the function empty.
   End Function
   

9. Adjon hozzá kódot az Button2_Click eseménykezelőhöz a függvény meghívásához:

   Private Sub Button2_Click(ByVal sender As System.Object,
       ByVal e As System.EventArgs) Handles Button2.Click
   
       Dim RetVal As Boolean = MoveFile("c:\tmp\Test.txt", "c:\Test.txt")
       If RetVal = True Then
           MsgBox("The file was moved successfully.")
       Else
           MsgBox("The file could not be moved.")
       End If
   End Sub
   

10. Hozzon létre egy Test.txt nevű fájlt, és helyezze a merevlemez C:\Tmp könyvtárába. Szükség esetén hozza létre a Tmp-könyvtárat.

11. Nyomja le az F5 billentyűt az alkalmazás elindításához. Megjelenik a fő űrlap.

12. Kattintson a Gomb2 gombra. A "A fájl sikeresen áthelyezve" üzenet jelenik meg, ha a fájl áthelyezhető.

Lásd még

• DllImportAttribute
• MarshalAsAttribute
• Nyilatkozat deklarálása
• automatikus
• Álnév
• COM Interop
• Prototípusok létrehozása felügyelt kódban
• Delegált kezelése visszahívási függvényként