Guidelines for Using SetupAPI

The following are guidelines for using the general Setup functions (SetupXxx) and device installation functions (SetupDiXxx) that are provided by SetupAPI:

• Never assume that installation file contents are error-free, or that an installation file that you provided hasn't been maliciously modified. Therefore, always validate all information received from SetupAPI functions. Verify that strings are of valid length, that buffers are of valid size, and that index values are within a valid range.

• When writing installation applications for installations on Microsoft Windows XP and later systems, you can call SetupVerifyInfFile (described in the Windows SDK documentation), which verifies that a digitally signed INF file has not been modified.

• Always test the return value of each SetupAPI function. If the function fails, your code should call GetLastError to obtain an error code that identifies the failure. Returned error codes can be defined in Winerror.h or Setupapi.h. Before calling FormatMessage with FORMAT_MESSAGE_FROM_SYSTEM to create a text display, always use the HRESULT_FROM_SETUPAPI macro (defined in Winerror.h) to convert the return value to an HRESULT value. If a SetupAPI function returns successfully, your code must not call GetLastError. (The GetLastError and FormatMessage functions, together with system error codes, are described in the Windows SDK documentation.)

• If a SetupAPI function returns a handle, your code must check for a return value of INVALID_HANDLE_VALUE. Such functions do not return NULL.

• Be aware of the following difference between the SetupDiXxx and SetupXxx functions that allow a caller to query for the required size of a buffer:

  • If the caller of a SetupDiXxx function makes such a query, GetLastError always returns ERROR_INSUFFICIENT_BUFFER.

  • If the caller of a SetupXxx function makes such a query, GetLastError returns NO_ERROR if no buffer length was specified or ERROR_INSUFFICIENT_BUFFER if a buffer was specified that was too small.