Diretrizes para usar SetupAPI

A seguir estão as diretrizes para usar as funções gerais de instalação (SetupXxx) e as funções de instalação do dispositivo (SetupDiXxx) fornecidas pela SetupAPI:

• Nunca assuma que o conteúdo do ficheiro de instalação está isento de erros ou que um ficheiro de instalação fornecido não foi modificado de forma maliciosa. Portanto, sempre valide todas as informações recebidas das funções SetupAPI. Verifique se as cadeias de caracteres têm um comprimento válido, se os buffers têm um tamanho válido e se os valores de índice estão dentro de um intervalo válido.

• Ao escrever aplicativos de instalação para instalações no Microsoft Windows XP e sistemas posteriores, você pode chamar SetupVerifyInfFile (descrito na documentação do SDK do Windows), que verifica se um arquivo INF assinado digitalmente não foi modificado.

• Sempre teste o valor de retorno de cada função SetupAPI. Se a função falhar, seu código deve chamar GetLastError para obter um código de erro que identifica a falha. Os códigos de erro retornados podem ser definidos em Winerror.h ou Setupapi.h. Antes de chamar FormatMessage com FORMAT_MESSAGE_FROM_SYSTEM para criar uma exibição de texto, sempre use a macro HRESULT_FROM_SETUPAPI (definida em Winerror.h) para converter o valor de retorno em um valor HRESULT. Se uma função SetupAPI retornar com êxito, seu código não deve chamar GetLastError. (As funções GetLastError e FormatMessage , juntamente com os códigos de erro do sistema, são descritas na documentação do SDK do Windows.)

• Se uma função SetupAPI retornar um identificador, o seu código deverá verificar se o valor de retorno é INVALID_HANDLE_VALUE. Tais funções não retornam NULL.

• Esteja ciente da seguinte diferença entre as funções SetupDiXxx e SetupXxx que permitem que um chamador consulte o tamanho necessário de um buffer:

  • Se o chamador de uma função SetupDiXxx fizer tal consulta, GetLastError sempre retornará ERROR_INSUFFICIENT_BUFFER.

  • Se o chamador de uma função SetupXxx fizer essa consulta, GetLastError retornará NO_ERROR se nenhum comprimento de buffer foi especificado ou ERROR_INSUFFICIENT_BUFFER se um buffer foi especificado que era muito pequeno.