Richtlijnen voor het gebruik van SetupAPI

Hieronder volgen richtlijnen voor het gebruik van de algemene Setup-functies (SetupXxx) en apparaatinstallatiefuncties (SetupDiXxx) die worden geleverd door SetupAPI:

• Ga er nooit van uit dat de inhoud van het installatiebestand foutloos is, of dat een installatiebestand dat u hebt aangeleverd, niet kwaadwillig is gewijzigd. Valideer daarom altijd alle informatie die is ontvangen van SetupAPI-functies. Controleer of tekenreeksen geldig zijn, dat buffers een geldige grootte hebben en dat indexwaarden binnen een geldig bereik vallen.

• Wanneer u installatietoepassingen schrijft voor installaties op Microsoft Windows XP en latere systemen, kunt u SetupVerifyInfFile aanroepen (beschreven in de Windows SDK-documentatie), waarmee wordt gecontroleerd of een digitaal ondertekend INF-bestand niet is gewijzigd.

• Test altijd de retourwaarde van elke SetupAPI-functie. Als de functie mislukt, moet uw code GetLastError aanroepen om een foutcode te verkrijgen waarmee de fout wordt geïdentificeerd. Geretourneerde foutcodes kunnen worden gedefinieerd in Winerror.h of Setupapi.h. Voordat u FormatMessage aanroept met FORMAT_MESSAGE_FROM_SYSTEM om een tekstweergave te maken, gebruikt u altijd de HRESULT_FROM_SETUPAPI macro (gedefinieerd in Winerror.h) om de retourwaarde te converteren naar een HRESULT-waarde. Als een SetupAPI-functie succesvol wordt voltooid, mag uw code GetLastError niet aanroepen. (De functies GetLastError en FormatMessage worden samen met systeemfoutcodes beschreven in de Windows SDK-documentatie.)

• Als een SetupAPI-functie een handle retourneert, moet uw code controleren op een retourwaarde van INVALID_HANDLE_VALUE. Dergelijke functies retourneren geen NULL.

• Let op het volgende verschil tussen de functies SetupDiXxx en SetupXxx waarmee een aanroeper een query kan uitvoeren op de vereiste grootte van een buffer:

  • Als de aanroeper van een SetupDiXxx-functie een dergelijke query maakt, retourneert GetLastError altijd ERROR_INSUFFICIENT_BUFFER.

  • Als de aanroeper van een SetupXxx-functie een dergelijke query maakt, retourneert GetLastError NO_ERROR als er geen bufferlengte is opgegeven of ERROR_INSUFFICIENT_BUFFER als er een buffer is opgegeven die te klein was.