Procédure pas à pas : appel des API Windows (Visual Basic)

Les API Windows sont des bibliothèques de liens dynamiques (DLL) qui font partie du système d’exploitation Windows. Vous les utilisez pour effectuer des tâches lorsqu’il est difficile d’écrire vos propres procédures équivalentes. Par exemple, Windows fournit une fonction nommée FlashWindowEx qui vous permet d’alterner la barre de titre d’une application entre les nuances claires et sombres.

L’avantage de l’utilisation des API Windows dans votre code est qu’elles peuvent gagner du temps de développement, car elles contiennent des dizaines de fonctions utiles qui sont déjà écrites et en attente d’être utilisées. L’inconvénient est que les API Windows peuvent être difficiles à utiliser et impitoyables en cas de problème.

Les API Windows représentent une catégorie spéciale d’interopérabilité. 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. En raison de ces différences et du fait 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 plateforme ou de PInvoke. L’appel de plateforme est un service qui permet au code managé d’appeler des fonctions non managées implémentées dans des DLL. Pour plus d’informations, consultez Consommation de fonctions DLL non managées. Vous pouvez utiliser PInvoke en Visual Basic en utilisant l’instruction Declare ou en appliquant l’attribut DllImport à une procédure vide.

Les appels d’API Windows ont été une partie importante de la programmation Visual Basic dans le passé, mais sont rarement nécessaires avec Visual Basic .NET. Dans la mesure du possible, vous devez utiliser du code managé à partir du .NET Framework pour effectuer des tâches, au lieu d’appels d’API Windows. Cette procédure pas à pas fournit des informations sur les situations dans lesquelles l’utilisation des API Windows est nécessaire.

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. L'édition de Visual Studio dont vous disposez et les paramètres que vous utilisez déterminent ces éléments. Pour plus d’informations, consultez Personnalisation de l’IDE.

Appels d’API à l’aide de Declare

La façon la plus courante d’appeler des API Windows consiste à utiliser l’instruction Declare .

Pour déclarer une procédure DLL

  1. Déterminez le nom de la fonction que vous souhaitez appeler, ainsi que ses arguments, ses types d’arguments et sa valeur de retour, ainsi que le nom et l’emplacement de la DLL qui la contient.

    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 logiciel (SDK) de plateforme. 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 logiciel (SDK) de plateforme.

  2. Ouvrez un nouveau projet d’application Windows en cliquant sur Nouveau dans le menu Fichier , puis sur Projet. La boîte de dialogue Nouveau projet apparaît.

  3. Sélectionnez Application Windows dans la liste des modèles de projet Visual Basic. Le nouveau projet s’affiche.

  4. Ajoutez la fonction suivante Declare à la classe ou au module dans lequel vous souhaitez utiliser la 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 Declare

L’instruction Declare inclut les éléments suivants.

Modificateur automatique

Le Auto modificateur indique au runtime de convertir la chaîne en fonction du nom de la méthode en fonction des règles common language runtime (ou du nom d’alias si spécifié).

Mots clés Lib et Alias

Le nom qui suit le Function mot clé est le nom que votre programme utilise pour accéder à la fonction importée. 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.

Spécifiez le Lib mot clé, suivi du nom et de l’emplacement de la DLL qui contient la fonction que vous appelez. 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.

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 de votre application. Alias indique le vrai nom de la fonction appelée.

Déclarations d’argument et de type de données

Déclarez les arguments et leurs types de données. Cette partie peut être difficile, car les types de données utilisés par Windows ne correspondent pas aux types de données Visual Studio. Visual Basic effectue une grande partie du travail pour vous en convertissant des arguments en types de données compatibles, un processus appelé marshaling. Vous pouvez contrôler explicitement la façon dont les arguments sont marshalés à l’aide de l’attribut MarshalAsAttribute défini dans l’espace de System.Runtime.InteropServices noms.

Notes

Les versions précédentes de Visual Basic vous permettaient de déclarer des paramètres As Any, ce qui signifie que des données de n’importe quel type de données pouvaient être utilisées. Visual Basic nécessite l’utilisation d’un type de données spécifique pour toutes les Declare instructions.

Constantes de l’API Windows

Certains arguments sont des combinaisons de constantes. Par exemple, l’API MessageBox présentée dans cette procédure pas à pas accepte un argument entier appelé Typ qui contrôle la façon dont la zone de message est affichée. Vous pouvez déterminer la valeur numérique de ces constantes en examinant les #define instructions dans le fichier WinUser.h. Les valeurs numériques étant généralement affichées en hexadécimal, vous pouvez utiliser une calculatrice pour les ajouter et les convertir en décimales. Par exemple, si vous souhaitez combiner les constantes du style MB_ICONEXCLAMATION d’exclamation 0x00000030 et le style MB_YESNO Oui/Non 0x00000004, vous pouvez ajouter les nombres et obtenir un résultat de 0x00000034, ou 52 décimaux. Bien que vous puissiez utiliser directement le résultat décimal, 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’opérateur Or .

