Функция CreateFileFromAppW (fileapifromapp.h)

Статья
03/09/2023

Создает или открывает файл или устройство ввода-вывода. Поведение этой функции идентично Функции CreateFile, за исключением того, что эта функция соответствует модели безопасности приложений универсальная платформа Windows.

Синтаксис

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

Параметры

lpFileName

Имя создаваемого или открываемого файла или устройства. В этом имени можно использовать косую черту (/) или обратную косую черту (\).

В версии ANSI этой функции имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, вызовите версию Функции в Юникоде и добавьте "\?\" к пути. Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Сведения о специальных именах устройств см. в разделе Определение имени устройства MS-DOS.

Чтобы создать файловый поток, укажите имя файла, двоеточие, а затем имя потока. Дополнительные сведения см. в разделе Файловые потоки.

Для версии этой функции в Юникоде (CreateFileFromAppW) можно согласиться на удаление ограничения MAX_PATH без добавления "\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

dwDesiredAccess

Запрошенный доступ к файлу или устройству, который можно суммировать как для чтения, записи, так и для нулевого значения.

Чаще всего используются значения GENERIC_READ, GENERIC_WRITE или оба (GENERIC_READ | GENERIC_WRITE). Дополнительные сведения см. в разделах Общие права доступа, Безопасность файлов и Права доступа, Константы прав доступа к файлам и ACCESS_MASK.

Если этот параметр равен нулю, приложение может запрашивать определенные метаданные, такие как атрибуты файла, каталога или устройства, без доступа к этому файлу или устройству, даже если GENERIC_READ доступ был бы запрещен.

Невозможно запросить режим доступа, конфликтующий с режимом общего доступа, заданным параметром dwShareMode в открытом запросе, который уже имеет открытый дескриптор.

dwShareMode

Запрошенный режим общего доступа к файлу или устройству, который можно читать, записывать, удалять, все или нет (см. следующую таблицу). Этот флаг не влияет на запросы доступа к атрибутам или расширенным атрибутам.

Значение	Значение
0 0x00000000	Запрещает другим процессам открывать файл или устройство, если они запрашивают доступ к удалению, чтению или записи.
0x00000004 FILE_SHARE_DELETE	Позволяет последующим операциям открытия файла или устройства запрашивать доступ к удалению. В противном случае другие процессы не смогут открыть файл или устройство при запросе на удаление доступа. Если этот флаг не указан, но файл или устройство были открыты для доступа к удалению, функция завершается ошибкой. Примечание Доступ к удалению позволяет выполнять операции удаления и переименования.
0x00000001 FILE_SHARE_READ	Позволяет последующим операциям открытия файла или устройства запрашивать доступ на чтение. В противном случае другие процессы не смогут открыть файл или устройство, если они запрашивают доступ на чтение. Если этот флаг не указан, но файл или устройство были открыты для чтения, функция завершается ошибкой.
0x00000002 FILE_SHARE_WRITE	Позволяет последующим операциям открытия файла или устройства запрашивать доступ на запись. В противном случае другие процессы не смогут открыть файл или устройство, если они запрашивают доступ на запись. Если этот флаг не указан, но файл или устройство были открыты для доступа на запись или имеет сопоставление файлов с доступом на запись, функция завершается ошибкой.

lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , содержащую два отдельных, но связанных элемента данных: необязательный дескриптор безопасности и логическое значение, определяющее, может ли возвращаемый дескриптор наследоваться дочерними процессами.

Этот параметр может принимать значение NULL.

Если этот параметр имеет значение NULL, возвращенный дескриптор не может наследоваться никакими дочерними процессами, которые может создать приложение, а файл или устройство, связанные с возвращенным дескриптором, получают дескриптор безопасности по умолчанию.

Элемент lpSecurityDescriptor структуры указывает SECURITY_DESCRIPTOR для файла или устройства. Если этот элемент имеет значение NULL, файлу или устройству, связанному с возвращенным дескриптором, назначается дескриптор безопасности по умолчанию.

Эта функция игнорирует член lpSecurityDescriptor при открытии существующего файла или устройства, но продолжает использовать элемент bInheritHandle .

Член структуры bInheritHandle указывает, можно ли наследовать возвращаемый дескриптор.

dwCreationDisposition

Действие, выполняемое с файлом или устройством, которые существуют или не существуют.

Для устройств, отличных от файлов, этот параметр обычно имеет значение OPEN_EXISTING.

Дополнительные сведения см. в разделе «Примечания».

Этот параметр должен иметь одно из следующих значений, которые нельзя объединить:

