Função SetupInstallFileExW (setupapi.h)
[Essa função está disponível para uso nos sistemas operacionais indicados na seção Requisitos. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. SetupAPI não deve mais ser usado para instalar aplicativos. Em vez disso, use o Windows Installer para desenvolver instaladores de aplicativos. SetupAPI continua a ser usado para instalar drivers de dispositivo.]
A função SetupInstallFileEx instala um arquivo conforme especificado por um INFCONTEXT retornado por SetupFindXXXLine ou explicitamente pelas informações de nome de arquivo e caminho. Essa função é a mesma que SetupInstallFile, exceto que um BOOL é retornado que indica se o arquivo estava em uso.
Se um arquivo for copiado, o chamador dessa função precisará ter privilégios para gravar no diretório de destino.
Sintaxe
WINSETUPAPI BOOL SetupInstallFileExW(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCWSTR SourceFile,
[in] PCWSTR SourcePathRoot,
[in] PCWSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_W CopyMsgHandler,
[in] PVOID Context,
[out] PBOOL FileWasInUse
);
Parâmetros
[in] InfHandle
Ponteiro opcional para o identificador para um arquivo INF que contém as seções SourceDisksNames e SourceDisksFiles. Se houver seções específicas da plataforma para o sistema do usuário (por exemplo, SourceDisksNames.x86 e SourceDisksFiles.x86), a seção específica da plataforma será usada. Se InfContext não for especificado e CopyStyle incluir SP_COPY_SOURCE_ABSOLUTE ou SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle será ignorado.
[in] InfContext
Ponteiro opcional para o contexto de uma linha em uma seção Copiar Arquivos em um arquivo INF. A rotina procura esse arquivo na seção SourceDisksFiles do InfHandle para obter informações de cópia de arquivo. Se InfContext não for especificado, SourceFile deverá ser.
[in] SourceFile
Ponteiro opcional para o nome do arquivo (sem caminho) do arquivo a ser copiado. O arquivo é pesquisado na seção SourceDisksFiles. O parâmetro SourceFile deverá ser especificado se InfContext não for. No entanto, SourceFile será ignorado se InfContext for especificado.
[in] SourcePathRoot
Ponteiro opcional para o caminho raiz para o arquivo a ser copiado (por exemplo, A:\ ou F:). Os caminhos na seção SourceDisksNames são acrescentados a esse caminho. O parâmetro SourcePathRoot será ignorado se CopyStyle incluir o sinalizador SP_COPY_SOURCE_ABSOLUTE.
[in] DestinationName
Ponteiro opcional para um novo nome para o arquivo copiado. Se InfContext for especificado, DestinationName fornecerá apenas o nome do arquivo (sem caminho) do arquivo de destino. Esse parâmetro pode ser NULL para indicar que o arquivo de destino deve ter o mesmo nome que o arquivo de origem. Se InfContext não for especificado, DestinationName fornecerá o caminho de destino completo e o nome do arquivo para o destino.
[in] CopyStyle
Sinalizadores que controlam o comportamento da operação de cópia de arquivo.
Esses sinalizadores podem ser uma combinação dos valores a seguir.
| Valor | Significado |
|---|---|
|
Exclua o arquivo de origem após a cópia bem-sucedida. O chamador não será notificado se a exclusão falhar. |
|
Copie o arquivo somente se isso substituir um arquivo no caminho de destino. |
|
Examine cada arquivo que está sendo copiado para ver se seus recursos de versão indicam que ele é a mesma versão ou não mais recente do que uma cópia existente no destino.
As informações de versão do arquivo usadas durante as verificações de versão são especificadas nos membros dwFileVersionMS e dwFileVersionLS de uma estrutura VS_FIXEDFILEINFO , conforme preenchido pelas funções de versão. Se um dos arquivos não tiver recursos de versão ou se tiverem informações de versão idênticas, o arquivo de origem será considerado mais recente. Se o arquivo de origem não for mais recente ou igual na versão e CopyMsgHandler for especificado, o chamador será notificado e poderá cancelar a cópia. Se CopyMsgHandler não for especificado, o arquivo não será copiado. |
|
Examine cada arquivo que está sendo copiado para ver se seus recursos de versão indicam que ele não é mais recente do que uma cópia existente no destino. Se o arquivo de origem for mais recente, mas não for igual na versão para o destino existente, o arquivo será copiado. |
|
Verifique se o arquivo de destino existe e, em caso afirmativo, notifique o chamador que pode vetar a cópia. Se CopyMsgHandler não for especificado, o arquivo não será substituído. |
|
Não descompacte o arquivo. Quando esse sinalizador é definido, o arquivo de destino não recebe a forma descompactada do nome de origem (se apropriado). Por exemplo, copiar "f:\x86\cmd.ex_" para "\\install\temp" resulta em um arquivo de destino de "\\install\temp\cmd.ex_". Se o sinalizador SP_COPY_NODECOMP não fosse especificado, o arquivo seria descompactado e o destino seria chamado de "\\install\temp\cmd.exe". A parte filename de DestinationName, se especificada, é removida e substituída pelo nome do arquivo de origem. Quando SP_COPY_NODECOMP é especificado, nenhuma informação de idioma ou versão pode ser verificada. |
|
Examine cada arquivo que está sendo copiado para ver se seu idioma difere do idioma de qualquer arquivo existente já no destino. Nesse caso, e CopyMsgHandler for especificado, o chamador será notificado e poderá cancelar a cópia. Se CopyMsgHandler não for especificado, o arquivo não será copiado. |
|
SourceFile é um caminho de origem completo. Não pesquise na seção SourceDisksNames do arquivo INF. |
|
SourcePathRoot é a parte completa do caminho do arquivo de origem. Ignore a fonte relativa especificada na seção SourceDisksNames do arquivo INF para a mídia de origem em que o arquivo está localizado. Esse sinalizador será ignorado se SP_COPY_SOURCE_ABSOLUTE for especificado. |
|
Se o destino existir, comporte-se como se estivesse em uso e enfileirar o arquivo para copiar na próxima reinicialização do sistema. |
|
Se o arquivo estiver em uso durante a operação de cópia, alerte o usuário de que o sistema requer uma reinicialização. |
|
Não dê ao usuário a opção de ignorar um arquivo. |
|
Verifique se o arquivo de destino existe e, em caso afirmativo, o arquivo não é substituído. O chamador não foi notificado. |
|
Examine cada arquivo que está sendo copiado para ver se seus recursos de versão (ou carimbos de data/hora para arquivos que não são de imagem) indicam que ele não é mais recente do que uma cópia existente no destino. Se o arquivo que está sendo copiado não for mais recente, o arquivo não será copiado. O chamador não foi notificado. |
|
Se o usuário tentar ignorar um arquivo, avise-o de que ignorar um arquivo pode afetar a instalação. (Usado para arquivos críticos do sistema.) |
[in] CopyMsgHandler
Ponteiro opcional para uma função de retorno de chamada a ser notificada de várias condições que podem surgir durante a cópia do arquivo.
[in] Context
Ponteiro para um valor definido pelo chamador que é passado como o primeiro parâmetro da função de retorno de chamada.
[out] FileWasInUse
Ponteiro para uma variável na qual essa função retorna um sinalizador que indica se o arquivo estava em uso. Este parâmetro é necessário.
Retornar valor
Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Se GetLastError retornar NO_ERROR, a operação de cópia de arquivo não foi concluída. O arquivo pode não ter sido copiado porque a operação de cópia de arquivo era desnecessária ou porque a função de retorno de chamada de arquivo retornou FALSE.
Comentários
Normalmente, essa API é usada ao instalar novas versões de arquivos do sistema que provavelmente estarão em uso. Ele atualiza um valor BOOL que indica se o arquivo estava em uso. Se o arquivo estiver em uso, a operação de cópia de arquivo será adiada até que o sistema seja reinicializado.
Se um diretório UNC for especificado como o diretório de destino de uma instalação de arquivo, você deverá garantir que ele exista antes de chamar SetupInstallFileEx. As funções de instalação não marcar para a existência de e não criam diretórios UNC. Se o diretório UNC de destino não existir, a instalação do arquivo falhará.
Observação
O cabeçalho setupapi.h define SetupInstallFileEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | setupapi.h |
| Biblioteca | Setupapi.lib |
| DLL | Setupapi.dll |