Procédure pas à pas : appel des API Windows

Article
09/12/2008

Mise à jour : novembre 2007

Les API Windows sont des bibliothèques de liens dynamiques (DLL, Dynamic-Link Libraries) qui font partie intégrante du système d'exploitation Windows. Elles permettent d'effectuer des tâches lorsqu'il s'avère difficile d'écrire des procédures équivalentes. Par exemple, Windows propose une fonction nommée FlashWindowEx qui vous permet de varier l'aspect de la barre de titre d'une application entre des tons clairs et foncés.

L'avantage de l'utilisation d'API Windows dans votre code réside dans le gain de temps de développement, car elles contiennent des douzaines de fonctions utiles déjà écrites et prêtes à être utilisées. L'inconvénient des API Windows est qu'elles peuvent être complexes à utiliser et implacables lorsqu'une opération se déroule mal.

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 comme les API Windows ne sont pas des objets COM, l'interopérabilité avec les API Windows et le .NET Framework est exécutée via un appel de plate-forme, ou PInvoke. L'appel de plate-forme est un service qui permet à du code managé d'appeler des fonctions non managées implémentées dans les DLL. Pour plus d'informations, consultez Consommation de fonctions DLL non managées. Vous pouvez employer PInvoke en Visual Basic en utilisant l'instruction Declare ou en appliquant l'attribut DllImport à une procédure vide.

Les appels API Windows représentaient auparavant une part importante de la programmation Visual Basic, mais sont rarement nécessaires avec Visual Basic 2005. Chaque fois que cela est possible, vous devez utiliser du code managé à partir du .NET Framework plutôt que les appels API Windows pour effectuer des tâches. Cette procédure pas à pas fournit des informations pour les cas dans lesquels l'utilisation des API Windows est nécessaire.

Remarque :
Selon vos paramètres actifs ou votre édition, les boîtes de dialogue et les commandes de menu que vous voyez peuvent différer de celles qui sont décrites dans l'aide. Pour modifier vos paramètres, choisissez Importation et exportation de paramètres dans le menu Outils. Pour plus d'informations, consultez Paramètres Visual Studio.

Appels API via Declare

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

Pour déclarer une procédure DLL

Identifiez le nom de la fonction que vous voulez appeler, ses arguments, types d'arguments et valeur de retour, ainsi que le nom et l'emplacement de la DLL qui la contient.

Remarque :
Pour plus d'informations sur les API Windows, consultez la documentation du kit Win32 SDK dans les API Windows du kit de développement Platform SDK. Pour plus d'informations sur les constantes utilisées par les API Windows, examinez les fichiers d'en-tête, tels que Windows.h, fournis avec le Kit de développement Platform SDK.

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 s'affiche.
Sélectionnez Application Windows dans la liste des modèles de projet Visual Basic. Le nouveau projet s'affiche.

Ajoutez la fonction Declare suivante à 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 comprend les éléments suivants.

Modificateur Auto

Le modificateur Auto indique au runtime de convertir la chaîne basée sur le nom de la méthode en fonction des règles du Common Language Runtime (ou du nom d'alias, s'il est indiqué).

Mots clés Lib et Alias

Le nom qui suit le mot clé Function est celui que votre programme utilise pour accéder à la fonction importée. Il peut s'agir du nom réel de la fonction que vous appelez, ou vous pouvez utiliser tout nom de procédure valide, puis le mot clé Alias pour indiquer le nom réel de cette fonction.

Spécifiez le mot clé Lib suivi du nom et de l'emplacement de la DLL qui contient la fonction que vous appelez. Vous n'avez pas besoin d'indiquer le chemin d'accès des fichiers situés dans les répertoires système Windows.

Utilisez le mot clé Alias 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 véritable nom de cette fonction.

Déclaration du type de données et des arguments

Déclarez les arguments et leurs types de données. Cette partie peut être complexe, car les types de données utilisés dans Windows ne correspondent pas aux types de données Visual Studio. Visual Basic effectue la plupart des tâches à votre place en convertissant des arguments en types de données compatibles, processus appelé marshaling. Vous pouvez contrôler de manière explicite la façon dont les arguments sont marshalés en utilisant l'attribut MarshalAsAttribute défini dans l'espace de noms System.Runtime.InteropServices.

Remarque :
Les versions antérieures de Visual Basic vous ont permis de déclarer des paramètres As Any, ce qui signifie que les données de n'importe quel type de données pourraient être utilisées. Visual Basic suppose que vous utilisez un type de données spécifique pour toutes les instructions Declare.

Constantes API Windows

