LES API DE WINDOWS VB6 ET VB.NET

Les API de Windows
Visual Basic 6 et Visual Basic .Net

But du Tutorial : Apprendre et comparer l’utilisation des API avec Visual Basic 6,7 et 8
Niveau requis : Débutant

1. Que sont les API ?

Définition : Une API (Application Programming Interface – Interface de programmation d’applications) a pour objet de faciliter le travail d'un programmeur en lui fournissant les outils de base nécessaire à tout travail à l'aide d'un langage donné. Elle constitue une interface servant de fondement à un travail de programmation plus poussé. Elle contient plusieurs méthodes, fonctions et routines permettant le simplifier le travail.

Résumé : Une API est donc une bibliothèque de classes (dll)

2. Visual Basic et les API

Dans Visual Basic, qui possède déjà des fonctions prédéfinies, nous utiliserons une API en tant que remplaçant d’une lacune du langage, telle que l’extraction d’une icône, qui n’est pas prédéfinie dans Visual Basic (excepté version 8.0)

3. Les API de Windows

Les API de Windows se trouvent généralement dans le répertoire système, il en existe plusieurs, et les plus fréquentes sont surtout : user32.dll, shell32.dll, wininet.dll, gdi32.dll, kernel32.dll…

4. Se documenter, rassembler les informations nécessaires

Pour avoir des informations sur le fonctionnement des API de Windows, le site MSDN de Microsoft est l’endroit de référence. Attention, la documentation sur les API n’est disponible qu’en anglais.
Pour ceux voulant faire tout cela hors ligne, Microsoft met à disposition un fichier Win32.hlp regroupant toutes les informations nécessaires sur les API. Pour obtenir de l’aide en français, plusieurs sites et logiciels regroupent des informations sur les API.

Sur MSDN, la page présentant une fonction nous indique des renseignements très utiles, tels que les paramètres à entrer dans la fonction et ce à quoi ils correspondent. Nous savons maintenant comment marche la fonction, mais comment faire… en Visual Basic…

5. Déclarer l’API

En Visual Basic et aussi en VB.Net, pour utiliser une API, il faut déclarer la fonction ainsi que l’API de laquelle elle vient. Mais comment faire ? Cela est assez simple.

Syntaxe VB6:

[Private | Public] Declare Function | Sub “<name>” Lib “<library>” _
[Alias “<alias>”] [([arglist])] [As Type]

- Private et Public indique la visibilité de la fonction.
- Declare, obligatoire, annonce un appel à une procédure externe
- Function ou Sub doit être indiqué, Sub si rien n’est renvoyé, Function dans le cas contraire.
- <name> est le nom de la procédure appelée, il est sensible à la casse. (ex : ExtractIcon)
- Lib est obligatoire pour signaler la procédure externe
- <library> est le nom de l’API appelée (ex : shell32.dll)
- Alias <alias> indique le vrai nom de la procédure permettant de personnaliser <name>
- Des paramètres peuvent être passés si nécessaire
- As Type, en cas de fonction, indique le type retourné par la fonction

Exemple : Declare Function IsWindow Lib "user32" (ByVal hwnd As Long) As Long

Syntaxe VB.Net (via Declare) :

[Private|Public|Friend] Declare [Ansi|Unicode|Auto] Function | Sub _
“<name>” Lib “<library>” [Alias “<alias>”] [([arglist])] [As Type]

- Private, Public et Friend indique la visibilité de la méthode
- Declare, obligatoire, annonce un appel à une procédure externe
- Ansi, Unicode et Auto indique le type d’encodage à utiliser
- Function ou Sub doit être précisé, Sub si rien n’est renvoyé, Function dans le cas inverse
- <name> est le nom de la procédure appelée, il est sensible à la casse
- Lib doit être présent pour signaler la procédure externe
- <library> est le nom de l’API appelée
- Alias <alias> indique le vrai nom de la procédure permettant de personnaliser <name>
- Des paramètres peuvent êtres passés si nécessaire
- As Type, en cas de fonction, indique le type retourné par la fonction

