Функция OpenFileById (winbase.h)
Открывает файл, соответствующий указанному идентификатору.
Синтаксис
HANDLE OpenFileById(
[in] HANDLE hVolumeHint,
[in] LPFILE_ID_DESCRIPTOR lpFileId,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwFlagsAndAttributes
);
Параметры
[in] hVolumeHint
Дескриптор любого файла в томе или общей папке, в которой хранится файл, который должен быть открыт.
[in] lpFileId
Указатель на FILE_ID_DESCRIPTOR , определяющий открываемую папку.
[in] dwDesiredAccess
Доступ к объекту . Доступ может быть для чтения, записи или и того, и другого.
Дополнительные сведения см. в разделе Безопасность файлов и права доступа. Нельзя запросить режим доступа, который конфликтует с режимом общего доступа, указанным в открытом запросе с открытым дескриптором.
Если этот параметр равен нулю (0), приложение может запрашивать атрибуты файла и устройства без доступа к устройству. Это полезно для приложения, чтобы определить размер дисковода гибких дисков и поддерживаемые им форматы без необходимости использовать гибкие диски на диске. Его также можно использовать для проверки существования файла или каталога, не открывая их для чтения или записи.
[in] dwShareMode
Режим совместного использования объекта, который может быть считывается, записывается, как, так и нет.
Нельзя запросить режим общего доступа, конфликтующий с режимом доступа, указанным в открытом запросе с открытым дескриптором, так как это приведет к следующему нарушению общего доступа: (ERROR_SHARING_VIOLATION). Дополнительные сведения см. в разделе Создание и открытие файлов.
Если этот параметр равен нулю (0) и OpenFileById выполняется успешно, объект не может быть общим и не может быть открыт снова, пока не будет закрыт дескриптор. Дополнительные сведения см. в разделе Примечания этого раздела.
Параметры общего доступа остаются в силе, пока вы не закроете дескриптор для объекта.
Чтобы позволить процессам совместно использовать объект, в то время как объект открыт другим процессом, используйте сочетание одного или нескольких из следующих значений, чтобы указать режим доступа, который они могут запрашивать для открытия объекта.
[in, optional] lpSecurityAttributes
Зарезервировано.
[in] dwFlagsAndAttributes
Флаги файла.
Когда OpenFileById открывает файл, он объединяет флаги файла с существующими атрибутами файла и игнорирует все предоставленные атрибуты файла. Этот параметр может включать любое сочетание следующих флагов.
| Значение | Значение |
|---|---|
|
Файл открывается для резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверки безопасности файлов, если у процесса есть SE_BACKUP_NAME и SE_RESTORE_NAME привилегии. Дополнительные сведения см. в разделе Изменение привилегий в токене.
Этот флаг необходимо задать, чтобы получить дескриптор каталога. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файла. Дополнительные сведения см. в разделе Дескрипторы каталогов. |
|
Система открывает файл без системного кэширования. Этот флаг не влияет на кэширование жесткого диска. В сочетании с FILE_FLAG_OVERLAPPED флаг обеспечивает максимальную асинхронную производительность, так как операции ввода-вывода не зависят от синхронных операций диспетчера памяти. Однако некоторые операции ввода-вывода занимают больше времени, так как данные не хранятся в кэше. Кроме того, метаданные файла могут по-прежнему кэшироваться. Чтобы записать метаданные на диск, используйте функцию FlushFileBuffers .
Приложение должно соответствовать определенным требованиям при работе с файлами, которые открываются с помощью FILE_FLAG_NO_BUFFERING:
Приложение может определить размер сектора тома, вызвав функцию GetDiskFreeSpace . |
|
Данные файла запрашивается, но они должны по-прежнему находиться в удаленном хранилище. Его не следует переносить обратно в локальное хранилище. Этот флаг предназначен для использования системами удаленного хранения. |
|
При использовании этого флага обычная обработка точки повторного определения не выполняется, и OpenFileById пытается открыть точку повторного определения. При открытии файла возвращается дескриптор файла, независимо от того, работает ли фильтр, управляющий точкой повторного определения. Этот флаг нельзя использовать с флагом CREATE_ALWAYS . Если файл не является точкой повторного извлечения, этот флаг игнорируется. |
|
Файл открывается или создается для асинхронного ввода-вывода. После завершения операции событие, указанное для вызова в структуре OVERLAPPED , задается в состояние сигнала. Операции, которые занимают значительное количество времени для обработки возвращаемых ERROR_IO_PENDING.
Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Система не поддерживает указатель на файл, поэтому необходимо передать положение файла в функции чтения и записи в структуре OVERLAPPED или обновить указатель файла. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED . |
|
Доступ к файлу осуществляется случайным образом. Система может использовать это в качестве указания для оптимизации кэширования файлов. |
|
Доступ к файлу осуществляется последовательно от начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов. Если приложение перемещает указатель файла для произвольного доступа, оптимальное кэширование может не происходить. Тем не менее, правильная операция по-прежнему гарантируется.
Указание этого флага может повысить производительность приложений, которые считывают большие файлы с помощью последовательного доступа. Повышение производительности может быть еще более заметным для приложений, которые считывают большие файлы в основном последовательно, но иногда пропускают небольшие диапазоны байтов. |
|
Система записывает данные через любой промежуточный кэш и переходит непосредственно на диск.
Если FILE_FLAG_NO_BUFFERING также не указан, так что действует системное кэширование, данные записываются в системный кэш, но сбрасываются на диск без задержки. Если также указано FILE_FLAG_NO_BUFFERING , чтобы системное кэширование не действовало, данные немедленно сбрасываются на диск без прохождения системного кэша. Операционная система также запрашивает запись кэша жесткого диска на постоянный носитель. Однако не все оборудование поддерживает эту возможность записи. |
Возвращаемое значение
Если функция завершается успешно, возвращается открытый дескриптор на указанный файл.
Если функция завершается неудачно, возвращается значение INVALID_HANDLE_VALUE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Используйте функцию CloseHandle для закрытия дескриптора объекта, возвращаемого OpenFileById .
При вызове OpenFileById для файла, ожидающего удаления в результате предыдущего вызова DeleteFile, функция завершается ошибкой. Операционная система задерживает удаление файла, пока не будут закрыты все дескрипторы файла. GetLastError возвращает ERROR_ACCESS_DENIED.
В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.
| Технология | Поддерживается |
|---|---|
| Протокол SMB 3.0 | Нет |
| SMB 3.0 Transparent Failover (TFO) | Нет |
| SMB 3.0 с масштабируемыми общими папками (SO) | Нет |
| Файловая система общего тома кластера (CSVFS) | Да |
| Восстанавливаемая файловая система (ReFS) | Да |
Требования
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbase.h (включая Windows.h) |
| Библиотека | Kernel32.lib; ФайлExtd.lib в Windows Server 2003 и Windows XP |
| DLL | Kernel32.dll |
| Распространяемые компоненты | Windows SDK в Windows Server 2003 и Windows XP. |