Richtlinien für die Verwendung von SetupAPI

Im Folgenden sind Richtlinien für die Verwendung der allgemeinen Setupfunktionen (SetupXxx) und der Geräteinstallationsfunktionen (SetupDiXxx) aufgeführt, die von SetupAPI bereitgestellt werden:

• Gehen Sie niemals davon aus, dass der Inhalt der Installationsdatei fehlerfrei ist oder dass eine von Ihnen bereitgestellte Installationsdatei nicht böswillig geändert wurde. Überprüfen Sie daher immer alle Informationen, die von SetupAPI-Funktionen empfangen werden. Vergewissern Sie sich, dass Zeichenfolgen eine gültige Länge haben, dass Puffer eine gültige Größe aufweisen und dass sich Indexwerte innerhalb eines gültigen Bereichs befinden.

• Beim Schreiben von Installationsanwendungen für Installationen unter Microsoft Windows XP und höheren Systemen können Sie SetupVerifyInfFile aufrufen (in der Windows SDK-Dokumentation beschrieben), um zu überprüfen, ob eine digital signierte INF-Datei nicht geändert wurde.

• Testen Sie immer den Rückgabewert jeder SetupAPI-Funktion. Wenn die Funktion fehlschlägt, sollte Ihr Code GetLastError aufrufen, um einen Fehlercode abzurufen, der den Fehler identifiziert. Zurückgegebene Fehlercodes können in Winerror.h oder Setupapi.h definiert werden. Bevor Sie FormatMessage mit FORMAT_MESSAGE_FROM_SYSTEM aufrufen, um eine Textanzeige zu erstellen, verwenden Sie immer das HRESULT_FROM_SETUPAPI Makro (definiert in Winerror.h), um den Rückgabewert in einen HRESULT-Wert zu konvertieren. Wenn eine SetupAPI-Funktion erfolgreich zurückgegeben wird, darf Ihr Code GetLastError nicht aufrufen. (Die Funktionen GetLastError und FormatMessage sowie Systemfehlercodes werden in der Dokumentation zum Windows SDK beschrieben.)

• Wenn eine SetupAPI-Funktion ein Handle zurückgibt, muss Ihr Code auf einen Rückgabewert von INVALID_HANDLE_VALUE überprüfen. Solche Funktionen geben null nicht zurück.

• Beachten Sie den folgenden Unterschied zwischen den Funktionen SetupDiXxx und SetupXxx , die es einem Aufrufer ermöglichen, die erforderliche Größe eines Puffers abzufragen:

  • Wenn der Aufrufer einer SetupDiXxx-Funktion eine solche Abfrage durchführt, gibt GetLastError immer ERROR_INSUFFICIENT_BUFFER zurück.

  • Wenn der Aufrufer einer SetupXxx-Funktion eine solche Abfrage durchführt, gibt GetLastError NO_ERROR zurück, wenn keine Pufferlänge angegeben wurde, oder ERROR_INSUFFICIENT_BUFFER, wenn ein zu kleiner Puffer angegeben wurde.