Значение	Значение
CREATE_ALWAYS 2	Всегда создает новый файл. Если указанный файл существует и доступен для записи, функция усекает файл, выполняется успешно, а для кода последней ошибки задано значение ERROR_ALREADY_EXISTS (183). Если указанный файл не существует и является допустимым путем, создается новый файл, функция завершается успешно, а код последней ошибки равен нулю. Дополнительные сведения см. в разделе Примечания этой статьи.
CREATE_NEW 1	Создает новый файл, только если он еще не существует. Если указанный файл существует, функция завершается сбоем, а для кода последней ошибки задано значение ERROR_FILE_EXISTS (80). Если указанный файл не существует и является допустимым путем к расположению, доступному для записи, создается новый файл.
OPEN_ALWAYS 4	Всегда открывает файл. Если указанный файл существует, функция выполняется успешно, а для кода последней ошибки задано значение ERROR_ALREADY_EXISTS (183). Если указанный файл не существует и является допустимым путем к расположению, доступному для записи, функция создает файл, а код последней ошибки равен нулю.
OPEN_EXISTING 3	Открывает файл или устройство, только если они существуют. Если указанный файл или устройство не существует, функция завершается сбоем, а для кода последней ошибки задано значение ERROR_FILE_NOT_FOUND (2). Дополнительные сведения об устройствах см. в разделе Примечания.
TRUNCATE_EXISTING 5	Открывает файл и усекает его таким образом, чтобы его размер был равен нулю байтов, только если он существует. Если указанный файл не существует, функция завершается сбоем, а код последней ошибки имеет значение ERROR_FILE_NOT_FOUND (2). Вызывающий процесс должен открыть файл с битом GENERIC_WRITE , заданным как часть параметра dwDesiredAccess .

dwFlagsAndAttributes

Атрибуты и флаги файла или устройства FILE_ATTRIBUTE_NORMAL являются наиболее распространенным значением по умолчанию для файлов.

Этот параметр может включать любое сочетание доступных атрибутов файла (FILE_ATTRIBUTE_*). Все остальные атрибуты файла переопределяют FILE_ATTRIBUTE_NORMAL.

Этот параметр также может содержать сочетания флагов (FILE_FLAG_*) для управления поведением кэширования файлов или устройств, режимов доступа и других специальных флагов. Они объединяются со значениями FILE_ATTRIBUTE_* .

Этот параметр также может содержать сведения о качестве обслуживания системы безопасности (SQOS), указав флаг SECURITY_SQOS_PRESENT . Дополнительные сведения о флагах, связанных с SQOS, представлены в таблице после таблиц атрибутов и флагов.

attribute	Значение
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Файл должен быть архивирован. Приложения используют этот атрибут, чтобы отмечать файлы для резервного копирования или удаления.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	Файл или каталог зашифрован. Для файла это означает, что все данные в файле зашифрованы. Для каталога это означает, что шифрование используется по умолчанию для вновь созданных файлов и подкаталогов. Дополнительные сведения см. в разделе Шифрование файлов. Этот флаг не действует, если также указан FILE_ATTRIBUTE_SYSTEM . Этот флаг не поддерживается в выпусках Windows Home, Home Premium, Starter или ARM.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Файл скрыт. Не включайте его в обычный список каталогов.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	В файле не заданы другие атрибуты. При использовании этого атрибута не допускается использование других атрибутов.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Данные файла доступны не сразу. Этот атрибут указывает, что данные файлов физически перемещаются в автономное хранилище. Этот атрибут используется удаленным хранилищем, программным обеспечением для управления иерархическим хранилищем. Приложения не должны произвольно изменять этот атрибут.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Файл доступен только для чтения. Приложения могут считывать файл, но не могут записывать или удалять его.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Файл является частью операционной системы или используется исключительно в ней.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Файл используется для временного хранения. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.

