Procédure pas à pas : appel des API Windows (Visual Basic)Walkthrough: Calling Windows APIs (Visual Basic)
Les API Windows sont des bibliothèques de liens dynamiques (dll) qui font partie du système d’exploitation Windows.Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows operating system. Vous les utilisez pour effectuer des tâches lorsqu’il est difficile d’écrire vos propres procédures équivalentes.You use them to perform tasks when it is difficult to write equivalent procedures of your own. Par exemple, Windows fournit une fonction nommée FlashWindowEx
qui vous permet de faire en sorte que la barre de titre d’une application alterne entre les tons clairs et foncés.For example, Windows provides a function named FlashWindowEx
that lets you make the title bar for an application alternate between light and dark shades.
L’avantage de l’utilisation des API Windows dans votre code est qu’ils peuvent économiser du temps de développement, car ils contiennent des dizaines de fonctions utiles qui sont déjà écrites et en attente d’utilisation.The advantage of using Windows APIs in your code is that they can save development time because they contain dozens of useful functions that are already written and waiting to be used. L’inconvénient est que les API Windows peuvent être difficiles à utiliser et Unforgiving en cas de problème.The disadvantage is that Windows APIs can be difficult to work with and unforgiving when things go wrong.
Les API Windows représentent une catégorie spéciale d’interopérabilité.Windows APIs represent a special category of interoperability. Les API Windows n’utilisent pas de code managé, n’ont pas de bibliothèques de types intégrées et utilisent des types de données différents de ceux utilisés avec Visual Studio.Windows APIs do not use managed code, do not have built-in type libraries, and use data types that are different than those used with Visual Studio. En raison de ces différences, et parce que les API Windows ne sont pas des objets COM, l’interopérabilité avec les API Windows et le .NET Framework est effectuée à l’aide de l’appel de code non managé ou de PInvoke.Because of these differences, and because Windows APIs are not COM objects, interoperability with Windows APIs and the .NET Framework is performed using platform invoke, or PInvoke. L’appel de code non managé est un service qui permet au code managé d’appeler des fonctions non managées implémentées dans des dll.Platform invoke is a service that enables managed code to call unmanaged functions implemented in DLLs. Pour plus d’informations, consultez consommation de fonctions DLL non managées.For more information, see Consuming Unmanaged DLL Functions. Vous pouvez utiliser PInvoke dans Visual Basic à l’aide de l' Declare
instruction ou en appliquant l' DllImport
attribut à une procédure vide.You can use PInvoke in Visual Basic by using either the Declare
statement or applying the DllImport
attribute to an empty procedure.
Les appels d’API Windows étaient un élément important de la programmation de Visual Basic, mais ils sont rarement nécessaires avec Visual Basic .NET.Windows API calls were an important part of Visual Basic programming in the past, but are seldom necessary with Visual Basic .NET. Dans la mesure du possible, vous devez utiliser du code managé à partir de la .NET Framework pour effectuer des tâches, et non des appels d’API Windows.Whenever possible, you should use managed code from the .NET Framework to perform tasks, instead of Windows API calls. Cette procédure pas à pas fournit des informations pour les situations dans lesquelles l’utilisation des API Windows est nécessaire.This walkthrough provides information for those situations in which using Windows APIs is necessary.
Notes
Il est possible que pour certains des éléments de l'interface utilisateur de Visual Studio, votre ordinateur affiche des noms ou des emplacements différents de ceux indiqués dans les instructions suivantes.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. L'édition de Visual Studio dont vous disposez et les paramètres que vous utilisez déterminent ces éléments.The Visual Studio edition that you have and the settings that you use determine these elements. Pour plus d’informations, consultez Personnalisation de l’IDE.For more information, see Personalizing the IDE.
Appels d’API à l’aide de DECLAREAPI Calls Using Declare
La méthode la plus courante pour appeler des API Windows consiste à utiliser l' Declare
instruction.The most common way to call Windows APIs is by using the Declare
statement.
Pour déclarer une procédure DLLTo declare a DLL procedure
Déterminez le nom de la fonction que vous souhaitez appeler, plus ses arguments, types d’arguments et valeur de retour, ainsi que le nom et l’emplacement de la DLL qui la contient.Determine the name of the function you want to call, plus its arguments, argument types, and return value, as well as the name and location of the DLL that contains it.
Notes
Pour obtenir des informations complètes sur les API Windows, consultez la documentation du kit de développement logiciel (SDK) Win32 dans l’API Windows du kit de développement Platform SDK.For complete information about the Windows APIs, see the Win32 SDK documentation in the Platform SDK Windows API. Pour plus d’informations sur les constantes utilisées par les API Windows, examinez les fichiers d’en-tête, tels que Windows. h, inclus dans le kit de développement Platform SDK.For more information about the constants that Windows APIs use, examine the header files such as Windows.h included with the Platform SDK.
Ouvrez un nouveau projet d’application Windows en cliquant sur nouveau dans le menu fichier , puis sur projet.Open a new Windows Application project by clicking New on the File menu, and then clicking Project. La boîte de dialogue Nouveau projet apparaît.The New Project dialog box appears.
Sélectionnez application Windows dans la liste des modèles de projet de Visual Basic.Select Windows Application from the list of Visual Basic project templates. Le nouveau projet s’affiche.The new project is displayed.
Ajoutez la
Declare
fonction suivante à la classe ou au module dans lequel vous souhaitez utiliser la dll :Add the followingDeclare
function either to the class or module in which you want to use the DLL: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
Parties de l’instruction DECLAREParts of the Declare Statement
L' Declare
instruction comprend les éléments suivants.The Declare
statement includes the following elements.
Modificateur automatiqueAuto modifier
Le Auto
modificateur indique au runtime de convertir la chaîne en fonction du nom de la méthode en fonction des règles de Common Language Runtime (ou du nom d’alias, si elle est spécifiée).The Auto
modifier instructs the runtime to convert the string based on the method name according to common language runtime rules (or alias name if specified).
Mots clés lib et aliasLib and Alias keywords
Le nom qui suit le Function
mot clé est le nom que votre programme utilise pour accéder à la fonction importée.The name following the Function
keyword is the name your program uses to access the imported function. Il peut être identique au nom réel de la fonction que vous appelez, ou vous pouvez utiliser n’importe quel nom de procédure valide, puis utiliser le Alias
mot clé pour spécifier le nom réel de la fonction que vous appelez.It can be the same as the real name of the function you are calling, or you can use any valid procedure name and then employ the Alias
keyword to specify the real name of the function you are calling.
Spécifiez le Lib
mot clé, suivi du nom et de l’emplacement de la dll qui contient la fonction que vous appelez.Specify the Lib
keyword, followed by the name and location of the DLL that contains the function you are calling. Vous n’avez pas besoin de spécifier le chemin d’accès pour les fichiers situés dans les répertoires système Windows.You do not need to specify the path for files located in the Windows system directories.
Utilisez le Alias
mot clé si le nom de la fonction que vous appelez n’est pas un nom de procédure Visual Basic valide, ou est en conflit avec le nom d’autres éléments dans votre application.Use the Alias
keyword if the name of the function you are calling is not a valid Visual Basic procedure name, or conflicts with the name of other items in your application. Alias
indique le nom réel de la fonction appelée.Alias
indicates the true name of the function being called.
Déclarations de type d’argument et de donnéesArgument and Data Type Declarations
Déclarez les arguments et leurs types de données.Declare the arguments and their data types. Cette partie peut être complexe, car les types de données utilisés par Windows ne correspondent pas aux types de données Visual Studio.This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic effectue un grand nombre de tâches pour vous en convertissant les arguments en types de données compatibles, un processus appelé marshaling.Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called marshaling. Vous pouvez contrôler explicitement la manière dont les arguments sont marshalés à l’aide de l' MarshalAsAttribute attribut défini dans l' System.Runtime.InteropServices espace de noms.You can explicitly control how arguments are marshaled by using the MarshalAsAttribute attribute defined in the System.Runtime.InteropServices namespace.
Notes
Les versions précédentes de Visual Basic vous permettaient de déclarer des paramètres As Any
, ce qui signifie que les données de n’importe quel type de données pouvaient être utilisées.Previous versions of Visual Basic allowed you to declare parameters As Any
, meaning that data of any data type could be used. Visual Basic requiert l’utilisation d’un type de données spécifique pour toutes les Declare
instructions.Visual Basic requires that you use a specific data type for all Declare
statements.
Constantes de l’API WindowsWindows API Constants
Certains arguments sont des combinaisons de constantes.Some arguments are combinations of constants. Par exemple, l' MessageBox
API illustrée dans cette procédure pas à pas accepte un argument entier appelé Typ
qui contrôle le mode d’affichage de la boîte de message.For example, the MessageBox
API shown in this walkthrough accepts an integer argument called Typ
that controls how the message box is displayed. Vous pouvez déterminer la valeur numérique de ces constantes en examinant les #define
instructions dans le fichier winuser. h.You can determine the numeric value of these constants by examining the #define
statements in the file WinUser.h. Les valeurs numériques sont généralement affichées au format hexadécimal. vous pouvez donc utiliser une calculatrice pour les ajouter et les convertir au format décimal.The numeric values are generally shown in hexadecimal, so you may want to use a calculator to add them and convert to decimal. Par exemple, si vous souhaitez combiner les constantes pour le style d’exclamation MB_ICONEXCLAMATION
0x00000030 et le style Yes/No MB_YESNO
0x00000004, vous pouvez ajouter les nombres et obtenir le résultat 0x00000034, ou 52 décimal.For example, if you want to combine the constants for the exclamation style MB_ICONEXCLAMATION
0x00000030 and the Yes/No style MB_YESNO
0x00000004, you can add the numbers and get a result of 0x00000034, or 52 decimal. Bien que vous puissiez utiliser le résultat décimal directement, il est préférable de déclarer ces valeurs en tant que constantes dans votre application et de les combiner à l’aide de l' Or
opérateur.Although you can use the decimal result directly, it is better to declare these values as constants in your application and combine them using the Or
operator.
Pour déclarer des constantes pour les appels d’API WindowsTo declare constants for Windows API calls
Consultez la documentation de la fonction Windows que vous appelez.Consult the documentation for the Windows function you are calling. Déterminez le nom des constantes qu’il utilise et le nom du fichier. h qui contient les valeurs numériques de ces constantes.Determine the name of the constants it uses and the name of the .h file that contains the numeric values for these constants.
Utilisez un éditeur de texte, tel que le bloc-notes, pour afficher le contenu du fichier d’en-tête (. h) et rechercher les valeurs associées aux constantes que vous utilisez.Use a text editor, such as Notepad, to view the contents of the header (.h) file, and find the values associated with the constants you are using. Par exemple, l'
MessageBox
API utilise la constanteMB_ICONQUESTION
pour afficher un point d’interrogation dans la boîte de message.For example, theMessageBox
API uses the constantMB_ICONQUESTION
to show a question mark in the message box. La définition deMB_ICONQUESTION
est dans winuser. h et se présente comme suit :The definition forMB_ICONQUESTION
is in WinUser.h and appears as follows:#define MB_ICONQUESTION 0x00000020L
Ajoutez
Const
des instructions équivalentes à votre classe ou module pour rendre ces constantes disponibles pour votre application.Add equivalentConst
statements to your class or module to make these constants available to your application. Par exemple :For example:Const MB_ICONQUESTION As Integer = &H20 Const MB_YESNO As Integer = &H4 Const IDYES As Integer = 6 Const IDNO As Integer = 7
Pour appeler la procédure DLLTo call the DLL procedure
Ajoutez un bouton nommé
Button1
au formulaire de démarrage de votre projet, puis double-cliquez dessus pour afficher son code.Add a button namedButton1
to the startup form for your project, and then double-click it to view its code. Le gestionnaire d’événements du bouton s’affiche.The event handler for the button is displayed.Ajoutez du code au
Click
Gestionnaire d’événements pour le bouton que vous avez ajouté, pour appeler la procédure et fournir les arguments appropriés :Add code to theClick
event handler for the button you added, to call the procedure and provide the appropriate arguments: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
Exécutez le projet en appuyant sur F5.Run the project by pressing F5. La boîte de message s’affiche avec les boutons de réponse Oui et non .The message box is displayed with both Yes and No response buttons. Cliquez sur l’un des deux.Click either one.
Marshaling de donnéesData Marshaling
Visual Basic convertit automatiquement les types de données des paramètres et des valeurs de retour pour les appels d’API Windows, mais vous pouvez utiliser l' MarshalAs
attribut pour spécifier explicitement les types de données non managés attendus par une API.Visual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the MarshalAs
attribute to explicitly specify unmanaged data types that an API expects. Pour plus d’informations sur le marshaling d’interopérabilité, consultez marshaling d’interopérabilité.For more information about interop marshaling, see Interop Marshaling.
Pour utiliser DECLARE et MarshalAs dans un appel d’APITo use Declare and MarshalAs in an API call
Déterminez le nom de la fonction que vous souhaitez appeler, ainsi que ses arguments, les types de données et la valeur de retour.Determine the name of the function you want to call, plus its arguments, data types, and return value.
Pour simplifier l’accès à l'
MarshalAs
attribut, ajoutez uneImports
instruction en haut du code pour la classe ou le module, comme dans l’exemple suivant :To simplify access to theMarshalAs
attribute, add anImports
statement to the top of the code for the class or module, as in the following example:Imports System.Runtime.InteropServices
Ajoutez un prototype de fonction pour la fonction importée à la classe ou au module que vous utilisez, puis appliquez l'
MarshalAs
attribut aux paramètres ou à la valeur de retour.Add a function prototype for the imported function to the class or module you are using, and apply theMarshalAs
attribute to the parameters or return value. Dans l’exemple suivant, un appel d’API qui attend le typevoid*
est marshalé en tant queAsAny
:In the following example, an API call that expects the typevoid*
is marshaled asAsAny
:Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" ( ByVal x As Short, <MarshalAsAttribute(UnmanagedType.AsAny)> ByVal o As Object)
Appels d’API à l’aide de DllImportAPI Calls Using DllImport
L' DllImport
attribut fournit une deuxième méthode pour appeler des fonctions dans des dll sans bibliothèques de types.The DllImport
attribute provides a second way to call functions in DLLs without type libraries. DllImport
est à peu près équivalent à l’utilisation d’une Declare
instruction, mais offre davantage de contrôle sur la façon dont les fonctions sont appelées.DllImport
is roughly equivalent to using a Declare
statement but provides more control over how functions are called.
Vous pouvez utiliser DllImport
avec la plupart des appels d’API Windows tant que l’appel fait référence à une méthode partagée (parfois appelée statique).You can use DllImport
with most Windows API calls as long as the call refers to a shared (sometimes called static) method. Vous ne pouvez pas utiliser de méthodes qui requièrent une instance d’une classe.You cannot use methods that require an instance of a class. Contrairement aux Declare
instructions, DllImport
les appels ne peuvent pas utiliser l' MarshalAs
attribut.Unlike Declare
statements, DllImport
calls cannot use the MarshalAs
attribute.
Pour appeler une API Windows à l’aide de l’attribut DllImportTo call a Windows API using the DllImport attribute
Ouvrez un nouveau projet d’application Windows en cliquant sur nouveau dans le menu fichier , puis sur projet.Open a new Windows Application project by clicking New on the File menu, and then clicking Project. La boîte de dialogue Nouveau projet apparaît.The New Project dialog box appears.
Sélectionnez application Windows dans la liste des modèles de projet de Visual Basic.Select Windows Application from the list of Visual Basic project templates. Le nouveau projet s’affiche.The new project is displayed.
Ajoutez un bouton nommé
Button2
au formulaire de démarrage.Add a button namedButton2
to the startup form.Double-cliquez
Button2
pour ouvrir le mode Code du formulaire.Double-clickButton2
to open the code view for the form.Pour simplifier l’accès à
DllImport
, ajoutez uneImports
instruction en haut du code pour la classe Startup Form :To simplify access toDllImport
, add anImports
statement to the top of the code for the startup form class:Imports System.Runtime.InteropServices
Déclarez une fonction vide avant l'
End Class
instruction pour le formulaire et nommez la fonctionMoveFile
.Declare an empty function preceding theEnd Class
statement for the form, and name the functionMoveFile
.Appliquez les
Public
Shared
modificateurs et à la déclaration de fonction et définissez les paramètres pourMoveFile
en fonction des arguments que la fonction API Windows utilise :Apply thePublic
andShared
modifiers to the function declaration and set parameters forMoveFile
based on the arguments the Windows API function uses:Public Shared Function MoveFile( ByVal src As String, ByVal dst As String) As Boolean ' Leave the body of the function empty. End Function
Votre fonction peut avoir n’importe quel nom de procédure valide ; l'
DllImport
attribut spécifie le nom dans la dll.Your function can have any valid procedure name; theDllImport
attribute specifies the name in the DLL. Il gère également le marshaling d’interopérabilité pour les paramètres et les valeurs de retour. vous pouvez donc choisir des types de données Visual Studio similaires aux types de données utilisés par l’API.It also handles interoperability marshaling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses.Appliquez l'
DllImport
attribut à la fonction vide.Apply theDllImport
attribute to the empty function. Le premier paramètre est le nom et l’emplacement de la DLL contenant la fonction que vous appelez.The first parameter is the name and location of the DLL containing the function you are calling. Vous n’avez pas besoin de spécifier le chemin d’accès pour les fichiers situés dans les répertoires système Windows.You do not need to specify the path for files located in the Windows system directories. Le deuxième paramètre est un argument nommé qui spécifie le nom de la fonction dans l’API Windows.The second parameter is a named argument that specifies the name of the function in the Windows API. Dans cet exemple, l'DllImport
attribut force les appels à àMoveFile
être transmis àMoveFileW
dans KERNEL32.DLL.In this example, theDllImport
attribute forces calls toMoveFile
to be forwarded toMoveFileW
in KERNEL32.DLL. LaMoveFileW
méthode copie un fichier à partir du chemin d’accèssrc
vers le chemin d’accèsdst
.TheMoveFileW
method copies a file from the pathsrc
to the pathdst
.<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
Ajoutez du code au
Button2_Click
Gestionnaire d’événements pour appeler la fonction :Add code to theButton2_Click
event handler to call the function: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
Créez un fichier nommé Test.txt et placez-le dans le répertoire C:\Tmp sur votre disque dur.Create a file named Test.txt and place it in the C:\Tmp directory on your hard drive. Créez le répertoire tmp si nécessaire.Create the Tmp directory if necessary.
Appuyez sur F5 pour démarrer l'application.Press F5 to start the application. Le formulaire principal s’affiche.The main form appears.
Cliquez sur button2.Click Button2. Le message « le fichier a été déplacé avec succès » s’affiche si le fichier peut être déplacé.The message "The file was moved successfully" is displayed if the file can be moved.