Wskazówki dotyczące korzystania z interfejsu SetupAPI

Poniżej przedstawiono wskazówki dotyczące używania ogólnych funkcji instalacji (SetupXxx) i funkcji instalacji urządzeń (SetupDiXxx), które są udostępniane przez SetupAPI:

• Nigdy nie zakładaj, że zawartość pliku instalacyjnego jest wolna od błędów lub że podany plik instalacyjny nie został złośliwie zmodyfikowany. W związku z tym należy zawsze weryfikować wszystkie informacje odebrane z funkcji SetupAPI. Sprawdź, czy ciągi mają prawidłową długość, że mają prawidłowy rozmiar i czy wartości indeksu znajdują się w prawidłowym zakresie.

• Podczas pisania aplikacji instalacyjnych dla instalacji w systemach Microsoft Windows XP i nowszych można wywołać metodę SetupVerifyInfFile (opisaną w dokumentacji zestawu Windows SDK), która sprawdza, czy plik INF podpisany cyfrowo nie został zmodyfikowany.

• Zawsze przetestuj wartość zwracaną dla każdej funkcji SetupAPI. Jeśli funkcja zakończy się niepowodzeniem, kod powinien wywołać metodę GetLastError , aby uzyskać kod błędu identyfikujący błąd. Zwrócone kody błędów można zdefiniować w pliku Winerror.h lub Setupapi.h. Przed wywołaniem funkcji FormatMessage za pomocą FORMAT_MESSAGE_FROM_SYSTEM w celu utworzenia wyświetlania tekstu zawsze użyj makra HRESULT_FROM_SETUPAPI (zdefiniowanego w winerror.h), aby przekonwertować wartość zwracaną na wartość HRESULT. Jeśli funkcja SetupAPI zostanie zwrócona pomyślnie, kod nie może wywołać metody GetLastError. (Funkcje GetLastError i FormatMessage wraz z kodami błędów systemowych są opisane w dokumentacji zestawu Windows SDK).

• Jeśli funkcja SetupAPI zwraca uchwyt, kod musi sprawdzić zwracaną wartość INVALID_HANDLE_VALUE. Takie funkcje nie zwracają wartości NULL.

• Należy pamiętać o następującej różnicy między funkcjami SetupDiXxx i SetupXxx , które umożliwiają wywołującym wykonywanie zapytań o wymagany rozmiar buforu:

  • Jeśli obiekt wywołujący funkcję SetupDiXxx wykonuje takie zapytanie, funkcja GetLastError zawsze zwraca ERROR_INSUFFICIENT_BUFFER.

  • Jeśli obiekt wywołujący funkcję SetupXxx wykonuje takie zapytanie, funkcja GetLastError zwraca NO_ERROR, jeśli nie określono długości buforu lub ERROR_INSUFFICIENT_BUFFER, jeśli określono zbyt mały bufor.