Usando informações de versão
Um programa de instalação normalmente tem as seguintes metas:
- Para colocar arquivos no local correto.
- Para notificar o usuário se o programa de instalação estiver substituindo um arquivo existente por uma versão significativamente diferente, por exemplo, substituindo um arquivo em alemão por um arquivo em inglês ou substituindo um arquivo mais recente por um arquivo mais antigo.
Ao escrever o programa de instalação, você deve ter as seguintes informações para cada arquivo:
- O nome e o local do arquivo (chamado de arquivo de origem).
- O nome do arquivo equivalente no disco rígido do usuário (chamado de arquivo de destino). Esse nome geralmente é o mesmo que o nome do arquivo no disco de instalação.
- O status de compartilhamento do arquivo, ou seja, se o arquivo é privado para o aplicativo que está sendo instalado ou pode ser compartilhado por vários aplicativos.
O programa de instalação pode usar a função VerFindFile para determinar onde o arquivo deve ser copiado no disco. Essa função também pode ser usada para especificar se o arquivo é privado para o aplicativo ou pode ser compartilhado. Se ocorrer um problema ao localizar o arquivo, VerFindFile retornará um valor de erro. Por exemplo, se o sistema estiver usando o arquivo de destino, VerFindFile retornará VFF_FILEINUSE. O programa de instalação deve notificar o usuário sobre o problema e responder à decisão do usuário de continuar ou encerrar a instalação.
A função VerInstallFile copia o arquivo de origem para um arquivo temporário no diretório especificado por VerFindFile. Se necessário, VerInstallFile expande o arquivo usando as funções na biblioteca de descompactação de dados.
VerInstallFile compara as informações de versão do arquivo temporário com as do arquivo de destino. Se os dois forem diferentes, VerInstallFile retornará um ou mais valores de erro. Por exemplo, ele retornará VIF_SRCOLD se o arquivo temporário for mais antigo que o arquivo de destino e VIF_DIFFLANG se os arquivos tiverem diferentes identificadores de idioma ou valores de página de código. O programa de instalação deve notificar o usuário sobre o problema e responder à decisão do usuário de continuar ou encerrar a instalação.
Alguns erros de VerInstallFile são recuperáveis. Ou seja, o programa de instalação pode chamar VerInstallFile novamente, especificando a opção VIFF_FORCEINSTALL , para instalar o arquivo independentemente do conflito de versão. Se VerInstallFile retornar VIF_TEMPFILE e o usuário optar por não forçar a instalação, o programa de instalação deverá excluir o arquivo temporário.
VerInstallFile pode encontrar um erro não detectável ao tentar forçar a instalação, mesmo que o erro não exista anteriormente. Por exemplo, o arquivo pode ser bloqueado por outro usuário antes que o programa de instalação tentasse forçar a instalação. Se um programa de instalação tentar forçar a instalação após um erro não recuperável, VerInstallFile falhará. O programa de instalação deve conter rotinas para se recuperar desse tipo de erro.
A solução recomendada é exibir uma caixa de diálogo com os botões Instalar, Ignorar e Instalar Tudo. (Outra solução é uma caixa de diálogo com os botões Sim, Sim para Todos, Ignorar e Cancelar.) O botão Instalar Tudo deve impedir que o programa de instalação solicite ao usuário erros semelhantes, incluindo a opção VIFF_FORCEINSTALL em todos os usos subsequentes de VerInstallFile. Para erros não detectáveis, os botões Instalar e Instalar Tudo devem ser desabilitados.
Para exibir uma mensagem de erro útil para o usuário, o programa de instalação geralmente deve recuperar informações dos recursos de versão dos arquivos conflitantes. Há quatro funções que o programa de instalação pode usar para essa finalidade:
GetFileVersionInfoSize retorna o tamanho das informações de versão. GetFileVersionInfo usa informações recuperadas por GetFileVersionInfoSize para recuperar uma estrutura que contém as informações de versão. VerQueryValue recupera um membro específico dessa estrutura.
Por exemplo, se VerInstallFile retornar o erro VIF_DIFFTYPE , o programa de instalação deverá usar as funções GetFileVersionInfoSize, GetFileVersionInfo e VerQueryValue nos arquivos temporários e de destino para obter o tipo geral de cada arquivo. Se os idiomas dos arquivos entrarem em conflito, o programa de instalação também deverá usar VerLanguageName para converter o identificador de idioma binário em uma representação de texto do idioma. (Por exemplo, 0x040C é traduzido para a cadeia de caracteres "Francês".
Se VerInstallFile retornar um erro de arquivo, como VIF_ACCESSVIOLATION, o programa de instalação deverá usar a função GetLastError para recuperar o valor de erro mais recente. O programa deve converter esse valor em uma mensagem informativa a ser exibida para o usuário. O programa não deve gerar controle entre as chamadas para VerInstallFile e GetLastError.