Overzicht: Windows-API's aanroepen (Visual Basic)
Windows-API's zijn DLL's (Dynamic Link Libraries) die deel uitmaken van het Windows-besturingssysteem. U gebruikt ze om taken uit te voeren wanneer het moeilijk is om gelijkwaardige procedures van uw eigen procedures te schrijven. Windows biedt bijvoorbeeld een functie met de naam FlashWindowEx
waarmee u de titelbalk voor een toepassing afwisselend kunt maken tussen lichte en donkere tinten.
Het voordeel van het gebruik van Windows-API's in uw code is dat ze ontwikkelingstijd kunnen besparen omdat ze tientallen nuttige functies bevatten die al zijn geschreven en wachten om te worden gebruikt. Het nadeel is dat Windows-API's moeilijk kunnen werken met en ongededigd zijn wanneer er iets misgaat.
Windows-API's vertegenwoordigen een speciale categorie interoperabiliteit. Windows-API's maken geen gebruik van beheerde code, hebben geen ingebouwde typebibliotheken en gebruiken gegevenstypen die verschillen van die in Visual Studio worden gebruikt. Vanwege deze verschillen en omdat Windows-API's geen COM-objecten zijn, wordt interoperabiliteit met Windows-API's en .NET Framework uitgevoerd met behulp van platform-aanroep of PInvoke. Platformoproep is een service waarmee beheerde code onbeheerde functies kan aanroepen die zijn geïmplementeerd in DLL's. Zie Onbeheerde DLL-functies gebruiken voor meer informatie. U kunt PInvoke in Visual Basic gebruiken met behulp van de Declare
instructie of het DllImport
kenmerk toepassen op een lege procedure.
Windows API-aanroepen waren een belangrijk onderdeel van het programmeren van Visual Basic in het verleden, maar zijn zelden nodig met Visual Basic .NET. Indien mogelijk moet u beheerde code van .NET Framework gebruiken om taken uit te voeren in plaats van Windows API-aanroepen. In dit scenario vindt u informatie over situaties waarin het gebruik van Windows-API's noodzakelijk is.
Notitie
Mogelijk worden op uw computer verschillende namen of locaties weergegeven voor sommige elementen van de Visual Studio-gebruikersinterface in de volgende instructies. De Visual Studio-editie die u hebt en de instellingen die u gebruikt, bepalen deze elementen. Zie Personalizing the IDE (Personalizing the IDE) voor meer informatie.
API-aanroepen met Declare
De meest voorkomende manier om Windows-API's aan te roepen, is door de Declare
instructie te gebruiken.
Een DLL-procedure declareren
Bepaal de naam van de functie die u wilt aanroepen, plus de argumenten, argumenttypen en retourwaarde, evenals de naam en locatie van de DLL die deze bevat.
Notitie
Zie de Win32 SDK-documentatie in de Windows-API voor platform-SDK voor volledige informatie over de Windows API's van Windows. Bekijk de headerbestanden zoals Windows.h die zijn opgenomen in de Platform SDK voor meer informatie over de constanten die door Windows-API's worden gebruikt.
Open een nieuw Windows-toepassingsproject door te klikken op Nieuw in het menu Bestand en vervolgens op Project te klikken. Het dialoogvenster Nieuw project wordt weergegeven.
Selecteer Windows-toepassing in de lijst met Visual Basic-projectsjablonen. Het nieuwe project wordt weergegeven.
Voeg de volgende
Declare
functie toe aan de klasse of module waarin u het DLL-bestand wilt gebruiken: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
Onderdelen van de declare-instructie
De Declare
instructie bevat de volgende elementen.
Automatische aanpassing
Met Auto
de wijzigingsfunctie wordt de runtime geïnstrueerd om de tekenreeks te converteren op basis van de naam van de methode volgens de algemene taalruntimeregels (of aliasnaam indien opgegeven).
Trefwoorden lib en alias
De naam na het Function
trefwoord is de naam die uw programma gebruikt voor toegang tot de geïmporteerde functie. Het kan hetzelfde zijn als de echte naam van de functie die u aanroept, of u kunt elke geldige procedurenaam gebruiken en vervolgens het Alias
trefwoord gebruiken om de echte naam op te geven van de functie die u aanroept.
Geef het Lib
trefwoord op, gevolgd door de naam en locatie van het DLL-bestand dat de functie bevat die u aanroept. U hoeft het pad voor bestanden in de Windows-systeemmappen niet op te geven.
Gebruik het Alias
trefwoord als de naam van de functie die u aanroept geen geldige Visual Basic-procedurenaam is of conflicteert met de naam van andere items in uw toepassing. Alias
geeft de werkelijke naam aan van de functie die wordt aangeroepen.
Declaraties voor argumenten en gegevenstypen
Declareer de argumenten en de bijbehorende gegevenstypen. Dit onderdeel kan lastig zijn omdat de gegevenstypen die door Windows worden gebruikt, niet overeenkomen met Visual Studio-gegevenstypen. Visual Basic doet veel werk voor u door argumenten te converteren naar compatibele gegevenstypen, een proces met de naam marshaling. U kunt expliciet bepalen hoe argumenten worden ge marshalld met behulp van het MarshalAsAttribute kenmerk dat is gedefinieerd in de System.Runtime.InteropServices naamruimte.
Notitie
In eerdere versies van Visual Basic kunt u parameters As Any
declareren, wat betekent dat gegevens van elk gegevenstype kunnen worden gebruikt. Visual Basic vereist dat u een specifiek gegevenstype gebruikt voor alle Declare
instructies.
Windows API-constanten
Sommige argumenten zijn combinaties van constanten. De API die in dit scenario wordt weergegeven, MessageBox
accepteert bijvoorbeeld een geheel getalargument dat bepaalt Typ
hoe het berichtvak wordt weergegeven. U kunt de numerieke waarde van deze constanten bepalen door de #define
instructies in het bestand WinUser.h te bekijken. De numerieke waarden worden over het algemeen weergegeven in hexadecimaal, dus u kunt een rekenmachine gebruiken om ze toe te voegen en te converteren naar decimaal. Als u bijvoorbeeld de constanten voor de uitroeptekenstijl MB_ICONEXCLAMATION
wilt combineren 0x00000030 en de stijl MB_YESNO
Ja/Nee 0x00000004, kunt u de getallen optellen en een resultaat krijgen van 0x00000034 of 52 decimalen. Hoewel u het decimale resultaat rechtstreeks kunt gebruiken, kunt u deze waarden beter declareren als constanten in uw toepassing en deze combineren met behulp van de Or
operator.
Constanten declareren voor Windows API-aanroepen
Raadpleeg de documentatie voor de Windows-functie die u aanroept. Bepaal de naam van de constanten die worden gebruikt en de naam van het .h-bestand dat de numerieke waarden voor deze constanten bevat.
Gebruik een teksteditor, zoals Kladblok, om de inhoud van het headerbestand (.h) weer te geven en de waarden te vinden die zijn gekoppeld aan de constanten die u gebruikt. De API gebruikt bijvoorbeeld
MessageBox
de constanteMB_ICONQUESTION
om een vraagteken weer te geven in het berichtvak. De definitie voorMB_ICONQUESTION
bevindt zich in WinUser.h en wordt als volgt weergegeven:#define MB_ICONQUESTION 0x00000020L
Voeg gelijkwaardige
Const
instructies toe aan uw klasse of module om deze constanten beschikbaar te maken voor uw toepassing. Voorbeeld:Const MB_ICONQUESTION As Integer = &H20 Const MB_YESNO As Integer = &H4 Const IDYES As Integer = 6 Const IDNO As Integer = 7
De DLL-procedure aanroepen
Voeg een knop met de naam
Button1
toe aan het opstartformulier voor uw project en dubbelklik erop om de bijbehorende code weer te geven. De gebeurtenis-handler voor de knop wordt weergegeven.Voeg code toe aan de
Click
gebeurtenis-handler voor de knop die u hebt toegevoegd, om de procedure aan te roepen en de juiste argumenten op te geven: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
Voer het project uit door op F5 te drukken. Het berichtvak wordt weergegeven met de knoppen Ja en Nee . Klik op een van beide.
Gegevens marshalling
Visual Basic converteert automatisch de gegevenstypen parameters en retourwaarden voor Windows API-aanroepen, maar u kunt het MarshalAs
kenmerk gebruiken om expliciet onbeheerde gegevenstypen op te geven die een API verwacht. Zie Interop Marshaling voor meer informatie over interop marshalling.
Declare en MarshalAs gebruiken in een API-aanroep
Bepaal de naam van de functie die u wilt aanroepen, plus de argumenten, gegevenstypen en retourwaarde.
Als u de toegang tot het
MarshalAs
kenmerk wilt vereenvoudigen, voegt u eenImports
instructie toe aan het begin van de code voor de klasse of module, zoals in het volgende voorbeeld:Imports System.Runtime.InteropServices
Voeg een functieprototype voor de geïmporteerde functie toe aan de klasse of module die u gebruikt en pas het
MarshalAs
kenmerk toe op de parameters of retourwaarde. In het volgende voorbeeld wordt een API-aanroep die verwacht dat het typevoid*
wordt ge marshalld alsAsAny
:Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" ( ByVal x As Short, <MarshalAsAttribute(UnmanagedType.AsAny)> ByVal o As Object)
API-aanroepen met DllImport
Het DllImport
kenmerk biedt een tweede manier om functies in DLL's aan te roepen zonder typebibliotheken. DllImport
is ongeveer gelijk aan het gebruik van een Declare
instructie, maar biedt meer controle over hoe functies worden aangeroepen.
U kunt de meeste Windows API-aanroepen gebruiken DllImport
zolang de aanroep verwijst naar een gedeelde (ook wel statische methode genoemd). U kunt geen methoden gebruiken waarvoor een exemplaar van een klasse is vereist. In tegenstelling tot Declare
instructies kunnen DllImport
aanroepen het MarshalAs
kenmerk niet gebruiken.
Een Windows-API aanroepen met het kenmerk DllImport
Open een nieuw Windows-toepassingsproject door te klikken op Nieuw in het menu Bestand en vervolgens op Project te klikken. Het dialoogvenster Nieuw project wordt weergegeven.
Selecteer Windows-toepassing in de lijst met Visual Basic-projectsjablonen. Het nieuwe project wordt weergegeven.
Voeg een knop toe met de naam
Button2
aan het opstartformulier.Dubbelklik om
Button2
de codeweergave voor het formulier te openen.Als u de toegang wilt
DllImport
vereenvoudigen, voegt u eenImports
instructie toe aan het begin van de code voor de opstartformulierklasse:Imports System.Runtime.InteropServices
Declareer een lege functie voorafgaand aan de
End Class
instructie voor het formulier en geef de functieMoveFile
een naam.Pas de
Public
enShared
modifiers toe op de functiedeclaratie en stel parametersMoveFile
in op basis van de argumenten die de Windows API-functie gebruikt:Public Shared Function MoveFile( ByVal src As String, ByVal dst As String) As Boolean ' Leave the body of the function empty. End Function
Uw functie kan elke geldige procedurenaam hebben; het
DllImport
kenmerk geeft de naam in de DLL. Het verwerkt ook interoperabiliteits marshalling voor de parameters en retourwaarden, zodat u Visual Studio-gegevenstypen kunt kiezen die vergelijkbaar zijn met de gegevenstypen die door de API worden gebruikt.Pas het
DllImport
kenmerk toe op de lege functie. De eerste parameter is de naam en locatie van het DLL-bestand met de functie die u aanroept. U hoeft het pad voor bestanden in de Windows-systeemmappen niet op te geven. De tweede parameter is een benoemd argument dat de naam van de functie in de Windows-API aangeeft. In dit voorbeeld dwingt hetDllImport
kenmerk aanroepen teMoveFile
worden doorgestuurdMoveFileW
in KERNEL32.DLL. Met deMoveFileW
methode wordt een bestand gekopieerd van het padsrc
naar het paddst
.<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
Voeg code toe aan de
Button2_Click
gebeurtenis-handler om de functie aan te roepen: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
Maak een bestand met de naam Test.txt en plaats het in de map C:\Tmp op uw harde schijf. Maak zo nodig de Tmp-map.
Druk op F5 om de toepassing te starten. Het hoofdformulier wordt weergegeven.
Klik op Knop2. Het bericht 'Het bestand is verplaatst' wordt weergegeven als het bestand kan worden verplaatst.