Функция OpenFile

Функция OpenFile создает, открывает, повторно открывает или удаляет файл.

Обратите внимание! на то, что эта функция предусматривается только для совместимости с 16-разрядными версиями Windows. Новые приложения должны использовать функцию CreateFile .

[in] Указатель на символьную строку с нулем в конце, которая именует открываемый файл. Строка должна состоять из букв или знаков символьного набора Windows. Функция OpenFile не поддерживает Unicode имена файлов. А также, OpenFile не поддерживает открытие именованных каналов.

[out] Указатель на структуру OFSTRUCT , которая получает информацию о файле, когда он впервые открывается. Структура может использоваться в последующих вызовах функции OpenFile, чтобы обратиться к открытому файлу.

Структура OFSTRUCT содержит член со строкой имени пути, длина которого ограничена количеством символов определяемых значением OFS_MAXPATHNAME . OFS_MAXPATHNAME в текущий момент определяется как 128. Вследствие этого, Вы не сможете использовать функцию OpenFile, чтобы открыть файл, длина пути которого будет больше 128 символов. Функция CreateFile не имеет такого ограничения длины пути.

[in] Предпринимаемое действие. Этот параметр может состоять из одного или нескольких нижеследующих значений.

Значение	Предназначение
OF_CANCEL	Игнорируется. Чтобы создать диалоговое окно, содержащее кнопку Cancel (Отменить), используйте флажок OF_PROMPT .
OF_CREATE	Создает новый файл. Если файл уже существует, он сокращается до нулевой длины.
OF_DELETE	Удаляет файл.
OF_EXIST	Открывает файл, а затем закрывает его. Используется, чтобы убедиться в существовании файла.
OF_PARSE	Заполняет поля структуры OFSTRUCT, но не делает никаких других действий.
OF_PROMPT	Показывает на экране диалоговое окно, если затребованный файл не существует. Диалоговое окно сообщает пользователю, что система не может найти файл, и оно содержит кнопки Retry (Повторить попытку) и Cancel (Отменить). Выбор кнопки Cancel предписывает функции OpenFile возвратить сообщение об ошибке «файл не найден».
OF_READ	Открывает файл только для чтения.
OF_READWRITE	Открывает файл для чтения и записи.
OF_REOPEN	Открывает файл, используя информацию в буфере повторного открытия.
OF_SHARE_COMPAT	Файловые системы, базирующиеся на MS DOS , открывают файл в режиме совместимости, давая возможность любому процессу на заданном компьютере открыть файл любое количество раз. Другие попытки открыть в каком-либо другом режиме совместного использования завершаются ошибкой (сбоем).

Windows NT/2000/XP: Этот флажок соответствует флажкам FILE_SHARE_READ | FILE_SHARE_WRITE функции CreateFile.

OF_SHARE_DENY_NONE Открывает файл без помех доступу к чтению или записи другими процессами. В файловых системах базирующихся на MS-DOS, если файл открылся в режиме совместимости любым другим процессом, функция завершается ошибкой.

Windows NT/2000/XP: Этот флажок соответствует флажкам FILE_SHARE_READ | FILE_SHARE_WRITE функции CreateFile.

OF_SHARE_DENY_READ Открывает файл и не дает доступ для чтения другим процессам. В файловых системах базирующихся на MS-DOS, если файл открылся в режиме совместимости или доступа для чтения любым другим процессом, функция завершается ошибкой.

Windows NT/2000/XP: Этот флажок соответствует флажку FILE_SHARE_READ | FILE_SHARE_WRITE функции CreateFile.

OF_SHARE_DENY_WRITE Открывает файл и не дает доступ для записи другим процессам. В файловых системах базирующихся на MS-DOS, если файл открылся в режиме совместимости или доступа для записи любым другим процессом, функция завершается ошибкой.

Windows NT/2000/XP: Этот флажок соответствует флажку FILE_SHARE_READ | FILE_SHARE_WRITE функции CreateFile.