Exemple : Declare Auto Function IsWindow Lib “user32” (ByVal hwnd As IntPtr) As Long

Syntaxe VB.Net (via DllImport) :

<DllImport(“<library>”, <params>)> _
[Private|Public|Friend] Shared Function|Sub “<alias>” [([arglist])] [As Type]
End Function|Sub

- DllImport sert à importer une procedure externe
- <library> correspond au nom de l’API (ex : «user32»)
- <params> sont une liste de paramètres pour l’appel externe dont nous retiendrons 3 importants :
- EntryPoint :=<name> où <name> désigne le nom de la procédure à appeler
- Charset :=<charset> où <charset> désigne un encodage de caractère
- CallingConvention :=<cv> où <cv> désigne un type d’appel
- Private, Public et Friend indique la visibilité de la méthode
- Shared indique que la procédure est partagée avec le module
- Function ou Sub, Sub si rien n’est retourné, Function le cas inverse
- <alias> définit le nom que vous utiliserez dans votre code pour la fonction
- Des paramètres peuvent êtres passés
- As Type, en cas fe donction, indique le type retourné

Exemple :
<DllImport(“kernel32.dll”, EntryPoint:=”MoveFile”, Charset:=Charset.Auto, _
CallingConvention:=CallingConvention.Winapi)> _
Private Shared Function DeplaceFichier(ByVal src As String, _
ByVal dst As String) As Boolean
End Function

Lors de l’entrée des paramètres à faire passer (pour tout les langages), il faut faire le choix entre ByVal (par valeur, qui fait une copie de la variable) et ByRef(par référence, qui envoi directement l’adresse pour permettre à la fonction de la modifier). Dans une fonction normale, cela n’a presque pas voir pas du tout de conséquence vu qu’on reste dans le module, mais lors de l’appel à une API (module externe), des erreurs peuvent avoir lieu. Notez qu’un handle n’est qu’une adresse, il peut être passé par valeur.

6. L’encodage

Il est généralement possible qu’une fonction nécessite un encodage, elle existe alors en 2 version et ces deux versions se distinguent facilement, une fonction acceptant l’encodage Ansi se termine par la lettre A en majuscule et une fonction acceptant l’encodage Unicode se termine par la lettre W en majuscule.

Exemple : ExtractIconA et ExtractIconW

Sur le site MSDN, référencez-vous au tableau de la fonction, qui indique les types d’encodage à utiliser.

Visual Basic 6 converti directement les paramètres en Ansi, nous n’utiliserons donc que la version Ansi de la fonction. Pour se faire, il faut ajouter le paramètre Alias.

Exemple : Private Declare Function ExtractIcon Lib “shell32.dll” _
Alias “ExtractIconA” (ByVal hInst As Long, ByVal Filename As String, _
ByVal Index As Integer) As Long

Visual Basic .Net (via Declare) agit un peu différemment, on peut choisir son encodage, mais il faut le préciser au moment de la déclaration. Notez que l’encodage choisi doit correspondre à l’encodage pris par la fonction.

Exemple (Ansi) : Private Declare Ansi Function ExtractIconA Lib “shell32.dll” _
(ByVal hInst As IntPtr, ByVal FileName As String, ByVal index As Integer) As IntPtr

Exemple (Unicode) : Private Declare Unicode Function ExtractIconW Lib “shell32.dll” _
(ByVal hInst As IntPtr, ByVal FileName As String, ByVal index As Integer) As IntPtr

Exemple (Auto) : Private Declare Auto Function ExtractIcon Lib “shell32.dll” _
(ByVal hInst As IntPtr, ByVal FileName As String, ByVal index As Integer) As IntPtr

Visual Basic .Net (via DllImport) , quant à lui, comme via Declare excepté que vous n’êtes pas obligé de définir le CharSet quand vous travailler en Auto

