Função JetGetAttachInfoInstance

Aplica-se a: Windows | Windows Server

Função JetGetAttachInfoInstance

A função JetGetAttachInfoInstance é usada durante um backup iniciado por JetBeginExternalBackupInstance para consultar uma instância para os nomes dos arquivos de banco de dados que devem se tornar parte do conjunto de arquivos de backup. Somente os bancos de dados que estão atualmente anexados à instância usando JetAttachDatabase serão considerados. Esses arquivos podem ser abertos posteriormente usando JetOpenFileInstance e lidos usando JetReadFileInstance.

Windows XP: JetGetAttachInfoInstance é introduzido no Windows XP.

    JET_ERR JET_API JetGetAttachInfoInstance(
      __in          JET_INSTANCE instance,
      __out_opt     tchar* szz,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

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 da 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.

Szz

O buffer de saída que recebe a lista de cadeias de caracteres terminadas nulas que descrevem o conjunto de arquivos de banco de dados que deve fazer parte do conjunto de arquivos de backup. A lista de cadeias de caracteres retornadas nesse buffer está no mesmo formato que uma cadeia de caracteres múltipla usada pelo registro. Cada cadeia de caracteres terminada em nulo é retornada em sequência seguida por um terminador nulo final.

cbMax

O tamanho máximo em bytes do buffer de saída.

pcbActual

Ponteiro para o buffer de saída que recebe a quantidade real de dados de cadeia de caracteres.

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 do 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_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. JetGetAttachInfoInstance retornará esse erro se o backup atual não for um backup completo.
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 JetGetAttachInfoInstance quando o identificador de instância especificado é inválido (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_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.

Com êxito, as informações solicitadas sobre o conjunto de arquivos de banco de dados que devem fazer parte do conjunto de arquivos de backup serão colocadas nos buffers de saída, quando fornecidos.

Em caso de falha, o estado dos buffers de saída é indefinido. A falha resultará no cancelamento de todo o processo de backup da instância.

Comentários

É importante observar que essa API não retorna um erro ou aviso se o buffer de saída for muito pequeno para aceitar a lista completa de arquivos que devem fazer parte do conjunto de arquivos de backup. O aplicativo sempre deve fornecer um buffer para receber o tamanho real dessa lista e usar essas informações para determinar se a lista foi truncada.

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 JetGetAttachInfoInstanceW (Unicode) e JetGetAttachInfoInstanceA (ANSI).

Consulte Também

JET_ERR
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetOpenFileInstance
JetReadFileInstance
JetStopBackupInstance
JetStopServiceInstance