Partilhar via

Diretrizes para usar SetupAPI

  • Artigo

Veja a seguir as diretrizes para usar as funções gerais de Instalação (InstalaçãoXxx) e as funções de instalação do dispositivo (SetupDiXxx) fornecidas pela SetupAPI:

  • Nunca suponha que o conteúdo do arquivo de instalação seja livre de erros ou que um arquivo de instalação fornecido não tenha sido modificado maliciosamente. 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 são de 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 em 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 retornado de cada função SetupAPI. Se a função falhar, seu código deverá chamar GetLastError para obter um código de erro que identifique a falha. 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 retornado em um valor HRESULT. Se uma função SetupAPI retornar com êxito, seu código não deverá chamar GetLastError. (As funções GetLastError e FormatMessage , juntamente com códigos de erro do sistema, são descritas na documentação do SDK do Windows.)

  • Se uma função SetupAPI retornar um identificador, seu código deverá marcar para um valor retornado de INVALID_HANDLE_VALUE. Essas funções não retornam NULL.

  • Lembre-se 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 essa consulta, GetLastError sempre retornará ERROR_INSUFFICIENT_BUFFER.

    • Se o chamador de uma função de InstalaçãoXxx fizer essa consulta, GetLastError retornará NO_ERROR se nenhum comprimento de buffer tiver sido especificado ou ERROR_INSUFFICIENT_BUFFER se um buffer tiver sido especificado que fosse muito pequeno.