Função JetOpenFile

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetOpenFile

A função JetOpenFile abre um banco de dados anexado, um arquivo de patch de banco de dados ou um arquivo de log de transações de uma instância ativa com a finalidade de executar um backup difuso de streaming. Os dados desses arquivos podem ser lidos posteriormente por meio do identificador retornado usando JetReadFile. O identificador retornado deve ser fechado usando JetCloseFile. Um backup externo da instância deve ter sido iniciado anteriormente usando JetBeginExternalBackup.

    JET_ERR JET_API JetOpenFile(
      __in          const tchar* szFileName,
      __out         JET_HANDLE* phfFile,
      __out         unsigned long* pulFileSizeLow,
      __out         unsigned long* pulFileSizeHigh
    );

Parâmetros

szFileName

O caminho relativo ou absoluto para um banco de dados anexado, arquivo de patch de banco de dados ou arquivo de log de transações gerenciado pela instância que será lida para backup.

phfFile

O buffer de saída que recebe um identificador para o arquivo a ser lido.

pulFileSizeLow

O buffer de saída que recebe os 32 bits menos significativos do tamanho do arquivo.

pulFileSizeHigh

O buffer de saída que recebe os 32 bits mais significativos do tamanho do arquivo.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos seguintes códigos de retorno. Para obter mais informações sobre os possíveis erros de ESE, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno	Descrição
JET_errSuccess	A operação foi concluída com sucesso.
JET_errBackupAbortByServer	A operação falhou porque o backup externo atual foi anulado por uma chamada para JetStopBackup. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errClientRequestToStopJetService	Não é possível concluir a operação porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.
Jet_errfileaccessdenied	A operação falhou porque não pôde abrir o arquivo solicitado devido a uma violação de compartilhamento ou privilégios insuficientes.
JET_errFileNotFound	A operação falhou porque não pôde abrir o arquivo solicitado porque ele não pôde ser encontrado no caminho especificado. Esse erro só será retornado pelo Windows 2000.
JET_errInstanceUnavailable	Não é possível concluir a operação porque a instância associada à sessão encontrou um erro fatal que exige que o acesso a todos os dados seja revogado para proteger a integridade desses dados. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errInvalidBackupSequence	A operação de backup falhou porque foi chamada fora de sequência.
JET_errInvalidParameter	Um dos parâmetros fornecidos continha um valor inesperado ou continha um valor que não fazia sentido quando combinado com o valor de outro parâmetro. Isso pode acontecer para JetOpenFile quando: O identificador de instância especificado é inválido (Windows XP e versões posteriores). O parâmetro filename especificado é NULL ou uma cadeia de caracteres de comprimento zero (Windows XP e versões posteriores).
JET_errInvalidPath	A operação falhou porque o caminho especificado não pôde ser encontrado.
JET_errMissingFileToBackup	O arquivo solicitado não pôde ser aberto para backup porque não foi possível encontrá-lo. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errNoBackup	A operação falhou porque nenhum backup externo está em andamento.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errOutOfMemory	A operação falhou porque não foi possível alocar memória suficiente para concluí-la. JetOpenFile retornará JET_errOutOfMemory se for feita uma tentativa de abrir outro arquivo antes que o arquivo anterior aberto usando JetOpenFile tenha sido fechado pelo JetCloseFile. Atualmente, há suporte para apenas um identificador de arquivo pendente.
JET_errRunningInMultiInstanceMode	A operação falhou porque foi feita uma tentativa de usar o mecanismo no modo herdado (modo de compatibilidade do Windows 2000) em que apenas uma instância tem suporte quando, na verdade, várias instâncias já existem.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada à sessão está sendo desligada. JET_errRestoreInProgress Não é possível concluir a operação porque uma operação de restauração está em andamento na instância associada à sessão.

Em caso de êxito, um identificador para o arquivo solicitado será retornado. Se o identificador for para um arquivo de banco de dados, esse arquivo de banco de dados será preparado para o backup de streaming, o que pode resultar na criação de um arquivo de patch de banco de dados no mesmo local que o arquivo de banco de dados. O arquivo de patch do banco de dados tem exatamente o mesmo caminho e nome de arquivo que o arquivo de banco de dados, mas tem um . Extensão pat. O tamanho do arquivo também será retornado.

Em caso de falha, o estado dos buffers de saída será indefinido. Um arquivo de patch de banco de dados pode ser criado temporariamente no disco e qualquer arquivo existente no local do arquivo de patch pode ser excluído. A falha resultará no cancelamento de todo o processo de backup para a instância. No Windows XP e versões posteriores, o backup não será cancelado se tiver sido feita uma tentativa de fazer backup de um banco de dados que não estava anexado à instância no momento da chamada.

Aviso Por motivos de segurança, é importante observar que o JetOpenFile não verifica se o caminho do arquivo solicitado está associado ao conjunto de arquivos que devem ser copiados em backup para a instância. Como resultado, é possível usar essa função para acessar qualquer arquivo que possa ser aberto pelo contexto de segurança atual do thread. É imperativo que o aplicativo restrinja os caminhos passados para essa função a um conjunto conhecido de bons caminhos de arquivo ou uma divulgação de ataque de informações possa ser possível.

Comentários

Os buffers de saída do identificador e do tamanho do arquivo devem estar presentes. Se eles não estiverem presentes, o mecanismo falhará porque os parâmetros de buffer de saída não serão validados.

No momento, apenas um arquivo pode ser aberto para backup a qualquer momento.

JetOpenFile não declara o privilégio de backup antes de abrir o arquivo solicitado.

O tamanho do arquivo a ser lido conforme relatado por essa função pode não corresponder ao tamanho do arquivo no disco. No Windows XP e versões posteriores, informações extras podem ser acrescentadas a um arquivo de banco de dados que é usado pelo mecanismo de banco de dados durante uma operação de restauração. Dessa forma, o aplicativo deve depender apenas do tamanho do arquivo retornado por JetOpenFile ou do número real de bytes de dados retornados pelo JetReadFile.

Requisitos

Requisito	Valor
Cliente	Requer Windows Vista, Windows XP ou Windows 2000 Professional.
Servidor	Requer o Windows Server 2008, o Windows Server 2003 ou o Windows 2000 Server.
Cabeçalho	Declarado em Esent.h.
Biblioteca	Use ESENT.lib.
DLL	Requer ESENT.dll.
Unicode	Implementado como JetOpenFileW (Unicode) e JetOpenFileA (ANSI).

Consulte Também

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackup
JetCloseFile
JetGetAttachInfo
JetGetLogInfo
JetReadFile
JetStopBackup
JetStopService
JetTruncateLog

Compartilhar via

Função JetOpenFile