Funzione JetOpenFileInstance

Si applica a: Windows | Windows Server

Funzione JetOpenFileInstance

La funzione JetOpenFileInstance apre un database collegato, un file di patch del database o un file di log delle transazioni di un'istanza attiva allo scopo di eseguire un backup fuzzy di streaming. I dati di questi file possono essere letti successivamente tramite l'handle restituito usando JetReadFileInstance. L'handle restituito deve essere chiuso usando JetCloseFileInstance. Un backup esterno dell'istanza deve essere stato avviato in precedenza usando JetBeginExternalBackupInstance.

Windows XP:JetOpenFileInstance è stato introdotto in 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
    );

Parametri

Istanza

Istanza da utilizzare per questa chiamata.

Per Windows 2000, la variante API che accetta questo parametro non è disponibile perché è supportata una sola istanza. L'uso di questa istanza globale è implicito in questo caso.

Per Windows XP e versioni successive, la variante DELL'API che non accetta questo parametro può essere chiamata solo quando il motore è in modalità legacy (modalità di compatibilità di Windows 2000) in cui è supportata una sola istanza. In caso contrario, l'operazione avrà esito negativo con JET_errRunningInMultiInstanceMode.

szFileName

Percorso relativo o assoluto di un database collegato, un file di patch del database o un file di log delle transazioni gestito dall'istanza di lettura per il backup.

phfFile

Puntatore al buffer di output che riceve un handle per il file da leggere.

pulFileSizeLow

Puntatore al buffer di output che riceve i 32 bit meno significativi delle dimensioni del file.

pulFileSizeHigh

Puntatore al 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 sui possibili errori ESE, vedere Errori del motore di archiviazione estendibile 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 JetStopBackupInstance. 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 sono cessate a seguito di una chiamata a JetStopServiceInstance.
JET_errFileAccessDenied	L'operazione non è riuscita perché non è stato possibile aprire il file richiesto a causa di una violazione di condivisione o di privilegi insufficienti.
JET_errFileNotFound	L'operazione non è riuscita perché non è stato possibile aprire il file richiesto perché non è stato trovato nel percorso specificato. Questo errore verrà restituito solo da Windows 2000.
JET_errInvalidBackupSequence	L'operazione di backup non è riuscita perché è stata chiamata fuori sequenza.
JET_errInvalidPath	L'operazione non è riuscita perché non è stato possibile trovare il percorso specificato.
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede la revoca dell'accesso a tutti i dati per proteggere l'integrità dei dati. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errInvalidParameter	Uno dei parametri forniti conteneva un valore imprevisto o conteneva un valore che non ha senso se combinato con il valore di un altro parametro. Ciò può verificarsi per JetOpenFileInstance 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_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. JetOpenFileInstance restituirà JET_errOutOfMemory se si tenta di aprire un altro file prima che il file precedente aperto con JetOpenFileInstance sia stato chiuso da JetCloseFileInstance. Attualmente è supportato un solo handle di file in sospeso.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata alla sessione.
JET_errRunningInMultiInstanceMode	L'operazione non è riuscita perché è stato effettuato un tentativo di utilizzo del motore in modalità legacy (modalità di compatibilità di Windows 2000), in cui è supportata solo un'istanza quando esistono effettivamente più istanze.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.

In caso di esito positivo, viene restituito un handle per il file richiesto. Se l'handle è relativo a un file di database, tale file di database verrà preparato per un backup di streaming che può comportare la creazione di un file di patch di database nella stessa posizione del file di database. Il file patch del database ha lo stesso percorso e il nome file del file di database, ma con . Estensione PAT. Verranno restituite anche le dimensioni del file.

In caso di errore, lo stato dei buffer di output non sarà definito. È possibile creare temporaneamente un file patch di database su disco e qualsiasi file esistente nel percorso del file 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 è stato effettuato un tentativo di backup di un database non collegato all'istanza al momento della chiamata.

Avviso Per motivi di sicurezza, è importante notare che JetOpenFileInstance non verifica che il percorso del file richiesto sia associato al set di file di cui viene eseguito il backup per l'istanza. Di conseguenza, è possibile usare questa funzione per accedere a qualsiasi file che possa essere aperto dal contesto di sicurezza corrente del thread. È fondamentale che l'applicazione limiti i percorsi passati a questa funzione a un set noto di percorsi di file validi o la divulgazione di un attacco informativo possa essere reso possibile.

Commenti

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

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

JetOpenFileInstance non dichiara 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 utilizzato dal motore di database durante un'operazione di ripristino. Di conseguenza, l'applicazione deve basarsi solo sulle dimensioni del file restituite da JetOpenFileInstance o sul numero effettivo di byte di dati restituiti da JetReadFileInstance.

Requisiti

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

Vedere anche

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance