Zjištění dostupnosti sady rozhraní API

V některých případech může být daný název kontraktu sady rozhraní API záměrně namapován na prázdný název modulu na některých zařízeních Windows. Důvody se liší, ale běžným příkladem je, že nákladná funkce z hlediska systémových prostředků může být při konfiguraci zařízení s omezenými prostředky odebrána z operačního systému Windows. To představuje výzvu pro aplikace k řádnému zpracování volitelných funkcí na úrovni rozhraní API.

Tradiční přístup k testování, zda je k dispozici rozhraní API Win32, je použít LoadLibrary nebo GetProcAddress. Nejedná se ale o spolehlivé prostředky pro testování sad rozhraní API kvůli zpětnému přeposílání. Pokud je u daného rozhraní API použito zpětné předávání, LoadLibrary nebo GetProcAddress se může přeložit na platný ukazatel funkce i v případech, kdy byla interní implementace odebrána. V tomto případě ukazatel funkce bude odkazovat na funkci zástupných procedur, která jednoduše vrátí chybu.

K detekci tohoto případu můžete použít funkci IsApiSetImplemented k dotazování základní dostupnosti dané implementace rozhraní API. Tento test hlásí, jestli je sada rozhraní API přítomná ve schématu složené sady rozhraní API na spuštěném zařízení a jestli je namapovaná na modul implementace.

Important

Úspěšný dotaz dostupnosti není zárukou úspěšného volání. Pokračujte ve zpracování chyb načítání modulů, chybějících exportů a vlastních zdokumentovaných výsledků selhání rozhraní API.

Následující příklad kódu ukazuje, jak použít IsApiSetImplemented k určení, zda sada rozhraní API obsahující WTSEnumerateSessionsW je k dispozici na aktuálním zařízení před voláním.

#include <windows.h>
#include <apiquery2.h>
#include <stdio.h>
#include <wtsapi32.h>

#pragma comment(lib, "OneCore.lib")
#pragma comment(lib, "Wtsapi32.lib")

int __cdecl wmain(int /* argc */, PCWSTR /* argv */ [])
{
    PWTS_SESSION_INFOW pInfo = nullptr;
    DWORD count = 0;

    if (!IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0"))
    {
        wprintf(L"ext-ms-win-session-wtsapi32-l1-1-0 is not available.\n");
        return 0;
    }

    if (WTSEnumerateSessionsW(WTS_CURRENT_SERVER_HANDLE, 0, 1, &pInfo, &count))
    {
        wprintf(L"SessionCount = %lu\n", count);

        for (DWORD i = 0; i < count; i++)
        {
            PWTS_SESSION_INFOW pCurInfo = &pInfo[i];
            wprintf(L"    %ls: ID = %lu, state = %d\n", pCurInfo->pWinStationName,
                pCurInfo->SessionId, static_cast<int>(pCurInfo->State));
        }

        WTSFreeMemory(pInfo);
    }
    else
    {
        wprintf(L"WTSEnumerateSessionsW failure: %lu\n", GetLastError());
    }

    return 0;
}

IsApiSetImplemented je deklarován v apiquery2.h a normální cesta odkazu veřejné sady SDK ji poskytuje z OneCore.lib. Tato knihovna je oddělená od jakékoli knihovny importu potřebné k volání volitelného cílového rozhraní API.

Příklad výše odkazuje Wtsapi32.lib pro statický import, který uchovává příklad krátký. Produkční aplikace, která musí běžet tam, kde sada rozhraní API chybí, by měla také použít pokyny v části Zachování dostupné volitelné cesty kódu.

Zvolte název dotazu.

Předejte název sady rozhraní API, kterou testujete. Názvy sady rozhraní API se obvykle zapisují bez .dll přípony a příklady na této stránce používají tento formulář. Přípona není součástí názvu sady rozhraní API.

Pokud chcete najít název, který se má předat, podívejte se na tabulku Požadavky na referenční stránce pro rozhraní API, které chcete volat. Pokud má tato tabulka řádek sady rozhraní API , dá název kontraktu. V opačném případě použijte řádek knihovny DLL , ale pouze v případě, že název kontraktu api-ext-začíná nebo ; název fyzického modulu, například Wtsapi32.dll není kontrakt, a dotazování vrátí hodnotu FALSE.

Forma názvu závisí na tom, jak se rozhraní API řeší.

Plocha rozhraní API Formulář dotazu Example
Pojmenovaná skupina <contract>~<group> api-win-core-samplefeature~AdvancedOperations
Výchozí skupina Alias smlouvy bez ~Default api-win-core-samplefeature
Kontrakt s verzí Úplný název kontraktu s verzí ext-ms-win-core-samplefeature-l1-1-0

Názvy samplefeature jsou ilustrativní názvy fiktivní Windows komponenty. Předpona názvu (api- nebo ext-) nehraje roli při chování dostupnosti.

U pojmenované skupiny úspěšný dotaz znamená, že skupina existuje, její kontrakt se mapuje na implementační modul, který je použitelný v aktuálním spouštěcím prostředí, skupina není zakázaná a je povolená žádná systémová funkce přidružená ke skupině. Dotaz, který používá alias kontraktu, použije kontrolu kontraktu a hostitele.

Pokud veřejná hlavička rozhraní API poskytuje pomocnou rutinu Is<APIName>Present , upřednostňujte tuto pomocnou rutinu. Obsahuje již správný název sady rozhraní API nebo skupiny, která toto rozhraní API přenáší.

Výsledkem dotazu je kontrakt nebo seskupit, nikoli členitá funkce. Dva pomocné rutiny zálohované stejnou pojmenovanou skupinou vždy vrátí stejný výsledek, i když je každý pomocník pojmenovaný pro jiné rozhraní API.

Zachování dostupné volitelné cesty kódu

Kontrola dostupnosti nemůže chránit spuštění procesu, pokud je volitelné rozhraní API propojené jako statický import. Zavaděč vyřeší statické importy před spuštěním kódu, takže chybějící modul selže proces před provedením kontroly.

Použijte jeden z těchto přístupů:

  • Nakonfigurujte modul, který má volitelné rozhraní API pro odložené načítání. Zpoždění načítání je nastavení linkeru: zadejte /DELAYLOAD:<module> a link delayimp.lib. Zadejte název modulu, který se zobrazí v tabulce importu binárního souboru, což může být klasický název knihovny DLL, nikoli název kontraktu sady rozhraní API. V předchozím příkladu je tento název WTSAPI32.dll.
  • Nebo můžete cíl dynamicky vyřešit pomocí LoadLibrary a GetProcAddress , jakmile bude dotaz dostupnosti úspěšný.

Nepoužívejte LoadLibrary ani GetProcAddress jako náhradu za dotaz dostupnosti. Odpovězují na modul a exportují otázky, nevyhodnocují pojmenovaný stav skupiny a můžou přeložit na zástupný proceduru zpětného přeposílání, jak je popsáno výše. Po dotazu je použijte ke zpracování samostatných kontrol modulu a exportu.

Chování v dřívějších verzích Windows

Implementace, kterou poskytuje OneCore.lib , vybere dostupný mechanismus dotazu za běhu, takže aplikace, která volá IsApiSetImplemented , může stále běžet v systému, který předchází podpoře podkladových dotazů.

V systému, kde není k dispozici žádný mechanismus dotazu:

  • Kvalifikovaný název skupiny, který obsahuje ~ hodnotu FALSE. Systém, který nemůže vyhodnotit pojmenované skupiny, nemůže hlásit, že je skupina dostupná.
  • Název, který není kvalifikovaný pro skupinu, může vrátit hodnotu PRAVDA. To zachovává kompatibilitu s aplikacemi, které dodávají vlastní knihovny DLL pro předávání na dřívějších verzích Windows, kde byl kontrakt ve skutečnosti spokojen tímto předáváním.

Nepoužívejte dotaz dostupnosti sady rozhraní API jako bezpečnostní nebo autorizační kontrolu.

Viz také

  • Last updated on