OF_SHARE_EXCLUSIVE Открывает файл в режиме монопольного использования, отказывая в доступе и для чтения и для записи другим процессам. Если файл открылся в любом другом режиме для доступа к чтению или записи, даже текущим процессом, функция завершается ошибкой. OF_VERIFY Проверяет, что дата и время файла — те же самые, как и тогда, когда он был предварительно открыт. Это полезно как дополнительная проверка файлов только для чтения. OF_WRITE Открывает файл только для записи.

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

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

Если параметр lpFileName определяет только имя файла и расширение, эта функция производит поиск соответствующего файла в нижеследующих каталогах, в указанном порядке:

1. Каталог из которого загрузилось приложение.
2. Текущий каталог.
3. Каталог системы Windows. Используйте функцию GetSystemDirectory , чтобы получить путь к этому каталогу.

Windows NT/2000/XP: Имя этого каталога SYSTEM32.

Windows NT/2000/XP: 16-разрядный каталог системы Windows. Нет никакой функции, которая извлекает путь к этому каталогу, но он ищется. Название этого каталога — SYSTEM.

Каталог Windows. Используйте функцию GetWindowsDirectory , чтобы получить путь к этому каталогу.

Каталоги, которые внесены в список переменной окружающей среды PATH.

Параметр lpFileName не может содержать буквы или знаки символа подстановки.

Функция OpenFile не поддерживает флажок OF_SEARCH , поддерживаемый функцией OpenFile 16-разрядного Windows. Флажок OF_SEARCH предписывает системе искать соответствующий файл, даже тогда, когда имя файла включает полный путь к нему. Чтобы найти такой файл, используйте функцию SearchPath .

Windows 2000/XP: Нарушение совместного использования произойдет тогда, если делается попытка открыть файл или каталог для стирания на удаленной машине, когда значение параметра uStyle является флажком доступа OF_DELETE объединенным при помощи OR с каким-либо другим флажком доступа, а удаленный файл или каталог не открывались с флажком совместного доступа FILE_SHARE_DELETE . Чтобы избежать нарушения совместного использования в этом сценарии, откройте удаленный файл или каталог только с доступом OF_DELETE или вызовите функцию DeleteFile без первоначального открытия файла или каталога для удаления.

Windows Me/98/95: Это замечание не применяется.

Размещение и совместимость OpenFile

Работа с двоичными файлами с использованием функций WinApi

Создание нового файла

Для создания файла используется функция WinApi CreateFile().

FILE_ATTRIBUTE определены следующим образом:

С помощью этой функции можно открывать уже существующие файлы и консоли для консольных приложений, усекать их, открывать каталоги. Это все задается пятым параметром. Для создания файла этот параметр задается как CREATE_NEW. Вновь создаваемый файл открывается как для чтения, так и для записи, о чем свидетельствует второй параметр функции. Третий и четвертый параметры редко имеют какое-либо практическое применение в Windows 9x и требуются в основном при создании систем с разделением доступа на базе Windows NT. Шестой параметр определяет, какие атрибуты будут установлены для создаваемого файла. В данном случае будет присвоен атрибут Read-Only, позволяющий только чтение файла без записи в него. Windows самостоятельно закрывает все файлы и освобождает дескрипторы, как только завершается выполнение программы, но правило чистоты программирования требует не заставлять думать систему, когда сам знаешь как выполнить то или иное действие.

Открытие существующего файла

Функция WinApi OpenFile() открывает файл. Помимо этого, OpenFile() умеет создавать и удалять файлы. Во многом назначения этой функции пересекаются с CreateFile(), и существует в последних версиях WinApi для совместимости с ранними версиями Windows. Поэтому везде, где это возможно, лучше пользовать CreateFile().

