Réaliser un plugin pour la télécommande ATI Remote Wonder

gRRosminet

- Titre : Réaliser un plugin pour la télécommande ATI Remote Wonder

- Auteur : gRRosminet

- Parution : 12 juillet 2012

- Licence : Copyright ® 2013 gRRosminet. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction ♪

- II. Le contenu du SDK AMMO

- III. Le flux de messages

- IV. Description détaillée de chacune des fonctions de l'API AMMO

- IV-A. WhatKeysDoYouWant

- IV-B. EnumerateProgramableFunction

- IV-C. Configure

- IV-D. AreYouInFocus

- IV-E. HandleKey

- V. Description de la DLL

- VI. Définition des ressources de la DLL

- VII. Conclusion

I - Introduction ♪

Si comme moi, vous avez acquis cette superbe télécommande, vous trouverez certainement que les fonctionnalités proposées par celle-ci sont assez limitées quand on ne dispose pas des plugins adaptés aux applications qu'on utilise. Vous vous êtes donc peut-être senti une âme de développeur en herbe et avez décidé d'écrire vos propres plugins. Vous avez donc téléchargé le SDK ATI AMMO (Application Manipulation Modular Object), mais vous n'y avez rien compris. Soyons honnêtes : si les mots compilateur, langage C, file de messages, processus, etc. ne vous disent rien, il vaut mieux que vous ne continuiez pas vôtre lecture et que vous vous contentiez de télécharger les plugins dont vous avez besoin auprès des sites spécialisés. Si vous avez les premières notions nécessaires, vous pouvez continuer votre lecture sans attendre.

II - Le contenu du SDK AMMO

Le SDK AMMO contient la licence qui encadre le développement et la diffusion des plugins pour la télécommande, un document explicatif sur ce que doit contenir un plugin, le fichier d'en-tête « ammo.h » et les fichiers de l'exemple de plugin pour Winamp 2.x. Voyons ce que raconte le fichier d'aide à l'écriture de plugins. Tout d'abord, certaines fonctionnalités sont déjà implantées, il n'est donc pas nécessaire de les redévelopper. Il y également certaines touches qu'on ne peut pas reprogrammer : les touches Power, TV, DVD, et Media Library.

III - Le flux de messages

La télécommande, comme tout périphérique de contrôle, génère un flux de messages à l'attention des plugins. Lorsque le logiciel de gestion de la télécommande reçoit une pression de touche, il détermine le groupe (Custom Raw, Custom Mapped, Mouse Group, Channel Group …) de touche auquel il appartient. Chaque plugin est alors interrogé pour savoir s'il est intéressé par ce groupe de touches. Si un plugin est intéressé par le groupe de touches en question, la fonction AreYouInFocus() est appelée pour déterminer si le plugin devrait recevoir l'événement. Si la fonction renvoie FALSE, le plugin suivant est interrogé à son tour et ainsi de suite. Si aucun plugin ne récupère l'événement, il est alors envoyé au Multimedia Center ou à Windows en fonction de l'application qui a le focus à ce moment-là. Si la fonction renvoie TRUE, l'événement est passé à la fonction HandleKey(). Si cette dernière renvoie TRUE, plus aucun traitement n'est effectué ; si elle renvoie FALSE, l'événement poursuit son chemin comme décrit précédemment.

Pour la plupart des touches, deux événements seront générés : « touche enfoncée » et « touche relâchée ». Cependant, il se peut que pour certaines touches, un ou plusieurs événements « touche répétée » soit généré entre les deux précédents. La fonction AreYouInFocus() n'est appelée qu'une seule fois pour chaque groupe d'événements (de « touche enfoncée » à « touche relâchée »).

IV - Description détaillée de chacune des fonctions de l'API AMMO

IV-A - WhatKeysDoYouWant

DWORD WhatKeysDoYouWant(void)

Cette fonction est la première à être appelée. Elle sert à indiquer quels sont les groupes de touches qui intéressent le plugin. Une constante a été définie par groupe de touches dans le fichier d'en-tête « ammo.h » :

CUSTOM_RAW

Boutons A à F, envoyés tels quels

CUSTOM_MAPPED

Boutons A à F, remplacés par la fonction à laquelle ils ont été affectés

MOUSE_GROUP

8 directions de la souris, bouton gauche, droit et la main

CHANNEL_GROUP

chaine précédente / suivante

VOLUME_GROUP

Volume + / -, muet

NUMBER_GROUP

Touches de 0 à 9

CURSOR_GROUP

Flèches haut, bas, gauche, droite

PLAY_GROUP

Lecture, pause, stop, avance / retour rapide

MENU

Touche menu

SETUP

Touche configuration

ENTER

Touche OK

RECORD

Touche enregistrement

STOPWATCH

Touche de pause / reprise de l'émission TV

RESIZE

Touche agrandir / restaurer la fenêtre

WEB_LAUNCH

Touche WEB

Pour indiquer qu'on veut utiliser un groupe de touche, il suffit d'utiliser les constantes comme des drapeaux :

DWORD WhatKeysDoYouWant (void)
{
return (CUSTOM_MAPPED | VOLUME_GROUP | RESIZE | PLAY_GROUP);
}

IV-B - EnumerateProgramableFunction

char *EnumerateProgrammableFunction(WORD wIndex)

Cette fonction sert a fournir au programme de gestion de la télécommande l'intitulé des fonctions programmables proposées par le plugin. Il est recommandé d'utiliser un tableau static et global pour stocker ces chaines :

//nombre de fonctions programmables (optionnel, mais plus clair)
#define kNumFunctions 5
//tableau de chaines descriptives
static char *functions[kNumFunctions] =
{
"fonction 1",
"groupe 1|fonction 1",
"groupe 1|fonction 2",
"groupe 2|fonction 1",
"groupe 2|fonction 2"
};
// Fonction d'interfaçage avec l'application ATI
char * EnumerateProgrammableFunction (WORD wIndex)
{
if (wIndex >= kNumFunctions)
return NULL;

return functions[wIndex];
}

Comme vous avez pu le remarquer, il suffit de renvoyer NULL quand l'application d'ATI demande l'intitulé d'une fonction en dehors de la portée du tableau.

IV-C - Configure

void Configure(HWND hWnd)

Cette fonction permet à l'utilisateur de configurer le plugin si cela est nécessaire. Si ce n'est pas le cas, elle peut toujours servir à afficher une petite boite de dialogue avec le nom du plugin et du concepteur.

void Configure (HANDLE hWnd)
{
MessageBox(hWnd, "Un petit plugin :)\r\npar moi-même", "About", MB_OK);
}

IV-D - AreYouInFocus

BOOL AreYouInFocus(void)

Cette fonction sert, comme je l'ai expliqué précédemment, à indiquer à l'application d'ATI si oui ou non notre plugin est celui qui doit recevoir le message :

int AreYouInFocus (void)
{
// Si l'appli au premier plan est celle qu'on gère, on renvoie vrai
if (FindWindow("class name de mon appli",NULL) == GetForegroundWindow())
{
return TRUE;
}
return FALSE;
}

IV-E - HandleKey

BOOL HandleKey(BOOL bCustom, WORD wKeyEvent, WORD wKeyState)

Cette fonction est l'endroit où tout va réellement se passer. C'est dans cette fonction qu'on va réagir en fonction de la touche de la télécommande. Voyons une brève description des trois paramètres :

- bCustom : s'il est à TRUE, cela signifie que l'événement concerne une fonction programmable du plugin ;

- wKeyEvent : contient le code de la touche qui a généré l'événement ou le numéro de la fonction ;

- wKeyState : permet de savoir l'état de la touche : enfoncée (RMCTRL_KEY_ON), répétée (RMCTRL_KEY_REPEAT), relâchée (RMCTRL_KEY_OFF).

Pour les codes des touches, reportez-vous au contenu du fichier « ammo.h ».

BOOL HandleKey (BOOL bCustom, WORD wKeyEvent, WORD wState)
{
// recherche du handle de notre application
HWND h = FindWindow("class name de mon appli",NULL);

// Si l'application n'a pas été trouvée => on quitte
if (h == NULL)
{
return FALSE;
}

// Gestion des fonctions programmables
if (bCustom)
{
if (wState != RMCTRL_KEY_ON)
switch (wKeyEvent)
{
case fonction1 :
...
}
}
else
{
// Gestion des touches non programmables
if (wState == RMCTRL_KEY_ON)
{
switch (wKeyEvent)
{
case RMCTRL_MENU:
// Traitement
return TRUE;

...
}
}
else if (wState == RMCTRL_KEY_REPEAT)
{
switch (wKeyEvent)
{
case RMCTRL_VOLUMEUP:
// Traitement
return TRUE;

...
}
}
else if (wState == RMCTRL_KEY_OFF)
{
switch (wKeyEvent)
{
case RMCTRL_VOLUMEUP:
// Traitement
return TRUE;

...
}
}
}
return FALSE;
}

Pour ce qui est de la simulation du clavier et de la souris, je vous renvoie à ce tutoriel qui y est consacré.

V - Description de la DLL

Pour indiquer au compilateur les informations concernant la DLL qu'on vient de réaliser et les fonctions à publier, on va utiliser un fichier de définition (*.def) dont voici un exemple.

LIBRARY    "nom de la librairie"
DESCRIPTION    'description de la librairie'

EXPORTS
WhatKeysDoYouWant PRIVATE
EnumerateProgrammableFunction PRIVATE
Configure PRIVATE
AreYouInFocus PRIVATE
HandleKey PRIVATE

VI - Définition des ressources de la DLL

Le fichier de ressources doit contenir les informations de langue de la DLL :

#ifdef _WIN32
LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US
#pragma code_page(1252)
#endif

Les informations de version de la DLL, de débogage et de type d'OS/fichier :

VS_VERSION_INFO VERSIONINFO
FILEVERSION     1,0,0,0
PRODUCTVERSION    1,0,0,0
FILEFLAGSMASK     0x3fL

#ifdef _DEBUG
FILEFLAGS 0x1L
#else
FILEFLAGS 0x0L
#endif

FILEOS        0x40004L
FILETYPE    0x2L
FILESUBTYPE    0x0L

Et enfin, les informations utiles à l'application ATI :

BEGIN
BLOCK "StringFileInfo"
BEGIN
BLOCK "040904b0"
BEGIN

VALUE "CompanyName", "gRRosminet\0"
VALUE "FileDescription", "Mon plugin pour mon application\0"
VALUE "LegalCopyright", "Copyright 2002 gRRosminet\0"
VALUE "FileVersion", "1.0.0.0\0"
VALUE "OriginalFilename", "monplugin.dll\0"
VALUE "ProductName", "Mon application\0"
VALUE "ProductVersion", "1.0.0.0\0"
END
END

BLOCK "VarFileInfo"
BEGIN
VALUE "Translation", 0x409, 1200
END
END

VII - Conclusion

Et voilà, vous n'avez plus qu'à compiler tout ça. Un petit avertissement pour ceux qui utilisent un compilateur tel que Borland C++ Builder : certains compilateurs préfixent le nom des fonctions par un _ (underscore), ce qui ne convient pas : il faut absolument désactiver cette option. Comme vous avez pu le voir tout au long de cet exposé, la création d'un plugin pour la télécommande est un simple remplissage de formulaire. Pour ceux qui ne savent pas comment simuler le clavier et/ou la souris, un petit tour sur le tutoriel que je vous ai indiqué répondra à toutes les questions qu'il peut vous rester en suspens.