Flag	Значение
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Файл открывается или создается для резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверки безопасности файлов, если у процесса есть SE_BACKUP_NAME и SE_RESTORE_NAME привилегии. Дополнительные сведения см. в разделе Изменение привилегий в токене. Этот флаг необходимо задать, чтобы получить дескриптор каталога. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файла. Дополнительные сведения см. в разделе «Примечания».
0x04000000 FILE_FLAG_DELETE_ON_CLOSE	Файл будет удален сразу после закрытия всех его дескрипторов, включая указанный дескриптор и другие открытые или дублирующиеся дескрипторы. Если для файла имеются открытые дескрипторы, вызов завершается ошибкой, если только они не были открыты в режиме общего доступа FILE_SHARE_DELETE . Последующие запросы на открытие файла завершатся сбоем, если только не указан режим совместного использования FILE_SHARE_DELETE.
FILE_FLAG_NO_BUFFERING 0x20000000	Файл или устройство открывается без системного кэширования для операций чтения и записи данных. Этот флаг не влияет на кэширование жесткого диска или сопоставленные файлы в памяти. Существуют строгие требования к успешной работе с файлами, открытыми с помощью этой функции с помощью флага FILE_FLAG_NO_BUFFERING . Дополнительные сведения см. в разделе Буферизация файлов.
0x00100000 FILE_FLAG_OPEN_NO_RECALL	Данные файла запрашивается, но они должны по-прежнему находиться в удаленном хранилище. Его не следует переносить обратно в локальное хранилище. Этот флаг предназначен для использования системами удаленного хранения.
0x00200000 FILE_FLAG_OPEN_REPARSE_POINT	Обычная обработка точек повторного обработки не выполняется; Эта функция попытается открыть точку повторного извлечения. При открытии файла возвращается дескриптор файла, независимо от того, работает ли фильтр, управляющий точкой повторного определения. Этот флаг нельзя использовать с флагом CREATE_ALWAYS . Если файл не является точкой повторного извлечения, этот флаг игнорируется. Дополнительные сведения см. в разделе «Примечания».
FILE_FLAG_OVERLAPPED 0x40000000	Файл или устройство открывается или создается для асинхронного ввода-вывода. После завершения последующих операций ввода-вывода для этого дескриптора событие, указанное в структуре OVERLAPPED , будет установлено в состояние сигнала. Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED . Сведения об использовании дескриптора файла, созданного с помощью этого флага, см. в разделе Синхронные и асинхронные дескрипторы ввода-вывода этой статьи.
FILE_FLAG_POSIX_SEMANTICS 0x0100000	Доступ будет осуществляться в соответствии с правилами POSIX. Это включает в себя разрешение нескольких файлов с именами, отличающимися только в случае, для файловой системы, поддерживающей такое именование. Будьте внимательны при использовании этого параметра, так как файлы, созданные с этим флагом, могут быть недоступны приложениям, написанным для MS-DOS или 16-разрядной версии Windows.
0x10000000 FILE_FLAG_RANDOM_ACCESS	Доступ должен быть случайным. Система может использовать это в качестве указания для оптимизации кэширования файлов. Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.
0x00800000 FILE_FLAG_SESSION_AWARE	Файл или устройство открывается с поддержкой сеанса. Если этот флаг не указан, то устройства для каждого сеанса (например, устройства, использующие перенаправление USB RemoteFX) не могут быть открыты процессами, запущенными в сеансе 0. Этот флаг не действует для вызывающих абонентов, не в сеансе 0. Этот флаг поддерживается только в серверных выпусках Windows.
0x08000000 FILE_FLAG_SEQUENTIAL_SCAN	Доступ должен быть последовательным от начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов. Этот флаг не следует использовать, если будет использоваться режим чтения программной части (т. е. обратные проверки). Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.
0x80000000 FILE_FLAG_WRITE_THROUGH	Операции записи не будут проходить через промежуточный кэш, они будут отправляться непосредственно на диск. Дополнительные сведения см. в разделе Поведение кэширования этой статьи.

Параметр dwFlagsAndAttributesтакже может указывать сведения о SQOS. Дополнительные сведения см. в разделе Уровни олицетворения. Если вызывающее приложение указывает флаг SECURITY_SQOS_PRESENT в составе dwFlagsAndAttributes, оно также может содержать одно или несколько следующих значений.

Флаг безопасности	Значение
SECURITY_ANONYMOUS	Олицетворяет клиента на уровне анонимного олицетворения.
SECURITY_CONTEXT_TRACKING	Режим отслеживания безопасности является динамическим. Если этот флаг не указан, режим отслеживания безопасности является статическим.
SECURITY_DELEGATION	Олицетворяет клиента на уровне олицетворения делегирования.
SECURITY_EFFECTIVE_ONLY	Серверу доступны только включенные аспекты контекста безопасности клиента. Если этот флаг не указан, будут доступны все аспекты контекста безопасности клиента. Это позволяет клиенту ограничить группы и привилегии, которые сервер может использовать при олицетворении клиента.
SECURITY_IDENTIFICATION	Олицетворяет клиента на уровне олицетворения идентификации.
SECURITY_IMPERSONATION	Олицетворение клиента на уровне олицетворения. Это поведение по умолчанию, если другие флаги не указаны вместе с флагом SECURITY_SQOS_PRESENT .

hTemplateFile

Допустимый дескриптор файла шаблона с правом доступа GENERIC_READ . Файл шаблона предоставляет атрибуты файла и расширенные атрибуты для создаваемого файла.

Этот параметр может принимать значение NULL.

При открытии существующего файла этот параметр игнорируется.

При открытии нового зашифрованного файла файл наследует список управления доступом на уровне пользователей из родительского каталога. Дополнительные сведения см. в разделе Шифрование файлов.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение представляет собой открытый дескриптор для указанного файла, устройства, именованного канала или почтового слота.

Если функция завершается неудачно, возвращается значение INVALID_HANDLE_VALUE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Требования


Минимальная версия клиента	Windows 10 версии 1803
Верхняя часть	fileapifromapp.h