JetOpenFile Function

Applies to: Windows | Windows Server

JetOpenFile Function

The JetOpenFile function opens an attached database, database patch file, or transaction log file of an active instance for the purpose of performing a streaming fuzzy backup. The data from these files can subsequently be read through the returned handle using JetReadFile. The returned handle must be closed using JetCloseFile. An external backup of the instance must have been previously initiated using JetBeginExternalBackup.

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

Parameters

szFileName

The relative or absolute path to an attached database, database patch file, or transaction log file managed by the instance that will be read for backup.

phfFile

The output buffer that receives a handle to the file to be read.

pulFileSizeLow

The output buffer that receives the least significant 32 bits of the size of the file.

pulFileSizeHigh

The output buffer that receives the most significant 32 bits of the size of the file.

Return Value

This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

On success, a handle to the requested file will be returned. If the handle is for a database file, that database file will be prepared for streaming backup which may result in the creation of a database patch file in the same location as the database file. The database patch file has the exact same path and filename as the database file, but has a .PAT extension. The size of the file will also be returned.

On failure, the state of the output buffers will be undefined. A database patch file may be temporarily created on disk and any existing file at the patch file location may be deleted. The failure will result in the cancellation of the entire backup process for the instance. On Windows XP and later releases, the backup will not be canceled if an attempt was made to backup a database that was not attached to the instance at the time of the call.

Warning  For security reasons, it is important to note that JetOpenFile does not verify that the requested file path is associated with the set of files that should be backed up for the instance. As a result, it is possible to use this function to access any file that can be opened by the current security context of the thread. It is imperative that the application restrict the paths passed to this function to a known set of good file paths or a disclosure of information attack could be made possible.

Remarks

The handle and file size output buffers are required to be present. If they are not present then the engine will crash because the output buffer parameters are not validated.

At this time, only one file can be open for backup at any one time.

JetOpenFile does not assert the backup privilege prior to opening the requested file.

The size of the file to be read as reported by this function may not match the size of the file on disk. On Windows XP and later releases, extra information may be appended to a database file which is used by the database engine during a restore operation. As such, the application should only rely on the file size returned by JetOpenFile or on the actual number of bytes of data returned by JetReadFile.

Requirements

See Also

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