Certains arguments sont des combinaisons de constantes. Par exemple, l'API MessageBox illustrée dans cette procédure pas à pas accepte un argument de type nombre entier appelé Typ qui contrôle le mode d'affichage du message. Vous pouvez déterminer la valeur numérique de ces constantes par l'examen des instructions #define dans le fichier WinUser.h. Les valeurs numériques sont généralement affichées au format hexadécimal. Par conséquent, vous pouvez utiliser une calculatrice pour les ajouter et les convertir au format décimal. Par exemple, si vous voulez combiner les constantes pour le style exclamation MB_ICONEXCLAMATION 0x00000030 et le style Oui/Non MB_YESNO 0x00000004, vous pouvez ajouter les nombres et obtenir un résultat de 0x00000034, ou 52 décimales. Même si vous pouvez utiliser directement le résultat en décimales, il est conseillé 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 API Windows

Consultez la documentation pour la fonction Windows que vous appelez. Déterminez le nom des constantes utilisées et le nom du fichier .h qui contient les valeurs numériques de ces constantes.
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 le message. La définition de MB_ICONQUESTION se trouve dans WinUser.h et est définie comme suit :

#define MB_ICONQUESTION 0x00000020L
Ajoutez des instructions Const équivalentes pour votre classe ou votre module pour rendre ces constantes disponibles pour l'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

Ajoutez un bouton nommé Button1 au formulaire de départ de votre projet, puis double-cliquez dessus pour afficher son code. Le gestionnaire d'événements du bouton s'affiche.

Ajoutez du code au gestionnaire d'événements Click pour le bouton que vous avez ajouté pour appeler la procédure et indiquez 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

Exécutez le projet en appuyant sur F5. Le message s'affiche avec les deux boutons de réponse Oui et Non. Cliquez sur l'un des deux.

Marshaling de données

Visual Basic convertit automatiquement les types de données des paramètres et valeurs de retour pour les appels API Windows, mais vous pouvez utiliser l'attribut MarshalAs pour indiquer de façon explicite les types de données non managés attendus par une API. Pour plus d'informations sur le marshaling d'interopérabilité, consultez Marshaling d'interopérabilité.

Pour utiliser Declare et MarshalAs dans un appel API

Déterminez le nom de la fonction à appeler, ses arguments, types de données et valeur de retour.
Pour simplifier l'accès à l'attribut MarshalAs, ajoutez une instruction Imports en haut du code de la classe ou du module, comme dans l'exemple suivant :
```
Imports System.Runtime.InteropServices
```
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 API qui attend le type void* est marshalé en tant que AsAny :
```
Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" ( _
    ByVal x As Short, _
    <MarshalAsAttribute(UnmanagedType.AsAny)> _
        ByVal o As Object)
```

Appels API via DllImport

L'attribut DllImport propose une seconde manière d'appeler des fonctions dans les DLL sans bibliothèque de types. DllImport équivaut approximativement à une instruction Declare, mais fournit plus de contrôle sur la manière d'appeler les fonctions.

Vous pouvez utiliser DllImport avec la plupart des appels API Windows tant que l'appel fait référence à une méthode partagée (parfois appelée statique). Vous ne pouvez pas utiliser des méthodes qui nécessitent une instance d'une classe. À la différence des instructions Declare, les appels DllImport ne peuvent pas utiliser l'attribut MarshalAs.

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

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 s'affiche.
Sélectionnez Application Windows dans la liste des modèles de projet Visual Basic. Le nouveau projet s'affiche.
Ajoutez un bouton nommé Button2 au formulaire de départ.
Double-cliquez sur Button2 pour ouvrir le mode code pour le formulaire.
Pour simplifier l'accès à DllImport, ajoutez une instruction Imports en haut du code de la classe du formulaire de départ :
```
Imports System.Runtime.InteropServices
```
Déclarez une fonction vide qui précède l'instruction End Class pour le formulaire et affectez à la fonction le nom MoveFile.
Appliquez les modificateurs Public et Shared à la déclaration de fonction et définissez des paramètres pour MoveFile en fonction des arguments que la fonction API Windows utilise :
```
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 porter n'importe quel nom de procédure valide ; l'attribut DllImport indique le nom dans la DLL. Il gère également le marshaling d'interopérabilité pour les paramètres et valeurs de retour ; vous pouvez donc choisir des types de données Visual Studio similaires à ceux que l'API utilise.
Appliquez l'attribut DllImport à la fonction vide. Le premier paramètre représente le nom et l'emplacement de la DLL qui contient la fonction que vous appelez. Vous n'avez pas besoin d'indiquer le chemin d'accès des fichiers situés dans les répertoires système Windows. Le second paramètre est un argument nommé qui indique le nom de la fonction dans API Windows : Dans cet exemple, l'attribut DllImport force les appels à MoveFile à être transférés à MoveFileW dans KERNEL32.DLL. La méthode MoveFileW copie un fichier à partir du chemin d'accès src vers le 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
```

Ajoutez le 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

Créez un fichier nommé Test.txt et placez-le dans le répertoire C:\Tmp de votre disque dur. Créez le répertoire Tmp si nécessaire.
Appuyez sur F5 pour démarrer l'application. Le formulaire principal s'affiche.
Cliquez sur Button2. Le message "The file was moved successfully" s'affiche si le fichier peut être déplacé.

Voir aussi

Share via