Função MsiOpenDatabaseA (msiquery.h)

Artigo
11/20/2024

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 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, transact mode read/write.
MSIDBOPEN_DIRECT	Abra uma leitura/gravação direta do banco de dados sem transação.
MSIDBOPEN_READONLY	Abra um banco de dados somente leitura, sem alterações persistentes.
MSIDBOPEN_TRANSACT	Abra uma leitura/gravação de banco de dados 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.

Valor de retorno

A função msiOpenDatabase retorna os seguintes valores:

Observações

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 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 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, consulte Usar PMSIHANDLE em vez da seção HANDLE node Práticas Recomendadas do Instalador do Windows .

Observação Quando um banco de dados é aberto como a 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 é mantido 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Installer 5.0 no Windows Server 2012, Windows 8, Windows Server 2008 R2 ou Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou Windows Vista. Windows Installer no Windows Server 2003 ou Windows XP
da Plataforma de Destino	Windows
cabeçalho	msiquery.h
biblioteca	Msi.lib
de DLL	Msi.dll

Consulte também

um banco de dados e um exemplo de patch

Funções gerais de acesso ao banco de dados

Compartilhar via