Функция CreateFileFromAppW (fileapifromapp.h)
Создает или открывает файл или устройство ввода-вывода. Поведение этой функции идентично 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 | Запрещает другим процессам открывать файл или устройство, если они запрашивают доступ на удаление, чтение или запись. |
| FILE_SHARE_DELETE 0x00000004 | Позволяет последующим операциям открытия на файле или устройстве запрашивать доступ к удалению. В противном случае другие процессы не могут открыть файл или устройство, если они запрашивают доступ к удалению. Если этот флаг не указан, но файл или устройство было открыто для удаления, функция завершается ошибкой. Примечание Доступ к удалению позволяет выполнять операции удаления и переименования. |
| FILE_SHARE_READ 0x00000001 | Позволяет последующим операциям открытия на файле или устройстве запрашивать доступ на чтение. В противном случае другие процессы не могут открыть файл или устройство, если они запрашивают доступ на чтение. Если этот флаг не указан, но файл или устройство было открыто для доступа на чтение, функция завершается ошибкой. |
| FILE_SHARE_WRITE 0x00000002 | Позволяет последующим операциям открытия на файле или устройстве запрашивать доступ на запись. В противном случае другие процессы не могут открыть файл или устройство, если они запрашивают доступ на запись. Если этот флаг не указан, но файл или устройство было открыто для доступа на запись или имеет сопоставление файлов с доступом на запись, функция завершается ошибкой. |
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, представлены в таблице ниже атрибутов и таблиц флагов.
| Флаг | Значение |
|---|---|
| FILE_FLAG_BACKUP_SEMANTICS 0x02000000 | Файл открывается или создается для операции резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверку безопасности файлов при SE_BACKUP_NAME и привилегиях SE_RESTORE_NAME. Дополнительные сведения см. в разделе Изменение привилегий вмаркера. Этот флаг необходимо задать для получения дескриптора в каталог. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файлов. Дополнительные сведения см. в разделе "Примечания". |
| FILE_FLAG_DELETE_ON_CLOSE 0x04000000 | Файл должен быть удален сразу после закрытия всех его дескрипторов, который включает указанный дескриптор и любые другие открытые или повторяющиеся дескрипторы. Если в файле есть открытые дескрипторы, вызов завершается ошибкой, если они не были открыты с режимом общего доступа FILE_SHARE_DELETE. Последующие открытые запросы для файла завершаются ошибкой, если не указан режим общего доступа FILE_SHARE_DELETE. |
| FILE_FLAG_NO_BUFFERING 0x20000000 | Файл или устройство открывается без системного кэширования для операций чтения и записи данных. Этот флаг не влияет на кэширование жесткого диска или сопоставленные с памятью файлы. Существуют строгие требования для успешной работы с файлами, открытыми с помощью флага FILE_FLAG_NO_BUFFERING, дополнительные сведения см. в буферизации файлов. |
| FILE_FLAG_OPEN_NO_RECALL 0x00100000 | Запрашивается файл, но он должен продолжать находиться в удаленном хранилище. Его не следует передавать обратно в локальное хранилище. Этот флаг предназначен для использования в системах удаленного хранения. |
| FILE_FLAG_OPEN_REPARSE_POINT 0x00200000 | Обычное перепарировать точку не будет выполняться; эта функция попытается открыть точку повторного выполнения. При открытии файла возвращается дескриптор файла, независимо от того, работает ли фильтр, который управляет точкой повторного выполнения. Этот флаг нельзя использовать с флагом CREATE_ALWAYS. Если файл не является точкой перепарирования, этот флаг игнорируется. Дополнительные сведения см. в разделе "Примечания". |
| FILE_FLAG_OVERLAPPED 0x40000000 | Файл или устройство открываются или создаются для асинхронного ввода-вывода. После завершения последующих операций ввода-вывода для этого дескриптора событие, указанное в структуре OVERLAPPED, будет присвоено сигнальное состояние. Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED. Сведения об использовании дескриптора файлов, созданного с этим флагом, см. в разделе синхронных и асинхронных дескрипторов ввода-вывода этого раздела. |
| FILE_FLAG_POSIX_SEMANTICS 0x0100000 | Доступ будет выполняться в соответствии с правилами POSIX. Это включает в себя разрешение нескольких файлов с именами, отличающимися только в случае, для файловой системы, поддерживающей это именование. Используйте осторожность при использовании этого параметра, так как файлы, созданные с помощью этого флага, могут быть недоступны приложениями, написанными для MS-DOS или 16-разрядных Windows. |
| FILE_FLAG_RANDOM_ACCESS 0x10000000 | Доступ должен быть случайным. Система может использовать это в качестве указания для оптимизации кэширования файлов. Этот флаг не действует, если файловая система не поддерживает кэшированные операции ввода-вывода и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе "Поведение кэширования" этого раздела. |
| FILE_FLAG_SESSION_AWARE 0x00800000 | Файл или устройство открывается с помощью осведомленности о сеансе. Если этот флаг не указан, то для каждого сеанса (например, устройства с использованием перенаправления USB RemoteFX) невозможно открыть процессами, выполняемыми в сеансе 0. Этот флаг не действует для вызывающих абонентов в сеансе 0. Этот флаг поддерживается только в выпусках сервера Windows. |
| FILE_FLAG_SEQUENTIAL_SCAN 0x08000000 | Доступ должен быть последовательным с начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов. Этот флаг не следует использовать, если будет использоваться чтение (т. е. обратные проверки). Этот флаг не действует, если файловая система не поддерживает кэшированные операции ввода-вывода и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе "Поведение кэширования" этого раздела. |
| FILE_FLAG_WRITE_THROUGH 0x80000000 | Операции записи не будут проходить через промежуточный кэш, они будут переходить непосредственно на диск. Дополнительные сведения см. в разделе "Поведение кэширования" этого раздела. |
Параметр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 |