Pour déclarer des constantes pour les appels d’API Windows
  1. Consultez la documentation relative à la fonction Windows que vous appelez. Déterminez le nom des constantes qu’il utilise et le nom du fichier .h qui contient les valeurs numériques de ces constantes.

  2. 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. Par exemple, l’API MessageBox utilise la constante MB_ICONQUESTION pour afficher un point d’interrogation dans la zone de message. La définition de MB_ICONQUESTION est dans WinUser.h et s’affiche comme suit :

    #define MB_ICONQUESTION 0x00000020L

  3. Ajoutez des instructions équivalentes Const à votre classe ou module pour rendre ces constantes disponibles pour votre application. Par exemple :

    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 DLL
  1. Ajoutez un bouton nommé Button1 au formulaire de démarrage de votre projet, puis double-cliquez dessus pour afficher son code. Le gestionnaire d’événements du bouton s’affiche.

  2. Ajoutez du Click code au gestionnaire d’événements pour le bouton que vous avez ajouté, pour appeler la procédure et fournir les arguments appropriés :

    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. Exécutez le projet en appuyant sur F5. La zone de message s’affiche avec les boutons De réponse Oui et Non . Cliquez sur l’une ou l’autre.

Marshaling des données

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’attribut MarshalAs pour spécifier explicitement les types de données non managés attendus par une API. Pour plus d’informations sur le marshaling d’interopérabilité, consultez Marshaling interop.

Pour utiliser Declare et MarshalAs dans un appel d’API
  1. Déterminez le nom de la fonction que vous souhaitez appeler, ainsi que ses arguments, types de données et valeur de retour.

  2. Pour simplifier l’accès à l’attribut MarshalAs , ajoutez une Imports instruction en haut du code pour la classe ou le module, comme dans l’exemple suivant :

    Imports System.Runtime.InteropServices
    
  3. Ajoutez un prototype de fonction pour la fonction importée à la classe ou au module que vous utilisez et appliquez l’attribut MarshalAs aux paramètres ou à la valeur de retour. Dans l’exemple suivant, un appel d’API qui attend le type void* est marshalé comme AsAny:

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

Appels d’API à l’aide de dllImport

L’attribut DllImport fournit un deuxième moyen d’appeler des fonctions dans des DLL sans bibliothèques de types. DllImport équivaut à peu près à l’utilisation d’une Declare instruction, mais offre un contrôle accru sur la façon dont les fonctions sont appelées.

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). Vous ne pouvez pas utiliser de méthodes qui nécessitent une instance d’une classe. Contrairement aux Declare instructions, DllImport les appels ne peuvent pas utiliser l’attribut MarshalAs .

Pour appeler une API Windows à l’aide de l’attribut DllImport

  1. Ouvrez un nouveau projet d’application Windows en cliquant sur Nouveau dans le menu Fichier , puis sur Projet. La boîte de dialogue Nouveau projet apparaît.

  2. Sélectionnez Application Windows dans la liste des modèles de projet Visual Basic. Le nouveau projet s’affiche.

  3. Ajoutez un bouton nommé Button2 au formulaire de démarrage.

  4. Double-cliquez pour Button2 ouvrir l’affichage code du formulaire.

  5. Pour simplifier l’accès à DllImport, ajoutez une Imports instruction en haut du code pour la classe de formulaire de démarrage :

    Imports System.Runtime.InteropServices
    
  6. Déclarez une fonction vide précédant l’instruction End Class pour le formulaire et nommez la fonction MoveFile.

  7. Appliquez les Public modificateurs et Shared à la déclaration de fonction et définissez les paramètres pour en MoveFile fonction des arguments utilisés par la fonction API Windows :

    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’attribut DllImport spécifie le nom dans la 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.

  8. Appliquez l’attribut DllImport à la fonction vide. Le premier paramètre est le nom et l’emplacement de la DLL contenant la fonction que vous appelez. 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. Le deuxième paramètre est un argument nommé qui spécifie le nom de la fonction dans l’API Windows. Dans cet exemple, l’attribut force les DllImport appels à MoveFile être transférés vers MoveFileW dans KERNEL32.DLL. La MoveFileW méthode copie un fichier à partir du chemin d’accès src au chemin d’accès 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. Ajoutez du code au gestionnaire d’événements Button2_Click pour appeler la fonction :

    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. Créez un fichier nommé Test.txt et placez-le dans le répertoire C:\Tmp sur votre disque dur. Créez le répertoire Tmp si nécessaire.

  11. Appuyez sur F5 pour démarrer l'application. Le formulaire principal s’affiche.

  12. Cliquez sur Bouton2. Le message « Le fichier a été déplacé avec succès » s’affiche si le fichier peut être déplacé.

Voir aussi