Функция OpenFile() принимает всего три аргумента: имя открываемого файла, указатель на структуру OFSTRUCT и флаг режима открытия файла. Структура OFSTRUCT заполняется данными об открытом файле. Она предоставляет такую информацию, как свойства файла, его размер и т. д.

Третий параметр, флаг открытия файла, устанавливается в режим чтения, чтобы избежать случайного повреждения данных. Разумеется, можно установить и другие режимы:

Удаление файлов

Для удаления файлов используется функция WinApi DeleteFile().

DeleteFile() не удаляет защищенные от записи файлы (READONLY).

Копирование и перемещение файлов

Для копирования используется функция WinApi CopyFile, для перемещения MoveFile().

Определим имена файлов:

Аналогично CopyFile() действует функция API для переноса файла MoveFile().

Единственное отличие MoveFile() от CopyFile() — отсутствие третьего параметра, отвечающего за блокировку процесса переноса в случае, если файл уже существует.

Чтение информации из файла

Для чтения информации из файла используется функцию Win API ReadFile(), и ряд функций, обеспечивающих ее информацией:

В тексте объявляются две структуры. Первая, BY_HANDLE_FILE_INFORMATION, нужна для хранения полезной информации о файле. Вторая, OFSTRUCT требуется для работы функции API OpenFile(). Далее идет инициализация поля размера этой структуры.

Далее — создание буфера, в который будут скопированы данные, считанные из файла. Можно проделать расчет, основанный на размере файла, но можно поступить проще: задать размер принудительно, например 64 Кбайт. Для создания такого буфера можно использовать задание типа new char[0xfffe], выделяющей блок памяти подходящего размера. В конце обработчика необходимо освободить блок памяти операцией delete[].

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

Полученный дескриптор функцией OpenFile() открытого файла необходимо передать в качестве параметра для другой функции API — GetFileInformationByHandle(), которая заполняет структуру bhFileInformation типа BY_HANDLE_FILE_INFORMATION, переданную в качестве второго параметра, данными об открытом файле. В этой структуре имеются два поля, хранящие старшие и младшие четыре байта размера файла. Для малого файла хватает и младших четырех байтов.

Первые два параметра — это дескриптор читаемого файла и адрес буфера, в который будут считаны данные. Четвертый параметр функции — счетчик байтов, в который ReadFile() записывает количество байтов, считанных из файла.

Пятый параметр игнорируется.

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

При работе в переменной появятся данные из файла.

Запись информации в файл

Функция WinApi WriteFile() записывает данные в файл. Она полностью аналогична по используемым параметрам функции ReadFile().

Пример универсальной функции работы с файлами

Следующая функция читает информацию типа int или char из файла, имя которого и директория передается в функцию, или записывает информацию в файл в соответствии с передаваемыми в функцию параметрами. Функция не предполагает чтение всего файла, и написана для случаев когда известно сколько байт предполагается прчитать или записать.

OpenFile function (winbase.h)

Creates, opens, reopens, or deletes a file.

Syntax

Parameters

The name of the file.

The string must consist of characters from the 8-bit Windows character set. The OpenFile function does not support Unicode file names or opening named pipes.

A pointer to the OFSTRUCT structure that receives information about a file when it is first opened.

The structure can be used in subsequent calls to the OpenFile function to see an open file.

The OFSTRUCT structure contains a path string member with a length that is limited to OFS_MAXPATHNAME characters, which is 128 characters. Because of this, you cannot use the OpenFile function to open a file with a path length that exceeds 128 characters. The CreateFile function does not have this path length limitation.

The action to be taken.

This parameter can be one or more of the following values.

