3.3. Koukkujen asennus, poistaminen ja koukkufunktiot

Koukun asennus tapahtuu funktiolla SetWindowsHookEx, joka ottaa neljä parametria. Ne ovat koukun tyypin kertova kokonaislukukoodi, osoitin koukun sisältävään funktioon, em. funktion sisältävän moduulin kahva ja koukutettavan säikeen tunniste. Järjestelmänlaajuisten koukkujen tapauksessa instanssi kahva on DllMainin HINSTANCE parametri ja säikeen tunnisteella 0 kerrotaan Windowsille ettei koukku rajoitu vain yhteen säikeeseen. Funktio palauttaa kahvan koukkuun (HHOOK), joka on tallennettava myöhempää käyttöä varten. Esimerkkiohjelmassa CBT-koukku asennetaan seuraavalla funktiokutsulla.

hCbtHook = SetWindowsHookEx(WH_CBT, cbtHookFunction, hDllInstance, 0);

Koukun poistaminen tapahtuu funktiolla UnhookWindowsHook, jonka ainut parametri on aiemmin tallennettu kahva poistettavaan koukkuun. Funktion paluuarvo kertoo periaatteessa poiston onnistumisesta, tosin Microsoftin koukkuartikkelin mukaan funktio palauttaa aina arvon tosi. CBT-koukku poistetaan esimerkissä seuraavalla koodinpätkällä:

UnhookWindowsHookEx(hCbtHook);

Mikäli useampi kuin yksi sovellus asentaa samantyyppisen koukun, koukut muodostavat ketjuja. SetWindowsHookEx lisää aina ajallisesti myöhäisimmän koukun ketjun kärkeen. Toisin sanoen viimeisenä lisätty koukku saa keskeytetyn viestin ensimmäisenä. Koukut eivät WH_DEBUG-koukkuja lukuunottamatta saa mitään tietoa muiden koukkujen olemassaolosta ketjussa. Ketjuttaessa voi käydä esimerkiksi niin, että ketjussa oleva koukku suodattaa tietyntyyppiset viestit pois eivätkä ne koskaan päädy käsittelyjärjestyksessä "suotimen" jälkeisille koukuille. Järjestelmänlaajuisten koukkujen kanssa onkin oltava erityisen varovainen.

SetWindowsHookEx funktion toinen parametri on osoite itse koukkufunktioon, jossa varsinainen toiminta tapahtuu. Koukkufunktion prototyyppi on kaikille koukkutyypeille sama ja muistuttaa pitkälti ikkunaproseduurille välitettäviä viestiparametreja. Paluuarvo on samaa tyyppiä kuin ikkunaproseduurissakin ja koukkufunktion kolmesta parametrista kaksi viimeistä ovat tyyppiä WPARAM ja LPARAM. Ensimmäinen on koukkukoodi ncode, joka kertoo koukkukohtaisesti lParam ja wParam parametrien merkityksen (vertaa ikkunaproseduurin message-parametri).

Windows ei automaattisesti välitä koukkufunktion saamaa tietoa ketjussa seuraavalle koukulle vaan vastuu on koukun kirjoittajalla. Viesti välitetään eteenpäin ketjussa kutsumalla CallNextHookEx-funktiota, jonka kolme viimeistä parametria vastaavat suoraan koukkufunktioon tulleita parametreja. Ensimmäinen parametri on SetWindowsHookEx-funktion paluuarvona saatu kahva. Koukkufunktion paluuarvo on lisäksi oltava CallNextHhookEx-funktion palauttama arvo. Nämä ehdot sanelevat koukkufunktion yleisrakenteen:

LRESULT CALLBACK hookFunction(int ncode, WPARAM wParam, LPARAM lParam)
{
	if(ncode >= 0)
	{
	    // Käsittely.
	} // if
	return CallNextHookEx(setHookRetval, ncode, wParam, lParam);
} // hookFunction

takaisin sisällysluetteloon