Pokyny pro používání setupAPI

Tady jsou pokyny pro použití obecných instalačních funkcí (SetupXxx) a instalačních funkcí zařízení (SetupDiXxx), které poskytuje SetupAPI:

• Nikdy nepředpokládáte, že obsah instalačního souboru je chybový nebo že zadaný instalační soubor nebyl zlými úmysly změněn. Proto vždy ověřte všechny informace přijaté z funkcí SetupAPI. Ověřte, že řetězce mají platnou délku, že vyrovnávací paměti mají platnou velikost, a že hodnoty indexu jsou v platném rozsahu.

• Při psaní instalačních aplikací pro instalace na systémech Microsoft Windows XP a novějších je možné zavolat SetupVerifyInfFile (popsané v dokumentaci k sadě Windows SDK), který ověřuje, že digitálně podepsaný soubor INF nebyl změněn.

• Vždy otestujte návratové hodnoty každé funkce SetupAPI. Pokud funkce selže, měl by váš kód volat GetLastError, aby získal kód chyby, který identifikuje selhání. Vrácené kódy chyb lze definovat v winerror.h nebo Setupapi.h. Než zavoláte FormatMessage s FORMAT_MESSAGE_FROM_SYSTEM k vytvoření zobrazení textu, vždy použijte makro HRESULT_FROM_SETUPAPI (definované v Winerror.h) k převodu návratové hodnoty na hodnotu HRESULT. Pokud se funkce SetupAPI úspěšně vrátí, nesmí kód volat GetLastError. (Funkce GetLastError a FormatMessage spolu s kódy systémových chyb jsou popsané v dokumentaci k sadě Windows SDK.)

• Pokud funkce SetupAPI vrátí popisovač, musí kód zkontrolovat návratovou hodnotu INVALID_HANDLE_VALUE. Takové funkce nevrací hodnotu NULL.

• Mějte na paměti následující rozdíl mezi funkcemi SetupDiXxx a SetupXxx , které volajícímu umožňují dotazovat se na požadovanou velikost vyrovnávací paměti:

  • Pokud volající funkce SetupDiXxx takový dotaz provede, funkce GetLastError vždy vrátí ERROR_INSUFFICIENT_BUFFER.

  • Pokud volající funkce SetupXxx provede takový dotaz, vrátí GetLastError NO_ERROR pokud nebyla zadána žádná délka vyrovnávací paměti nebo ERROR_INSUFFICIENT_BUFFER pokud byla zadána vyrovnávací paměť, která byla příliš malá.