Native Wifi - bezdrátové sítě ve Windows - díl 1

V tomto článku se nebudu věnovat jádru Windows, psaní ovladačů, procesu bootování či jiné nízkoúrovňové záležitosti. Dnešním tématem je knihovna wlanpai.dll, jež implementuje klientskou část rozhraní Native Wifi, které programátorovi dovoluje poměrně pohodlně pracovat s bezdrátovými sítěmi. Začneme ale úplně od počátku všeho...

Motivační příběh

Na rozhraní Native Wifi jsem narazil před 2,5 roky v období prázdnin mezi (úspěšným) ukončením bakalářského a počátkem navazujícího magisterského studia na MFF UK. Již tehdy jsme se rozhodli započít s prací na splnění předmětu Softwarový projekt, jehož cílem je v rámci malé skupiny, čítající obvykle 4-6 lidí, vytvořit softwarové dílo poněkud většího rozsahu. Za tímto účelem bylo třeba nalézt vhodnou neutrální půdu, kde by se tým mohl setkávat a pracovat, tedy příjemné prostředí disponující zejména dobrým připojením k internetu. Budovy MFF UK kupodivu nesplňovaly internetovou podmínku, protože jsme jako nestudující neměli přístup k sítí eduroam.

Rozhodli jsme se vyzkoušet Národní technickou knihovnu (NTK), zejména její týmové studovny. Pronájem těchto místností mají studenti zdarma a registrační poplatek do knihovny také nepatří do kategorie "jen pro bohaté". Celá budova je navíc pokryta jak výše zmíněnou sítí eduroam, tak i sítí NTK-Simple, jenž umožňuje registrovaným návštěvníkům přístup k internetu. Volba se tedy zdála jasná.

Připojení přes NTK-Simple se záhy ukázalo jako velmi nestabilní. Hlavní příčinou, jak nám ji sdělila technická podpora, je snaha pokrýt celou budovu NTK, což vedlo k instalaci přílišného množství přístupových bodů (AP). Wifi karty tak při komunikaci neustále přecházejí mezi jednotlivými AP, což prý vede k celkové nestabilitě připojení. Standardní řešení, které v našem případě ale nezafungovalo, spočívá ve snížení výkonu Wifi karty, což vede k tomu, že počet viditelných AP poklesne na rozumnou mez.

Nechtěl jsem se NTK jen tak snadno vzdát a proto jsem se rozhodl prozkoumat, zda-li Windows neexportují nějaké rozhraní pro práci s bezdrátovými sítěmi a zejména pro připojování přes konkrétní (ideálně však jeden) přístupové body. V případě Windows Vista a novějších verzí hledání skončilo stoprocentním úspěchem. Ano, spásné rozhraní se jmenuje Native Wifi.

A tím celá pohádka v podstatě končí. Za cca půldruhého dne vznikla jednoduchá GUI aplikace s názvem WlanClient dovolující připojení k bezdrátové síti přes konkrétní AP, přičemž slušné množství programovacího času zabralo importování potřebných funkcí rozhraní Native Wifi do Delphi, jelikož v jiném jazyce jsem se grafická rozhraní ještě tvořit nenaučil. Aplikace je součástí tohoto článku, nechybí ani (nekomentované) zdrojové kódy.

Poznámka: po vyřešení problému došlo k výměně několika mailů s technickou podporou (odpověď na otázku, zda se podařilo problém vyřešit, ve stylu "ano, napsali jsme si na to aplikaci" asi neprogramátory obvykle udiví) a zdálo se, že naše aplikace bude k dispozici i oficiálně. Tato jednání nakonec vyšla do ztracena.

Poznámka: Je pravda, že také dokáži tvořit grafické rozhraní ve Windows Forms, tedy na platformě .NET. Rozhraní Native Wifi je sice dostupné i pro .NET, leč je nutné jej explicitně doinstalovat. Proto jsem se rozhodl použít Delphi. Tím také odpadly případné problémy s chybějícím .NET Frameworkem.

Příprava na akci

Jak již bylo řečeno výše, klientskou část rozhraní Native Wifi implementuje knihovna wlanapi.dll, pro linkování je dostupná statická knihovna wlanapi.lib. V článku se nebudeme zabývat veškerou funkčností, kterou rozhraní nabízí, ale podíváme se jen na prostředky, jenž nám dovolí vyřešit problém popsaný v pohádce. Konkrétně se jedná o nalezení odpovědí na následující otázky:

• Jak získat seznam Wifi karet připojených (ať už interně (PCI) či externě(USB)) k počítači?
• Jak zjistit bezdrátové sítě detekované určitou kartou?
• Jak zjistit seznam AP pro určitou síť?
• Jak se připojit ke konkrétní síti a jak se od ní opět odpojit?