Value	Meaning
OF_CANCEL 0x00000800	Ignored. To produce a dialog box containing a Cancel button, use OF_PROMPT.
OF_CREATE 0x00001000	Creates a new file. If the file exists, it is truncated to zero (0) length.
OF_DELETE 0x00000200	Deletes a file.
OF_EXIST 0x00004000	Opens a file and then closes it. Use this to test for the existence of a file.
OF_PARSE 0x00000100	Fills the OFSTRUCT structure, but does not do anything else.
OF_PROMPT 0x00002000	Displays a dialog box if a requested file does not exist. A dialog box informs a user that the system cannot find a file, and it contains Retry and Cancel buttons. The Cancel button directs OpenFile to return a file-not-found error message.
OF_READ 0x00000000	Opens a file for reading only.
OF_READWRITE 0x00000002	Opens a file with read/write permissions.
OF_REOPEN 0x00008000	Opens a file by using information in the reopen buffer.
OF_SHARE_COMPAT 0x00000000	For MS-DOS–based file systems, opens a file with compatibility mode, allows any process on a specified computer to open the file any number of times. Other efforts to open a file with other sharing modes fail. This flag is mapped to the FILE_SHARE_READ|FILE_SHARE_WRITE flags of the CreateFile function.
OF_SHARE_DENY_NONE 0x00000040	Opens a file without denying read or write access to other processes. On MS-DOS-based file systems, if the file has been opened in compatibility mode by any other process, the function fails. This flag is mapped to the FILE_SHARE_READ|FILE_SHARE_WRITE flags of the CreateFile function.
OF_SHARE_DENY_READ 0x00000030	Opens a file and denies read access to other processes. On MS-DOS-based file systems, if the file has been opened in compatibility mode, or for read access by any other process, the function fails. This flag is mapped to the FILE_SHARE_WRITE flag of the CreateFile function.
OF_SHARE_DENY_WRITE 0x00000020	Opens a file and denies write access to other processes. On MS-DOS-based file systems, if a file has been opened in compatibility mode, or for write access by any other process, the function fails. This flag is mapped to the FILE_SHARE_READ flag of the CreateFile function.
OF_SHARE_EXCLUSIVE 0x00000010	Opens a file with exclusive mode, and denies both read/write access to other processes. If a file has been opened in any other mode for read/write access, even by the current process, the function fails.
OF_VERIFY	Verifies that the date and time of a file are the same as when it was opened previously. This is useful as an extra check for read-only files.
OF_WRITE 0x00000001	Opens a file for write access only.

Return value

If the function succeeds, the return value specifies a file handle to use when performing file I/O. To close the file, call the CloseHandle function using this handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

If the lpFileName parameter specifies a file name and extension only, this function searches for a matching file in the following directories and the order shown:

1. The directory where an application is loaded.
2. The current directory.
3. The Windows system directory.

Use the GetSystemDirectory function to get the path of this directory.

The 16-bit Windows system directory.

There is not a function that retrieves the path of this directory, but it is searched.

The Windows directory.

Use the GetWindowsDirectory function to get the path of this directory.

The directories that are listed in the PATH environment variable.

The lpFileName parameter cannot contain wildcard characters.

The OpenFile function does not support the OF_SEARCH flag that the 16-bit Windows OpenFile function supports. The OF_SEARCH flag directs the system to search for a matching file even when a file name includes a full path. Use the SearchPath function to search for a file.

A sharing violation occurs if an attempt is made to open a file or directory for deletion on a remote machine when the value of the uStyle parameter is the OF_DELETE access flag OR’ed with any other access flag, and the remote file or directory has not been opened with FILE_SHARE_DELETE share access. To avoid the sharing violation in this scenario, open the remote file or directory with OF_DELETE access only, or call DeleteFile without first opening the file or directory for deletion.

In WindowsВ 8 and Windows ServerВ 2012, this function is supported by the following technologies.

Technology	Supported
Server Message Block (SMB) 3.0 protocol	Yes
SMB 3.0 Transparent Failover (TFO)	Yes
SMB 3.0 with Scale-out File Shares (SO)	Yes
Cluster Shared Volume File System (CsvFS)	Yes
Resilient File System (ReFS)	Yes

В

CsvFs will do redirected IO for compressed files.