Função JetOpenFileInstance
Aplica-se a: Windows | Windows Server
Função JetOpenFileInstance
A função JetOpenFileInstance 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 JetReadFileInstance. O identificador retornado deve ser fechado usando JetCloseFileInstance. Um backup externo da instância deve ter sido iniciado anteriormente usando JetBeginExternalBackupInstance.
O Windows XP:JetOpenFileInstance é introduzido no Windows XP.
JET_ERR JET_API JetOpenFileInstance(
__in JET_INSTANCE instance,
__in JET_PCSTR szFileName,
__out JET_HANDLE* phfFile,
__out unsigned long* pulFileSizeLow,
__out unsigned long* pulFileSizeHigh
);
Parâmetros
instance
A instância a ser usada para essa chamada.
Para o Windows 2000, a variante de API que aceita esse parâmetro não está disponível porque há suporte apenas para uma instância. O uso dessa instância global está implícito nesse caso.
Para o Windows XP e versões posteriores, a variante de API que não aceita esse parâmetro só pode ser chamada quando o mecanismo está no modo herdado (modo de compatibilidade do Windows 2000) em que há suporte apenas para uma instância. Caso contrário, a operação falhará com JET_errRunningInMultiInstanceMode.
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 é lida para backup.
phfFile
Ponteiro para o buffer de saída que recebe um identificador para o arquivo a ser lido.
pulFileSizeLow
Ponteiro para o buffer de saída que recebe os 32 bits menos significativos do tamanho do arquivo.
pulFileSizeHigh
Ponteiro para 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 JetStopBackupInstance. 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 JetStopServiceInstance. |
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_errInvalidBackupSequence |
A operação de backup falhou porque foi chamada fora de sequência. |
JET_errInvalidPath |
A operação falhou porque o caminho especificado não pôde ser encontrado. |
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_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 JetOpenFileInstance quando:
|
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. JetOpenFileInstance retornará JET_errOutOfMemory se for feita uma tentativa de abrir outro arquivo antes que o arquivo anterior aberto usando JetOpenFileInstance tenha sido fechado pelo JetCloseFileInstance. Atualmente, há suporte para apenas um identificador de arquivo pendente. |
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. |
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. |
Em caso de êxito, um identificador para o arquivo solicitado é retornado. Se o identificador for para um arquivo de banco de dados, esse arquivo de banco de dados será preparado para um backup de streaming 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 com 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 JetOpenFileInstance não verifica se o caminho do arquivo solicitado está associado ao conjunto de arquivos que são 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.
JetOpenFileInstance 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 JetOpenFileInstance ou do número real de bytes de dados retornados por JetReadFileInstance.
Requisitos
| Requisito | Valor |
|---|---|
Cliente |
Requer o Windows Vista ou o Windows XP. |
Servidor |
Requer o Windows Server 2008 ou o Windows Server 2003. |
Cabeçalho |
Declarado em Esent.h. |
Biblioteca |
Use ESENT.lib. |
DLL |
Requer ESENT.dll. |
Unicode |
Implementado como JetOpenFileInstanceW (Unicode) e JetOpenFileInstanceA (ANSI). |
Consulte Também
JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance