Funzione JetOpenFile

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetOpenFile

La funzione JetOpenFile apre un database collegato, un file di patch del database o un file di log delle transazioni di un'istanza attiva per l'esecuzione di un backup fuzzy di streaming. I dati di questi file possono essere letti successivamente tramite l'handle restituito usando JetReadFile. L'handle restituito deve essere chiuso usando JetCloseFile. Un backup esterno dell'istanza deve essere stato avviato in precedenza usando JetBeginExternalBackup.

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

Parametri

szFileName

Percorso relativo o assoluto di un database collegato, file di patch di database o file di log delle transazioni gestito dall'istanza che verrà letto per il backup.

phfFile

Buffer di output che riceve un handle per il file da leggere.

pulFileSizeLow

Buffer di output che riceve i 32 bit meno significativi delle dimensioni del file.

pulFileSizeHigh

Buffer di output che riceve i 32 bit più significativi delle dimensioni del file.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sugli errori ESE possibili, vedere Errori del motore di archiviazione estendibili e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errBackupAbortByServer	L'operazione non è riuscita perché il backup esterno corrente è stato interrotto da una chiamata a JetStopBackup. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività nell'istanza associata alla sessione non sono state interrotte in seguito a una chiamata a JetStopService.
JET_errFileAccessDenied	L'operazione non è riuscita perché non è stato possibile aprire il file richiesto a causa di una violazione della condivisione o di privilegi insufficienti.
JET_errFileNotFound	L'operazione non è riuscita perché non è stato possibile aprire il file richiesto perché non è stato possibile trovare nel percorso specificato. Questo errore verrà restituito solo da Windows 2000.
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede che l'accesso a tutti i dati venga revocato per proteggere l'integrità dei dati. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errInvalidBackupSequence	L'operazione di backup non è riuscita perché è stata chiamata fuori sequenza.
JET_errInvalidParameter	Uno dei parametri forniti contiene un valore imprevisto o contiene un valore che non ha senso quando si combina con il valore di un altro parametro. Questo può verificarsi per JetOpenFile quando: L'handle di istanza specificato non è valido (Windows XP e versioni successive). Il parametro del nome file specificato è NULL o una stringa di lunghezza zero (Windows XP e versioni successive).
JET_errInvalidPath	L'operazione non è riuscita perché non è stato possibile trovare il percorso specificato.
JET_errMissingFileToBackup	Impossibile aprire il file richiesto per il backup perché non è stato trovato. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errNoBackup	L'operazione non è riuscita perché non è in corso alcun backup esterno.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errOutOfMemory	L'operazione non è riuscita perché non è possibile allocare memoria sufficiente per completarla. JetOpenFile restituirà JET_errOutOfMemory se viene eseguito un tentativo di aprire un altro file prima dell'apertura del file precedente usando JetOpenFile è stato chiuso da JetCloseFile. Attualmente è supportato un solo handle di file in sospeso.
JET_errRunningInMultiInstanceMode	L'operazione non è riuscita perché è stato effettuato un tentativo di usare il motore in modalità legacy (modalità di compatibilità di Windows 2000) in cui è supportata solo un'istanza quando esistono già più istanze.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata. JET_errRestoreInProgress Non è possibile completare l'operazione perché un'operazione di ripristino è in corso nell'istanza associata alla sessione.

In caso di esito positivo, verrà restituito un handle al file richiesto. Se l'handle è per un file di database, tale file di database verrà preparato per il backup di streaming che potrebbe causare la creazione di un file di patch di database nella stessa posizione del file di database. Il file di patch del database ha lo stesso percorso e il nome file del file di database, ma ha un oggetto . Estensione PAT. Verrà restituita anche la dimensione del file.

In caso di errore, lo stato dei buffer di output non verrà definito. Un file di patch di database può essere creato temporaneamente sul disco e qualsiasi file esistente nel percorso del file di patch può essere eliminato. L'errore comporterà l'annullamento dell'intero processo di backup per l'istanza. In Windows XP e versioni successive il backup non verrà annullato se viene eseguito un tentativo di backup di un database non collegato all'istanza al momento della chiamata.

Avviso Per motivi di sicurezza, è importante notare che JetOpenFile non verifica che il percorso del file richiesto sia associato al set di file che devono essere sottoposti a backup per l'istanza. Di conseguenza, è possibile usare questa funzione per accedere a qualsiasi file che può essere aperto dal contesto di sicurezza corrente del thread. È imperativo che l'applicazione limita i percorsi passati a questa funzione a un set noto di percorsi di file validi o a una divulgazione di attacchi informativi può essere reso possibile.

Commenti

I buffer di output delle dimensioni del file e dell'handle devono essere presenti. Se non sono presenti, il motore si arresterà in modo anomalo perché i parametri del buffer di output non vengono convalidati.

In questo momento, è possibile aprire un solo file per il backup in qualsiasi momento.

JetOpenFile non afferma il privilegio di backup prima di aprire il file richiesto.

Le dimensioni del file da leggere come segnalato da questa funzione potrebbero non corrispondere alle dimensioni del file su disco. In Windows XP e versioni successive è possibile aggiungere informazioni aggiuntive a un file di database usato dal motore di database durante un'operazione di ripristino. Di conseguenza, l'applicazione deve basarsi solo sulle dimensioni del file restituite da JetOpenFile o sul numero effettivo di byte di dati restituiti da JetReadFile.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista, Windows XP o Windows 2000 Professional.
Server	Richiede Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.
Unicode	Implementato come JetOpenFileW (Unicode) e JetOpenFileA (ANSI).

Vedere anche

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

Condividi tramite

Funzione JetOpenFile