Nutno přiznat, že oproti standardnímu Windows API se funkce exportované knihovnou wlanapi.dll používají velmi dobře, zejména ty, které budeme potřebovat. Hlavní rozdíl spočívá v tom, že pokud vám má funkce vrátit výsledek netriviální velikosti, alokuje si pro jeho uložení paměť sama a vaší zodpovědností je příslušný buffer uvolnit až jej nebudete dále potřebovat. U klasického Windows API musíte buffer poskytnout sami a jelikož dopředu obvykle nevíte, jak velký bude výsledek, voláte příslušnou rutinu minimálně dvakrát; poprvé, abyste se dozvěděli, jak velký výstupní buffer potřebujete, podruhé, abyste do něho uložili výsledek (jehož velikost se s trochou štěstí mezi dvěma voláními nezvětšila a tudíž se do vámi alokovaného bloku vejde).

Rozhraní Native Wifi je přítomné i na Windows XP SP3 či SP2 s balíčkem Wireless LAN API, nedovoluje však připojování k bezdrátové síti pouze přes určité přístupové body.

Před samotným zahájením práce je nutné rozhraní Native Wifi inicializovat pro vaši aplikaci, k čemuž slouží funkce WlanOpenHandle definovaná následovně:

DWORD WINAPI WlanOpenHandle(
  _In_        DWORD dwClientVersion,
  _Reserved_  PVOID pReserved,
  _Out_       PDWORD pdwNegotiatedVersion,
  _Out_       PHANDLE phClientHandle
);

V prvním parametru specifikujete jakou verzi Native Wifi si přejete používat (hodnota 1 znamená Windows XP, pro Windows Vista a novější zadejte dvojku). V třetím parametru se v případě úspěšné inicializace dozvíte jakou verzi nakonec budete opravdu používat. Jelikož je verze pro Windows Vista zpětně kompatibilní s verzí pro XP (pouze rozšiřuje její možnosti), ani situace, kdy vaše aplikace požaduje starší verzi a nakonec inicializuje novější by neměla představovat problém.

V případě úspěchu vám funkce ve čtvrtém parametru vrátí tzv. handle, což je odkaz na datové struktury vámi používané instance knihovny wlanapi.dll. Budete jej muset předávat jako parametr při volání dalších rutin rozhraní. Fakt, že inicializace skončila úspěchem, poznáte z návratové hodnoty, která bude ERROR_SUCCESS (číselná hodnota 0).

Upozornění: Vždy testujte úspěch či neúspěch volání funkce podle její návratové hodnoty, pokud dokumentace neřekne jinak. Nikdy nezkoumejte obsah výstupních parametrů předtím, než zkontrolujete návratovou hodnotu. U rozhraní Windows API se vyskytují převážně dva typy funkcí:

• Funkce vracející BOOL (logická hodnota TRUE nebo FALSE). Hodnota TRUE znamená, že funkce splnila svůj úkol a tedy naplnila výstupní parametry validními daty. Hodnota FALSE značí, že volání selhalo. Kód chyby obvykle získáte voláním rutiny GetLastError.
• Funkce vracející celé číslo (DWORD, NTSTATUS, int...). Takové rutiny vrací přímo kód chyby. Hodnota ERROR_SUCCESS udává, že volání uspělo (mimochodem, číselně je ERROR_SUCCESS rovna logické hodnotě FALSE). Jiný chybový kód indikuje neúspěch. Konstanty chybových kódů se mohou lišit u různých funkcí, ale 0 obvykle znamená úspěch.

Pokud si již s bezdrátovými sítěmi přes rozhraní Native Wifi pracovat nepřejete, měli byste tento fakt oznámit knihovně wlanapi.dll. Za tímto účelem exportuje funkci WlanCloseHandle. V prvním parametru ji předáte handle získané při úspěšné inicializaci knihovny.

DWORD WINAPI WlanCloseHandle(
  _In_        HANDLE hClientHandle,
  _Reserved_  PVOID pReserved
);

Poznámka: Pravděpodobně jste si v deklaracích funkcí všimli parametru pReserved. Jeho hodnotu vždy nastavujte na NULL (či nulu) a to nejen při volání funkcí rozhraní Native Wifi. Tyto parametry mohou být využity v pozdější verzi Windows k rozšíření funkčnosti dané rutiny.

Nyní již tedy víte, jak knihovnu wlanapi.dll připravit a jak provést úklid po případném "řádění". Nastal čas si ukázat, že Native Wifi je skutečně k něčemu dobré, k čemuž se dostaneme v druhém dílu.