Função MsiOpenDatabaseA (msiquery.h)

  • Artigo

A função MsiOpenDatabase abre um arquivo de banco de dados para acesso a dados. Essa função retorna um identificador que deve ser fechado usando MsiCloseHandle.

Sintaxe

UINT MsiOpenDatabaseA(
  [in]  LPCSTR    szDatabasePath,
  [in]  LPCSTR    szPersist,
  [out] MSIHANDLE *phDatabase
);

Parâmetros

[in] szDatabasePath

Especifica o caminho completo ou o caminho relativo para o arquivo de banco de dados.

[in] szPersist

Recebe o caminho completo para o arquivo ou o modo de persistência. Você pode usar o parâmetro szPersist para direcionar a saída persistente para um novo arquivo ou para especificar um dos seguintes modos de persistência predefinidos.

Valor Significado
MSIDBOPEN_CREATEDIRECT
 Crie um novo banco de dados, leitura/gravação no modo direto.
MSIDBOPEN_CREATE
 Crie um novo banco de dados, transe o modo de leitura/gravação.
MSIDBOPEN_DIRECT
 Abra um banco de dados de leitura/gravação direta sem transação.
MSIDBOPEN_READONLY
 Abra um banco de dados somente leitura, sem alterações persistentes.
MSIDBOPEN_TRANSACT
 Abra um banco de dados de leitura/gravação no modo de transação.
MSIDBOPEN_PATCHFILE
 Adicione esse sinalizador para indicar um arquivo de patch.

[out] phDatabase

Ponteiro para o local do identificador de banco de dados retornado.

Retornar valor

A função MsiOpenDatabase retorna os seguintes valores:

Comentários

Para fazer e salvar alterações em um banco de dados, primeiro abra o banco de dados no modo de transação (MSIDBOPEN_TRANSACT), criar (MSIDBOPEN_CREATE ou MSIDBOPEN_CREATEDIRECT) ou direto (MSIDBOPEN_DIRECT). Depois de fazer as alterações, sempre chame MsiDatabaseCommit antes de fechar o identificador do banco de dados. MsiDatabaseCommit libera todos os buffers.

Sempre chame MsiDatabaseCommit em um banco de dados que foi aberto no modo direto (MSIDBOPEN_DIRECT ou MSIDBOPEN_CREATEDIRECT) antes de fechar o identificador do banco de dados. A falha ao fazer isso pode corromper o banco de dados.

Como o MsiOpenDatabase inicia o acesso ao banco de dados, ele não pode ser usado com uma instalação em execução.

Observe que é recomendável usar variáveis do tipo PMSIHANDLE porque o instalador fecha objetos PMSIHANDLE à medida que eles saem do escopo, enquanto você deve fechar objetos MSIHANDLE chamando MsiCloseHandle. Para obter mais informações, confira a seção Use PMSIHANDLE em vez de HANDLE nas Melhores práticas do Windows Installer.

Nota Quando um banco de dados é aberto como saída de outro banco de dados, o fluxo de informações de resumo do banco de dados de saída é, na verdade, um espelho somente leitura do banco de dados original e, portanto, não pode ser alterado. Além disso, ele não é persistente com o banco de dados. Para criar ou modificar as informações de resumo do banco de dados de saída, ele deve ser fechado e reaberto.
 
Se a função falhar, você poderá obter informações de erro estendidas usando MsiGetLastErrorRecord.

Observação

O cabeçalho msiquery.h define MsiOpenDatabase 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 Installer 5.0 no Windows Server 2012, no Windows 8, no Windows Server 2008 R2 ou no Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou no Windows Vista. Windows Installer no Windows Server 2003 ou no Windows XP
Plataforma de Destino Windows
Cabeçalho msiquery.h
Biblioteca Msi.lib
DLL Msi.dll

Confira também

Um exemplo de banco de dados e de patch

Funções gerais de acesso ao banco de dados