Si Api est un dieu egyptien, c'est aussi un terme informatique. API est un acronyme de "Application Programming Interface". Si elles sont utilisées par toute sorte d'applications, on connait les APIs google, c'est parce que les APIs sont des fonctions publiées, exportées, par des programmes, OS... Vous avez déja rencontré des dll ! Ce sont des librairies (bibliothèrques) qui fournissent des éléments permmettant d'intégrer (interagir, modifier le comportement...) notre programme perso à un autre programme. C'est un énorme cadeau que nous file le programmeur ! Si certains programmes (compilés, donc 010011...) ne fonctionnent que sous windows et pas sur mac, ce n'est pas parce qu'ils ne sont matériellement incomptibles: tout ordinateur comprend des 0 et 1: c'est parce que le programme appelle des fonction intégrées à l'OS: les APIs. En gros, ce sont des portions de codes fournies, donc inutiles (et impossibles) à recopier dans notre script.

Le ruby est un langage interprété, c'est à dire qu'il a besoin d'un autre programme compilé (01001...) pour fonctionner. Sa vitesse-exécution est donc bien plus lente qu'un autre programme compilé. Maintenant imaginez que l'on ait besoin de faire une capture d'écran de notre fenetre. Il faut capturer son contenu pixel par pixel, à l'aide d'une boucle for très laide. On peut utiliser alors une API ecrite en C donc rapide, pour arriver au même résultat: la fameuse dll screenshot. Ce n'est qu'une infime possibilité, je l'ai dit plus tôt, les apis (celles que nous utilisons sont des .dll ou .lib, donc exploitables que sous windows.) etablissent une interface avec l'OS.

Ca devient interressant, maintenant. RGSS nous fournit une classe très pratique, la classe Win32API, c'est elle qui charge puis exécute les librairies. On la chareg comme ceci:

Code:

@instance=Win32API.new("librairie","fonction",[*args entrée],[args sortie])

et on l'exécute comme cela:

Code:

@instance.call(,[*args entrée])
=>@instance=[args sortie]

Voila donc la structure de l'utilisation d'API.

théoriquement toute librairie dll ou lib est utilisable: elle doit être placée à la racine du projet. Cependant, si vous êtes curieux, vous avez pu voir ou être forcé de voir en cas de bug, la quantité de librairies présentes dans le répertoire C:\WINDOWS\System32\. Vous en connaissez surement plusieurs. En voici une toute petite liste de celles que j'ai le plus souvent utilisées avec leur description:

• user32.dll :interface utilisateur: ce qui interagit avec vous: les fenetres, le clavier, souris.
  
• kernel32.dll :le noyaux de windows, les processus, mémoires...
  
• shell32.dll :interface graphique: explorer
  
• gdi32.dll :interface graphique: manipulation dessins...de bitmaps.
  
• socket32.dll :gestion de transfert via socket
  
• winmm.dll :librairie multimédia
  

il en existe plein d'autres: netapi32, avapi...
note: le -32 indique le type de processeur (32bits et pas 64 bits)

J'vous mâche le travail ! Imaginez le nombre d'heures à tenter de comprendre le fonctionnement des APIs ! Allez, pour commencer, une API lambda:

Code:

api=Win32API.new("user32",'MessageBoxA', ['i','p','p','i'], 'i')
api.call(0, 'texte', 'titre', 1)

Cette API affiche une boite de dialogue.
Soit. Qu'est-ce que c'est que ce truc... Analysons pas à pas.
Première ligne: l'initialisation:

• Premier argument: 'user32' c'est le nom de la librairie que l'on utilise, l'extension '.dll' est optionnelle. C'est une chaîne.
  
• Deuxième argument, la fonction: 'MessageBoxA'. c'est aussi une Chaîne. Chaque librairie comporte un certain nombre de fonctions, que l'on pourrait considérer comme nos méthodes ruby. C'est elle qui traitera l'action que l'on recherche.
  
• Troisième argument: ['i','p','p','i'] c'est un tableau, mais cela peut très bien être une chaine: "ippi" ou un tableau de forme %w(i p p i). Ce sont des paramètres d'entrée. Je vous expliquerai après ce que ces lettres stupides représentent.
  
• Dernier argument: 'i' c'est une chaîne, mais comme plus haut, cela peut être un tableau. C'est le valeur retournée par la fonction de la dll après l'exécution. Il y en a très souvent qu'une seule.

Deuxième ligne: l'exécution:
Comme tout processus en ruby, l'appel se fait par la méthode .call de l'instance.
Les arguments sont passés en entrée dans le tableau ['i','p','p','i']

• Premier argument: 0 nombre entier (integer) correspond à 'i' : c'est l'adresse mémoire de la fenetre parente. On a mis 0 pour ne pas établir de parenté avec le Rgss Player.
  
• Deuxième argument: 'texte' chaîne de caractères (string) : correspond à 'p' : c'est le contenu de la boite de dialogue.
  
• Troisième argument: 'titre' chaîne de caractères (string) : correspond à 'p' : c'est le titre de la fenêtre.
  
• Dernier argument: 1 nombre entier (integer) : ce sera le type de la fenetre (nombre de boutons, icones...).

Vous pouvez tester, une fenetre s'affiche... ouf !

Revenons à notre histoire de ippi... qu'est-ce que cela représente... Si vous avez fait du langage C, Basic, etc. vous devez savoir que toutes les variables n'ont pas la même déclaration. En ruby, même on distingue les float, des entiers, des strings. Et meme, dans les entiers, les Bignum et les autres. Ainsi, les paramètres sont traités différemment par ruby lors de leur envoi vers la dll. Voici leurs types:

• i : integer: nombre entier : 0 254, -1.
  
• l : long: nombre décimal, bignum: 0.254 et autres.
  
• p : pointer: est utilisé pour les strings, mais aussi pour les données compactées en chaine (tableau...).
  
• v : void: utilisé uniquement en retour de fonction retourne un nombre, mais on peut utiliser les autres.

et d'autres arguments moins utiles: n (nombre) et en ruby pur: s (string).
Ainsi, pour chaque paramètre, il convient d'identifier son type.

Certaines APIS ont des arguements spéciaux, c'est à dire qu'il s'agit de faire passer plusieurs données dans un seul argument, comme un tableau, quoi !
Deux méthodes, qui ne sont pas applicables dans un meme cas, existent:

• Les parenthèses: pour un groupe d'arguments de nombres:(1|254|2668|458) on utilise l'opérateur "OU bit par bit": "|" pour évaluer successivement les arguments, et les transférer s'ils sont exploitables.
  
• Le compactage: il consiste a faire rentrer dans un string plusieurs données de type différent:
  

  Code:

  param=["arg",0,-1.25,"test"].pack("pilp")

  param est maintenant une chaine

En général, la fonction renvoie 0 si son exécution a échoué, et un autre nombre non nul (utilisable: ex adresse mémoire d'une fenetre) en cas de réussite.
il s'obtient par arg=api.call(...)
Mais la fonction peut également renvoyer d'autres valeurs, par un moyen différent:
aussi étrange que cela puisse paraitre, un argument d'entrée peut servir de valeur-sortie.
prenons une api que vous avez surement rencontré : elle sert à récuperer le handle (adresse mémoire) de la fenetre de jeu, le Rgss Player.

Code:

    jeu="\0"*256
    Win32API.new('kernel32','GetPrivateProfileStringA','pppplp', 'l').call('Game','Title','',jeu,255,".\\Game.ini")
    titre=jeu.delete!("\0")
    print Win32API.new('user32','FindWindowEx','llpp','l').call(0,0,nil,titre)

que se passe-t-il?
Dans un premier temps, on cherche à récuperer le titre de la fenêtre par GetPrivateProfileStringA , pour pouvoir l'identifier par une autre API FindWindowEx.
On crée une chaine vide de 256 caractères nuls (\0 est un caractère nuls) qui contiendra le titre récupéré par l'API. La première API lit le fichier Game.ini, à la section Title et inscrit le titre récupéré dans la chaine préparée. En supprimant les caractères nuls, on obtient le titre en clair. Et on passe ce titre en paramètre à la seconde API qui identifie la fenetre en renvoie l'adresse mémoire.
Parfois, on peut compacter un tableau en chaine, l'API modifiera et renverra cette chaine. On la dépactera pour en retrouver un tableau rempli ou modifié.

Hé oui... je vous le laisse pour la fin... c'est ici la principale difficulté des APIs: on ne connait que le nom de la fonction, sans les arguments... comment les obtenir ? ben, il faut faire une recherche. Microsoft fournit un site très complet (un point pour lui, cette fois !) sur ses APIs: le site msdn.
Tapez sur Google "msdn mafonction" vous tomberez sur une page en anglois détaillant la référence de la fonction.
si l'on reprend notre API FindWindowEx: "msnd FindWindowEx"
On peut s'y attarder, c'est super utile. Les fonctions sont expliquées dans le langage Basic ou C, parfois C#, il faut traduire le tout pour ruby.
Descendez directement tout en bas de la page, vous y trouverez le nom de la dll.
Remontez, vous voyez un encadré, avec comme titre Syntax: c'est l'appel de la fonction
Le nom de la fonction est précédé d'un BOOL (0/1) VOID, HWND (handle)... c'est la valeur retournée. ici, c'est HWND
Ensuite, suivent les arguments d'entrée:
[TYPE, description]: HWND hwndParent : le handle du parent: le type vous aidera à trouver la lettre à écrire.
...
Vous avez les explications des paramètres en dessous.

Précisions:
Des constantes intégrées au C ou Basic sont parfois utilisées, vous en trouverez surement la valeur pour ruby en faisant une recherche ["NOM_CONST =" 0x4000]
les guillemets forment un bloc pour la recherche google, le nombre hexadécimal trie les site affichant les valeurs des constantes