Exemple (Auto): <DllImport("shell32.dll", EntryPoint:="ExtractIcon", _
CallingConvention:=CallingConvention.Winapi)> _
Public Shared Function OuvrirIcone(ByVal hInst As IntPtr, _
ByVal Filename As String, ByVal Index As Integer) As IntPtr
End Function

Exemple (Ansi) : <DllImport("shell32.dll", CharSet:=CharSet.Ansi, _
EntryPoint:="ExtractIconA", CallingConvention:=CallingConvention.Winapi)> _
Public Shared Function OuvrirIcone(ByVal hInst As IntPtr, _
ByVal Filename As String, ByVal Index As Integer) As IntPtr
End Function

Exemple (Unicode) : <DllImport("shell32.dll", CharSet:=CharSet.Unicode, _
EntryPoint:="ExtractIconW", CallingConvention:=CallingConvention.Winapi)> _
Public Shared Function OuvrirIcone(ByVal hInst As IntPtr, _
ByVal Filename As String, ByVal Index As Integer) As IntPtr
End Function

7. Conversion de types

L’aide sur les API est fournie avec la syntaxe C++, vu qu’elles ont été écrites pour. Il va donc falloir convertir les types C++ en Visual Basic. Pour cela, voici un tableau avec les types courant, la traduction Visual Basic 6 et Visual Basic .Net.

En VB6, la visionneuse d’API vous évite de passer votre temps à convertir les types, mais il est toujours bon de savoir ce tableau, en .Net, la visionneuse d’API n’est plus livrée, vous devez donc procéder à la conversion.

8. Appel de l’API

L’API est désormais déclarée, vous pouvez l’appeler comme n’importe quelle autre fonction dans toutes les versions de Visual Basic.

9. L’attribut MarshalAs et l’objet Marshal (VB.Net)

L’attribut MarshalAs, pour les types non-managés

Si vous avez souhaité traduire une déclaration VB6 en VB.Net ou même en voulant écrire une nouvelle déclaration, il est possible que l’API retourne une erreur demandant un type non managé. L’attribut MarshalAs est fait pour ça. Nous allons voir comment l’utiliser.

Il faut d’abord savoir qu’il se place avant le paramètre dans la déclaration de la fonction, voici sa syntaxe :

Function|Sub <name> (<MarshalAs(params)> ByVal|ByRef <param> As Type) [As Type]

- Function ou Sub qui désigne le type de méthode
- <name> désigne le nom de la fonction
- <MarshalAs(…)> avec ses nombreux attributs dont nous retiendront 2 éléments importants :
- UnanagedType.<Type> où <Type> désigne un tyoe non managé
- SizeCount =<taille> où <taille> définit la taille d’un tableau ou d’une chaine structurée
- ByVal et ByRef pour signaler le type de passage (Voir Point 5. Déclarer l’API)
- <param> qui est le nom du paramètre
- As Type qui définit le type du paramètre.

Exemple : <MarshalAs(UnmanagedType.LptStr)> ByVal Name As String

L’objet Marshal, pour le travail avec les pointeurs

Il peut aussi arriver par exemple qu’une API vous demande le pointeur du buffer dans lequel écrire (Voir par ex : GetPrivateProfileString), en VB6, un String structuré aurait suffit, en .Net, nous allons travailler avec l’Objet Marshal qui contient des fonctions pour travailler avec les pointeurs.
Un petit exemple :

Déclarons la fonction (Voir http://msdn2.microsoft.com/en-us/library/ms724353.aspx ):

Private Declare Ansi Function GetPrivateProfileStringA Lib “kernel32.dll”(ByVal _
AppName As String, ByVal KeyName As String,ByVal Default As String, ByVal _
RetBuffer As IntPtr, ByVal Size As Integer, ByVal lpFileName As String) As Integer

Remarquez que j’ai donc remplacé le type du paramètre RetBuffer par un IntPtr vu que l’objet Marshal travaille avec les pointeurs. Nous allons donc écrire notre propre fonction qui va lire dans le fichier INI et retourner la réponse en utilisant cet API.

Public Function GetValue(ByVal Section As String, ByVal Key As String, _
ByVal DftValue As String, FileName As String) As String
Dim PtrCh As IntPtr ‘On crée le IntPtr qui contiendra l’adresse du buffer
Dim Lng As Integer ‘ Nombre de caractère retourné par l’API
Dim Chaine As String ‘Chaine qui sera retournée
PtrCh = Marshal.StringToHGlobalAnsi(New String(vbNullChar, 1024))
Lng = GetPrivateProfileString(Section, Key, "", PtrCh, 255, FileName)
Chaine = Marshal.PtrToStringAnsi(PtrCh, Lng)
Marshal.FreeHGlobal(PtrCh)
Return Chaine
End Function

Pour une description complète des fonctions Marshal, consultez l’aide MSDN.

10. Un exemple en VB6

Nous allons… extraire l’icône du Bloc Note pour l’afficher dans un PictureBox.

Nous avons besoin : d’un formulaire avec un PictureBox.

Après quelques recherches sur MSDN, voici ce que nous pouvons trouver :
http://msdn2.microsoft.com/en-us/library/ms648068.aspx
http://msdn2.microsoft.com/en-us/library/ms648064.aspx

Nous allons donc d’abord déclarer les fonctions comme indiqué sur la page MSDN dans le code, voici ce que nous obtenons :

Private Declare Function ExtractIcon Lib “shell32.dll” Alias “ExtractIconA” ( _
ByVal hInst As Long, ByVal ExeFileName As String, ByVal nIconIndex As Long) As Long

Private Declare Function DrawIcon Lib “user32.dll” (ByVal hDC As Long, _
ByVal X As Integer, ByVal Y As Integer, ByVal hIcon As Long) As Boolean

Il ne nous reste plus qu’à utiliser les fonctions, ici j’appelle les fonctions depuis l’évnèement Paint de la PictureBox, donc l’icône s’affichera dès que le contrôle aura été peint au chargement de l’application.

Private Sub Picture1_Paint()
Dim Icon As Long
Icon = ExtractIcon(Me.hdc, “C:\WINNT\NOTEPAD.EXE”, 0)
Call DrawIcon(Picture1.hdc, 0, 0, Icon)
End Sub

Voici ce que nous obtenons au lancement du programme :

11. Un exemple en VB.Net

Nous allons… afficher une boîte de dialogue « A propos de… » Windows.

Nous avons besoin : d’un formulaire et d’un bouton

Après quelques recherches, voici ce que nous pouvons trouver :
http://msdn2.microsoft.com/en-us/library/ms647731.aspx

Nous allons d’abord nous référencer à la grille de conversion et/ou aux descriptions de l’API pour pouvoir déclarer notre fonction. Nous allons utiliser le type de déclaration via DllImport. Voici ce que nous obtenons après la déclaration :

<DllImport(“shell32.dll”, EntryPoint:= “ShellAbout”, _
CallingConvention:=CallingConvention.Winapi)> _
Private Shared Function ShellAbout(ByVal hInst As IntPtr, ByVal szApp As String, _
ByVal szOther As String, ByVal hIcon As IntPtr) As Boolean
End Function

Notez ici que j’ai traduit la valeur retournée de type Int en Boolean car MSDN nous indiquait qu’elle retournait True ou False. Je vais donc appeler cette fonction dès que l’év ènement Click du bouton se sera produit :

Private Sub AbtBtn_Click(ByVal sender As System.Object, ByVal e As EventArgs) _
Handles AbtBtn.Click

ShellAbout(Me.Handle, "Mon Application", _
"Ici se trouve le texte de description de l'application.", Me.Icon.Handle)
End Sub

Voici ce que nous obtenons à l’affichage de cette boîte de dialogue (sur Vista Home Premium) :