Функция JetOpenFileInstance
Применимо к: Windows | Windows Server
Функция JetOpenFileInstance
Функция JetOpenFileInstance открывает присоединенную базу данных, файл исправлений базы данных или файл журнала транзакций активного экземпляра для выполнения потоковой нечеткой резервной копии. Данные из этих файлов можно впоследствии считывать через возвращенный дескриптор с помощью JetReadFileInstance. Возвращаемый дескриптор должен быть закрыт с помощью JetCloseFileInstance. Внешняя резервная копия экземпляра должна быть ранее инициирована с помощью JetBeginExternalBackupInstance.
Windows XP:JetOpenFileInstance представлена в 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
);
Параметры
Экземпляр
Экземпляр, используемый для этого вызова.
Для Windows 2000 вариант API, который принимает этот параметр, недоступен, так как поддерживается только один экземпляр. В данном случае подразумевается использование этого одного глобального экземпляра.
Для Windows XP и более поздних версий вариант API, который не принимает этот параметр, может вызываться только в том случае, если подсистема находится в устаревшем режиме (режим совместимости Windows 2000), где поддерживается только один экземпляр. В противном случае операция завершится сбоем с JET_errRunningInMultiInstanceMode.
szFileName
Относительный или абсолютный путь к подключенной базе данных, файлу исправлений базы данных или файлу журнала транзакций, управляемому экземпляром, который считывается для резервного копирования.
phfFile
Указатель на выходной буфер, который получает дескриптор файла для чтения.
pulFileSizeLow
Указатель на выходной буфер, который получает наименьшие значимые 32 бита от размера файла.
pulFileSizeHigh
Указатель на выходной буфер, который получает наиболее значительные 32 бита от размера файла.
Возвращаемое значение
Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.
Код возврата |
Описание |
|---|---|
JET_errSuccess |
Операция выполнена успешно. |
JET_errBackupAbortByServer |
Операция завершилась сбоем, так как текущая внешняя резервная копия была прервана вызовом JetStopBackupInstance. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках. |
JET_errClientRequestToStopJetService |
Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopServiceInstance. |
JET_errFileAccessDenied |
Операция завершилась сбоем, так как ей не удалось открыть запрошенный файл из-за нарушения общего доступа или недостаточных привилегий. |
JET_errFileNotFound |
Операция завершилась сбоем, так как ей не удалось открыть запрошенный файл, так как его не удалось найти по указанному пути. Эта ошибка будет возвращена только Windows 2000. |
JET_errInvalidBackupSequence |
Операция резервного копирования завершилась сбоем, так как она была вызвана из последовательности. |
JET_errInvalidPath |
Операция завершилась сбоем, так как не удалось найти указанный путь. |
JET_errInstanceUnavailable |
Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках. |
JET_errInvalidParameter |
Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра. Это может произойти для JetOpenFileInstance в указанных ниже случаях.
|
JET_errMissingFileToBackup |
Не удалось открыть запрошенный файл для резервного копирования, так как его не удалось найти. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках. |
JET_errNoBackup |
Операция завершилась сбоем, так как внешнее резервное копирование не выполняется. |
JET_errNotInitialized |
Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован. |
JET_errOutOfMemory |
Операция завершилась сбоем, так как для ее завершения было выделено недостаточно памяти. JetOpenFileInstance возвращает JET_errOutOfMemory, если предпринята попытка открыть другой файл до того, как предыдущий файл, открытый с помощью JetOpenFileInstance , был закрыт JetCloseFileInstance. В настоящее время поддерживается только один необработанные дескриптор файла. |
JET_errRestoreInProgress |
Невозможно выполнить операцию, так как операция восстановления выполняется в экземпляре, связанном с сеансом. |
JET_errRunningInMultiInstanceMode |
Операция завершилась сбоем, так как была предпринята попытка использовать подсистему в устаревшем режиме (режим совместимости с Windows 2000), где поддерживается только один экземпляр, если на самом деле уже существует несколько экземпляров. |
JET_errTermInProgress |
Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, завершает работу. |
При успешном выполнении возвращается дескриптор запрошенного файла. Если дескриптор предназначен для файла базы данных, этот файл базы данных будет подготовлен для потоковой резервной копии, что может привести к созданию файла исправлений базы данных в том же расположении, что и файл базы данных. Файл исправлений базы данных имеет тот же путь и имя файла, что и файл базы данных, но с . Расширение PAT. Также будет возвращен размер файла.
При сбое состояние выходных буферов будет неопределенным. Файл исправлений базы данных может быть временно создан на диске, а любой существующий файл в расположении файла исправлений может быть удален. Сбой приведет к отмене всего процесса резервного копирования экземпляра. В Windows XP и более поздних выпусках резервное копирование не будет отменено, если была предпринята попытка создать резервную копию базы данных, которая не была подключена к экземпляру во время вызова.
Предупреждение В целях безопасности важно отметить, что JetOpenFileInstance не проверяет, связан ли запрошенный путь к файлу с набором файлов, резервные копии которых создаются для экземпляра. В результате можно использовать эту функцию для доступа к любому файлу, который может быть открыт текущим контекстом безопасности потока. Крайне важно, чтобы приложение ограничивло пути, передаваемые в эту функцию, известным набором хороших путей к файлам, иначе могла быть возможна атака на раскрытие информации.
Комментарии
Должны присутствовать буферы вывода дескриптора и размера файла. Если они отсутствуют, подсистема аварийно завершает работу, так как параметры выходного буфера не проверяются.
В настоящее время для резервного копирования можно одновременно открыть только один файл.
JetOpenFileInstance не утверждает привилегию резервного копирования перед открытием запрошенного файла.
Размер считываемого файла, сообщаемый этой функцией, может не совпадать с размером файла на диске. В Windows XP и более поздних версиях дополнительные сведения могут добавляться в файл базы данных, который используется ядром СУБД во время операции восстановления. Таким образом, приложение должно полагаться только на размер файла, возвращенный JetOpenFileInstance , или на фактическое количество байтов данных, возвращаемых JetReadFileInstance.
Требования
| Требование | Значение |
|---|---|
Клиент |
Требуется Windows Vista или Windows XP. |
Сервер |
Требуется Windows Server 2008 или Windows Server 2003. |
Верхняя часть |
Объявлено в Esent.h. |
Библиотека |
Используйте ESENT.lib. |
DLL |
Требуется ESENT.dll. |
Юникод |
Реализовано как JetOpenFileInstanceW (Юникод) и JetOpenFileInstanceA (ANSI). |
См. также:
JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance