В лекции рассматривается использование функций библиотеки (C++): CreateFile(), CopyFile(), MoveFile(), DeleteFile(), ReadFile(), WriteFile(), UnlockFile(), LockFile() и CloseHandle().
Материалы по данной теме имеются так же в лекции про файлы .
Содержание лекции:
Создание файлов
Для создания нового или открытия существующего файла используется функция CreateFile. При использовании функции CreateFile необходимо указать, предполагается чтение или запись в файл или и то и другое. Также необходимо указать, необходимые действия в случае наличия файла на диске или его отсутствия (например, перезаписывать файл, если он существует и создавать новый, если – нет). Также функция CreateFile позволяет указать возможность разделения файла с другими приложениями (одновременного чтения/записи нескольких приложений в файл). Если некоторое приложение монополизировало доступ к файлу на чтение и/или запись, то никакое другое приложение не сможет читать и/или писать в файл, пока первое его не закроет.
Операционная система присваивает каждому открытому файлу уникальный идентификатор (дескриптор, file handle), который может быть использован при обращениях к файлу для записи, чтения и получения информации о файле. Дескриптор действителен до тех пор, пока файл не закрыт. Приложение может наследовать дескрипторы файлов от процесса, который его запустил (если дескрипторы наследуемые).
Функция CreateFile среди прочих объектов позволяет обращаться к файлам и каналам (pipes). При обращении к каналам функция CreateFile позволяет создавать клиентское подключение к именованным каналам, находящимся в режиме ожидания подключения. Серверная часть канала создаётся функцией CreateNamedPipe. Одно приложение может создавать множество клиентских подключений к каналу, но к одному экземпляру канала может подключаться только одно приложение (Стоит отметить, что возможно существование нескольких экземпляров именованных каналов с одинаковыми именами).
Функция CreateFile
имеет следующий прототип:
HANDLE CreateFile(
LPCTSTR lpFileName, // file name
DWORD dwDesiredAccess, // access mode
DWORD dwShareMode, // share mode
LPSECURITY_ATTRIBUTES lpSecurityAttributes, // SD
DWORD dwCreationDisposition, // how to create
DWORD dwFlagsAndAttributes, // file attributes
HANDLE hTemplateFile // handle to template file
);
Параметры:
lpFileName:
Указатель на строку, содержащую имя объекта для создания или открытия (имя файла, путь к файлу, имя канала и пр.). Если имя задается литеральной константой, то следует поместить её в макрос TEXT() или поставить L перед открывающей кавычкой. Например, TEXT("C:\\tmp.txt") или L"C:\\tmp.txt"
dwDesiredAccess:
Описание желаемого режима доступа к файлу. Существует возможность передачи большого количества различных флагов. Нас интересуют флаги GENERIC_READ, GENERIC_WRITE и их объединение. При доступе к каналам следует учитывать режим создания канала сервером. Если сервер создал канал для записи, то клиент открывает его для чтения и наоборот. Если сервер создал канал для чтения и записи, то клиент может открыть его как для чтения, так и для записи.
dwShareMode:
Определяет режим разделения объекта
0 – приложение открывает файл для монопольного доступа. Последующие обращения на открытие данного файла будут безуспешными, пока данных дескриптор не будет закрыт. Для разделения доступа к файлу могут использоваться следующие ключи (один или вместе):
FILE_SHARE_READ
– разрешены лишь последующие операции открытия только на чтение.
FILE_SHARE_WRITE
– разрешены лишь последующие операции открытия только на запись.
lpSecurityAttributes
Указатель на сруктуру SECURITY_ATTRIBUTES
, которая определяет возможность наследования дескриптора дочерними процессами. Можно передавать NULL – это значит, что дескриптор не может быть наследован (для наших приложений этого достаточно).
dwCreationDisposition:
Определяет то, какие действия необходимо предпринять в случаях, если файл существует и если файл не существует. Этот параметр должен иметь одно из следующих заначений:
Значение Пояснение
CREATE_NEW
Создаёт файл. Вызов заканчивается неудачей, если файл существует.
CREATE_ALWAYS
Создаёт новый файл. Если файл существует, то его содержимое и атрибуты будут стёрты.
OPEN_EXISTING
Открытие файла. Если файл не существует, то вызов закончится неудачей.
OPEN_ALWAYS
Открывает файл. Если файл не существует, то он будет создан.
TRUNCATE_EXISTING
Открывает файл, размер которого обнуляется. Файл должен открываться как минимум с режимом доступа GENERIC_WRITE. Если файл не существует, то вызов будет неудачен.
dwFlagsAndAttributes:
Позволяет задавать файловые атрибуты (только для чтения, скрытый, системный и пр.). Также позволяет сообщать операционной системе желаемое поведение при работе с файлами. Например, запись в файл без буферизации (FILE_FLAG_NO_BUFFERING
и FILE_FLAG_WRITE_THROUGH
); оптимизация для неупорядоченного доступа (FILE_FLAG_RANDOM_ACCESS
); открытие для асинхронного ввода/вывода (FILE_FLAG_OVERLAPPED
).
В
озвращаемое значение:
Если вызов успешен, возвращается дескриптор открытого файла. Если вызов неудачен, возвращается константа INVALID_HANDLE_VALUE
. Код ошибки можно получить вызовом функции GetLastError. Подробную информацию об ошибке (по её коду) можно получить вызовом функции FormatMessage.
Для копирования файлов используется функция CopyFile
:
BOOL CopyFile(
LPCTSTR lpExistingFileName, // имя существующего файла
LPCTSTR lpNewFileName, // имя нового файла
BOOL bFailIfExists // действие, если файл существует TRUE – ошибка
// FALSE - перезаписывать
);
Для переименования файлов и директорий используется функция MoveFile
:
BOOL MoveFile(
LPCTSTR lpExistingFileName, // имя файла
LPCTSTR lpNewFileName // новое имя файла
);
В случае успеха возвращается ненулевое значение.
Для удаления существующих файлов используется функция DeleteFile
:
BOOL DeleteFile(
LPCTSTR lpFileName // имя удаляемого файла
);
В случае успеха возвращается ненулевое значение.
Чтение/запись в файл:
Каждый открытый файл имеет файловый указатель (file pointer), который указывает позицию следующего файла, который будет записан/прочтен. При открытии файла его файловый указатель перемещается на начало файла. После прочтения/записи очередного файла система перемещает файловый указатель. Файловый указатель можно перемещать, используя функцию SetFilePointer
.
Для чтения/записи в файл используются функции ReadFile и WriteFile, при этом необходимо, чтобы файл был открыт на чтение и на запись соответственно.
Функция ReadFile
читает из файла указанное количество символов, начиная с позиции, обозначенной файловым указателем. При синхронном (в противоположность асинхронному) чтении файловый указатель сдвигается на фактически прочитанное количество байт.
BOOL ReadFile(
LPVOID lpBuffer, // буфер данных
DWORD nNumberOfBytesToRead, // количество байт для прочтения
LPDWORD lpNumberOfBytesRead, // количество фактически прочитанных байт
// асинхронном чтении
);
Параметры:
hFile:
Дескриптор читаемого файла. Должен быть открыт с доступом GENERIC_READ.
lpBuffer:
Указатель на буфер, принимающий данные из файла.
nNumberOfBytesToRead:
Задаёт количество байт, которые необходимо прочитать из файла.
lpNumberOfBytesRead:
Указатель на переменную, которая принимает количество реально прочитанных байт.
lpOverlapped:
Возвращаемое значение
:
Если возвращено ненулевое значение, но прочитано 0 байт, значит файловый указатель стоял на конце файла перед операцией чтения.
Функция WriteFile
записывает в файл данные, начиная с позиции, обозначенной файловым указателем. При синхронной (в противоположность асинхронному) записи файловый указатель сдвигается на фактически записанное количество байт.
BOOL WriteFile(
HANDLE hFile, // дескриптор файла
LPCVOID lpBuffer, // буфер данных
DWORD nNumberOfBytesToWrite, // количество байт для записи
LPDWORD lpNumberOfBytesWritten,// количество фактически записанных байт
LPOVERLAPPED lpOverlapped // указатель на структуру, используемую при
// асинхронном чтении
);
Параметры:
hFile:
Дескриптор файла, в который производится запись. Должен быть открыт с доступом GENERIC_WRITE.
lpBuffer:
Указатель на буфер, содержащий данные, которые необходимо записать.
nNumberOfBytesToWrite:
Задаёт количество байт, которые необходимо записать в файл.
lpNumberOfBytesWritten:
Указатель на переменную, которая принимает количество реально записанных байт.
lpOverlapped:
Укзатель на структуру OVERLAPPED. При не асинхронном доступе следует передавать NULL.
Возвращаемое значение:
Если выполнение функции произошло успешно, то возвращается ненулевое значение.
Блокировка файлов:
Т.к. система позволяет более чем одному приложению открывать файл и писать в него, приложения не должны одновременно писать в одну область файла. Эта проблема может быть решена путем временного блокирования части файла. Функция LockFile позволяет приложению получить в монопольное пользования определённое количество байт в файле. Отрезок заблокированных байт может выходить за текущий конец файла. Все попытки сторонних приложений обратиться к заблокированному участку файла потерпят неудачу.
Приложение может файл с помощью функции UnlockFile
.
BOOL LockFile(
HANDLE hFile, // дескриптор файла
DWORD nNumberOfBytesToLockLow, // младшее слово длины отрезка
DWORD nNumberOfBytesToLockHigh // старшее слово длины отрезка
);
Параметры:
hFile:
Дескриптор файла, в который производится запись. Должен быть открыт с доступом GENERIC_READ или GENERIC_WRITE (или обоими).
dwFileOffsetLow:
Определяет младшее слово смещения начала блокируемого отрезка относительно начала файла.
dwFileOffsetHigh:
Определяет старшее слово смещения начала блокируемого отрезка относительно начала файла. Не равно нулю, если смещение относительно начала более чем 232 байт.
n
NumberOfBytesToLockLow:
Определяет младшее слово длины блокируемого отрезка.
nNumberOfBytesToLockHigh:
Определяет старшее слово длины блокируемого отрезка. Не равно нулю, если длина отрезка более 232 байт или 4 ГБ.
Возвращаемое значение:
Если выполнение функции произошло успешно, то возвращается ненулевое значение.
Блокирование предоставляет процессу монопольный доступ к отрезку файла. Файловые блокировки не наследуются. Остальные процессы не могут ни читать, ни писать в заблокированную часть файла.
Функция UnlockFile
позволяет разблокировать участок файла, ранее заблокированный функцией LockFile
.
BOOL UnlockFile(
HANDLE hFile, // дескриптор файла
DWORD dwFileOffsetLow, // младшее слово смещения начала отрезка
DWORD dwFileOffsetHigh, // старшее слово смещения начала отрезка
DWORD nNumberOfBytesToUnlockLow, // младшее слово длины отрезка
DWORD nNumberOfBytesToUnlockHigh // старшее слово длины отрезка
);
Параметры данной функции аналогичны параметрам функции LockFile
.
Возвращаемое значение:
Если выполнение функции произошло успешно, то возвращается ненулевое значение.
Отрезок файла, который разблокируется функцией UnlockFile должен в точности соответствовать отрезку, заблокированному функцией LockFile. Например, две соседних части файла не могут быть заблокированы по отдельности, а разблокированы как единое целое. Процесс не должен завершать выполнение, имея заблокированные части файлов. Файловый дескриптор, для которого есть заблокированные отрезки, не должен закрываться.
Для оптимального использования ресурсов операционной системы приложение должно закрывать ненужные файлы с помощью функции CloseHandle
. Файлы, открытые на момент завершения приложения, закрываются автоматически.
BOOL CloseHandle(
HANDLE hObject // Дескриптор объекта (файла, канала и пр.)
);
Возвращаемое значение:
Если выполнение функции произошло успешно, то возвращается ненулевое значение.
Для создания нового или открытия существующего файла используется функция CreateFile. При использовании функцииCreateFile необходимо указать, предполагается чтение или запись в файл или и то и другое. Также необходимо указать, необходимые действия в случае наличия файла на диске или его отсутствия (например, перезаписывать файл, если он существует и создавать новый, если – нет). Также функцияCreateFile позволяет указать возможность разделения файла с другими приложениями (одновременного чтения/записи нескольких приложений в файл). Если некоторое приложение монополизировало доступ к файлу на чтение и/или запись, то никакое другое приложение не сможет читать и/или писать в файл, пока первое его не закроет.
Операционная система присваивает каждому открытому файлу уникальный идентификатор (дескриптор, filehandle), который может быть использован при обращениях к файлу для записи, чтения и получения информации о файле. Дескриптор действителен до тех пор, пока файл не закрыт. Приложение может наследовать дескрипторы файлов от процесса, который его запустил (если дескрипторы наследуемые).
Функция CreateFileсреди прочих объектов позволяет обращаться к файлам и каналам (pipes). При обращении к каналам функцияCreateFileпозволяет создавать клиентское подключение к именованным каналам, находящимся в режиме ожидания подключения. Серверная часть канала создаётся функцией CreateNamedPipe. Одно приложение может создавать множество клиентских подключений к каналу, но к одному экземпляру канала может подключаться только одно приложение (Стоит отметить, что возможно существование нескольких экземпляров именованных каналов с одинаковыми именами).
Функция CreateFileимеет следующий прототип:
HANDLE CreateFile(
LPCTSTR lpFileName , // file name
DWORD dwDesiredAccess , // access mode
DWORD dwShareMode , // share mode
LPSECURITY_ATTRIBUTES lpSecurityAttributes , // SD
DWORD dwCreationDisposition , // how to create
DWORD dwFlagsAndAttributes , // file attributes
HANDLE hTemplateFile // handle to template file
Параметры
lpFileName
Указатель на строку, содержащую имя объекта для создания или открытия (имя файла, путь к файлу, имя канала и пр.). Если имя задается литеральной константой, то следует поместить её в макросTEXT() или поставитьLперед открывающей кавычкой. Например, TEXT("C:\\tmp.txt") или L"C:\\tmp.txt"
dwDesiredAccess
Описание желаемого режима доступа к файлу. Существует возможность передачи большого количества различных флагов. Нас интересуют флаги GENERIC_READ, GENERIC_WRITE и их объединение. При доступе к каналам следует учитывать режим создания канала сервером. Если сервер создал канал для записи, то клиент открывает его для чтения и наоборот. Если сервер создал канал для чтения и записи, то клиент может открыть его как для чтения, так и для записи.
dwShareMode
Определяет режим разделения объекта
0 – приложение открывает файл для монопольного доступа. Последующие обращения на открытие данного файла будут безуспешными, пока данных дескриптор не будет закрыт. Для разделения доступа к файлу могут использоваться следующие ключи (один или вместе):
FILE_SHARE_READ – разрешены лишь последующие операции открытия только на чтение.
FILE_SHARE_WRITE – разрешены лишь последующие операции открытия только на запись.
lpSecurityAttributes
Указатель на сруктуру SECURITY_ATTRIBUTES, которая определяет возможность наследования дескриптора дочерними процессами. Можно передаватьNULL– это значит, что дескриптор не может быть наследован (для наших приложений этого достаточно).
dwCreationDisposition
Определяет то, какие действия необходимо предпринять в случаях, если файл существует и если файл не существует. Этот параметр должен иметь одно из следующих заначений:
|
Значение |
Пояснение |
|
Создаёт файл. Вызов заканчивается неудачей, если файл существует. |
|
|
Создаёт новый файл. Если файл существует, то его содержимое и атрибуты будут стёрты. |
|
|
Открытие файла. Если файл не существует, то вызов закончится неудачей. |
|
|
Открывает файл. Если файл не существует, то он будет создан. |
|
|
TRUNCATE_EXISTING |
Открывает файл, размер которого обнуляется. Файл должен открываться как минимум с режимом доступа GENERIC_WRITE. Если файл не существует, то вызов будет неудачен. |
dwFlagsAndAttributes
Позволяет задавать файловые атрибуты (только для чтения, скрытый, системный и пр.). Также позволяет сообщать операционной системе желаемое поведение при работе с файлами. Например, запись в файл без буферизации (FILE_FLAG_NO_BUFFERING и FILE_FLAG_WRITE_THROUGH); оптимизация для неупорядоченного доступа (FILE_FLAG_RANDOM_ACCESS); открытие для асинхронного ввода/вывода (FILE_FLAG_OVERLAPPED).
WinAPI. Функции работы с файлами. Часть 4 :
Заканчиваем изучать WinAPI работы с фалами и дисками. Это последняя статья, потому что в следующий раз мы перейдём к рассмотрению другой группы WinAPI функций. Я постарался дать тебе максимум инфе о основных API для работы с файлами. Надеюсь, что я работал не зря.
Сегодня ты узнаешь про:
ReadFile
Функция читает из файла блок данных начиная с текущей позиции. После прочтения блока, позиция переносится в конец прочитанного блока.
Объявление:
Для С/С++ BOOL ReadFile(HANDLE hFile, // Указатель на открытый файл LPVOID lpBuffer, // Указатель на буфер, куда поместится прочитанный блок DWORD nNumberOfBytesToRead, // количество прочитанных байтов LPDWORD lpNumberOfBytesRead,// указатель на число прочитанных данных LPOVERLAPPED lpOverlapped // указатель на структуру OVERLAPPED); Для Delphi function ReadFile(hFile: THandle; // Указатель на открытый файл var Buffer; // Указатель на буфер, куда поместится прочитанный блок nNumberOfBytesToRead: DWORD; // количество прочитанных байтов var lpNumberOfBytesRead: DWORD; // указатель на число прочитанных данных lpOverlapped: POverlapped // указатель на структуру OVERLAPPED): BOOL; stdcall;RemoveDirectory
Функция удаляет директорию. Если внутри есть хотя бы один файл или другая директория, то произойдёт ошибка. Удаление возможно только пустой директории.
Существует в: Win NT, Win9x, Win32s.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ BOOL RemoveDirectory(LPCTSTR lpPathName // Указатель на путь директории); Для Delphi function RemoveDirectory(lpPathName: PChar// Указатель на путь директории): BOOL; stdcall;Если всё ничтяк, то функция вернёт TRUE.
Пример использования: RemoveDirectory("с:\Windows");
SetCurrentDirectory
Функция изменяет текущую директорию на указанную. Это значит, что когда ты будешь использовать другие функции работы с файлами, и не указывать путь, то ОС будет искать файл в этой директории.
Существует в: Win NT, Win9x, Win32s.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ BOOL SetCurrentDirectory(LPCTSTR lpPathName // Указатель на строку, содержащую путь); Для Delphi function SetCurrentDirectory(lpPathName: PChar // Указатель на строку, содержащую путь): BOOL; stdcall;Если всё ничтяк, то функция вернёт TRUE.
SetEndOfFile
Функция делает текущую позицию файла концом файла. Если тебе нужно сократить размер файла, то вызови эту функцию, установи курсор в необходимую позицию и вызови эту функцию.
Существует в: Win NT, Win9x, Win32s.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ BOOL SetEndOfFile(HANDLE hFile // Указатель на открытый файл); Для Delphi function SetEndOfFile(hFile: THandle // Указатель на открытый файл): BOOL; stdcall;Если всё ничтяк, то функция вернёт TRUE.
SetFileAttributes
Функция позволяет устанавливать на файл атрибуты.
Существует в: Win NT, Win9x, Win32s.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ BOOL SetFileAttributes(LPCTSTR lpFileName, // Путь к файлу DWORD dwFileAttributes // Будущие атрибуты файла); Для Delphi function SetFileAttributes(lpFileName: PChar; // Путь к файлу dwFileAttributes: DWORD // Будущие атрибуты файла): BOOL; stdcall;С первым параметром всё ясно. Это просто путь к файлу. А вот второй параметр это атрибуты. Они могут быть в виде сочетания следующих флагов:
- FILE_ATTRIBUTE_ARCHIVE - атрибут архивного файла.
- FILE_ATTRIBUTE_HIDDEN - атрибут спрятанного файла.
- FILE_ATTRIBUTE_NORMAL - атрибут нормального файла.
- FILE_ATTRIBUTE_OFFLINE - указывает на то, что данные файла не доступны и находятся на отключённом устройстве
- FILE_ATTRIBUTE_READONLY - атрибут файла только для чтения.
- FILE_ATTRIBUTE_SYSTEM - атрибут системного файла.
- FILE_ATTRIBUTE_TEMPORARY - атрибут временного файла.
Если всё ничтяк, то функция вернёт TRUE.
SetFilePointer
Функция устанавливает позицию в файле. Например, если ты хочешь прочитать данные из файла начиная с какой-то позиции, то ты должен воспользоваться этой функцией, чтобы выставить позицию, а потом прочитать данные начиная с этой позиции.
Существует в: Win NT, Win9x, Win32s.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ DWORD SetFilePointer(HANDLE hFile, // Указатель на открытый файл LONG lDistanceToMove, // количество байт, на которые надо передвинуться PLONG lpDistanceToMoveHigh, // Второй байт, указывающий количество байт DWORD dwMoveMethod //Откуда нужно начинать двигаться); Для Delphi function SetFilePointer(hFile: THandle; // Указатель на открытый файл lDistanceToMove: Longint; // количество байт, на которые надо передвинуться lpDistanceToMoveHigh: Pointer; // Второй байт, указывающий количество байт dwMoveMethod: DWORD //Откуда нужно начинать двигаться): DWORD; stdcall;Первый параметр - указатель на открытый файл. Второй и третий параметры определяют количество байт, на которые надо передвинуться. Последний параметр - это флаг определяющий откуда надо начинать двигаться:
- FILE_BEGIN - Передвинуться от начала файла вперёд.
- FILE_CURRENT - Передвинуться начиная от текущей позиции вперёд.
- FILE_END - Передвинуться от конца файла к началу.
Если всё ничтяк, то функция вернёт младший байт установленной позиции.
Если ты хочешь узнать текущую позицию файла, то можешь смухлевать, вызвав функцию с такими параметрами: SetFilePointer(h,0,0, FILE_CURRENT). Этим ты заставляешь передвинутся на 0 байтов от текущей позиции. Передвижения не произойдёт, но функция вернёт новую позицию файла, то есть текущую.
SetVolumeLabel
Функция устанавливает метку тома
Существует в: Win NT, Win9x.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ BOOL SetVolumeLabel(LPCTSTR lpRootPathName, // Указатель на имя тома LPCTSTR lpVolumeName // Метка тома); Для Delphi function SetVolumeLabel(lpRootPathName: PChar; // Указатель на имя тома lpVolumeName: PAnsiChar// Метка тома): BOOL; stdcall;Если всё ничтяк, то функция вернёт TRUE.
WriteFile
Функция производит запись блока данных начиная с текущей позиции в файле.
Существует в: Win NT, Win9x, Win32s.
Для С/С++ объявлена в winbase.h. Для Delphi в модуле windows.
Объявление:
Для С/С++ BOOL WriteFile(HANDLE hFile, // Указатель на открытый файл LPCVOID lpBuffer, // Указатель на данные для записи DWORD nNumberOfBytesToWrite, // Количество записанных байт LPDWORD lpNumberOfBytesWritten,// Указатель на количество записанных байт LPOVERLAPPED lpOverlapped // Указатель на структуру OVERLAPPED); Для Delphi function WriteFile(hFile: THandle; // Указатель на открытый файл const Buffer; // Указатель на данные для записи nNumberOfBytesToWrite: DWORD; // Количество записанных байт var lpNumberOfBytesWritten: DWORD; // Указатель на количество записанных байт lpOverlapped: POverlapped // Указатель на структуру OVERLAPPED): BOOL; stdcall;Если всё ничтяк, то функция вернёт TRUE.
На этом я заканчиваю рассмотрения функций для работы с файлами.
Описание:
function
CreateFile(lpFileName: PChar; dwDesiredAccess, dwShareMode: DWORD;
lpSecurityAttributes: PSecurityAttributes; dwCreationDisposition, dwFlagsAndAttributes: DWORD;
hTemplateFile: THandle): THandle;
Создает или открывает следующие объекты и возвращает Хендл (handle), для получения доступа к объекту:
· файлам
· каналам (pipes)
· mailslots
· коммуникационные ресурсы (communications resources)
· Дисковым устройствам (только для Windows NT)
· консолям (consoles)
· папкам (только открытие)
Параметры
lpFileName: Строка которая определяет название объекта для создания или открытия. Если lpFileName - путь, то максимум символов в строке определено константой MAX_PATH.
Windows NT: Можно использовать пути более MAX_PATH знаков, вызывая расширенную (W) версию CreateFile и подставив " \? \ " в Путь. " \? \ " говорит функции выключать парсинг пути. Это позволяет вам использовать пути, которые имеют почти 32 000 Unicode знаков. Функция также работает с именами internet-протокола. " \? \ " игнорируется как часть пути. Например, " \? \C:\myworld\private" будет трансформирован в "C:\myworld\private", а " \? \UNC\tom_1\hotstuff\coolapps" будет трансформирован в " \ tom_1\hotstuff\coolapps".
dwDesiredAccess: Определяет тип доступа к объекту. Приложение может получить доступ по чтению, записи, записи-чтению. Этим параметром может быть любая комбинация следующих флагов:
-0 - Специальный флаг доступа к обьекту. Определяет аттрибуты файла не подсоединяясь к нему, не подсоединяясь к нему.
-GENERIC_READ- определяет доступ по чтению к устройству. Данные могут читаться из файла, а указатель файла может быть перемещен. Объединяется с флагом GENERIC_WRITE для доступа по чтению-записи.
GENERIC_WRITE - определяет, доступ по записи к устройству. Данные могут быть записываться в файл, и указатель файла может быть перемещен. Объединяется с флагом GENERIC_WRITE для доступа по чтению-записи.
dwShareMode: Набор флагов который определяет, как объект может быть разделен(shared). Если dwShareMode - 0, объект не может быть разделен. Последующие операции открытия объекта будут отклонены, пока указатель не будет закрыт.
Чтобы разделить объект, используйте комбинацию следующих флагов:
FILE_SHARE_DELETE - только для Windows NT: Доступ закрыт для всех кроме открывшего, после закрытия указателя файл будет удален.
- FILE_SHARE_READ - Доступ для чтения.
-FILE_SHARE_WRITE - Доступ для записи.
lpSecurityAttributes: Указатель на структуру TSecurityAttributes, которая определяет, может ли возвращенный указатель быть использован процессами-потомками. Если lpSecurityAttributes является пустым, указатель не может быть унаследован.
Windows NT: поле структуры lpSecurityDescriptor определяет описатель безопасности для объекта. Если lpSecurityAttributes является пустым, объект получает описатель по умолчанию. Файловая система должна поддерживать ружим безопасности.
Windows 95: поле lpSecurityDescriptor игнорируется.
dwCreationDistribution: Определяет действие которое надо совершить в случае когда файлы существуют, и какое когда файлы не существуют. Дополнительную информацию см. в Примечаниях. Этим параметром должна быть один из следующих флагов:
-CREATE_NEW создает новый файл. Функция терпит неудачу, если указанный файл уже существует.
-CREATE_ALWAYS создает новый файл. Функция переписывает файл, если он существует.
-OPEN_EXISTING открывает файл. Функция терпит неудачу, если файл не существует.
OPEN_ALWAYS открывает файл, если он существует. Если файл не существует, функция создает файл.
-TRUNCATE_EXISTING открывает файл. После того файл открывается его размер обнуляется. Процесс запроса должен открыть файл с по крайней мере с GENERIC_WRITE доступом. Функция терпит неудачу, если файл не существует.
DwFlagsAndAttributes: Определяет признаки файла и флаги для файла.
Любая комбинация следующих признаков приемлема. Все признаки файла перекрывают FILE_ATTRIBUTE_NORMAL. См. FILE_ATTRIBUTE_.
Любая комбинация следующих флагов приемлема для использования.
- FILE_FLAG_WRITE_THROUGH - говорит системе чтобы при записи в кэш сразу шла запись на диск.
- FILE_FLAG_OVERLAPPED - говорит системе возвращать указатель даже если действие еще не завершено. Без этого флага функции ReadFile, WriteFile, ConnectNamedPipe, и TransactNamedPipe, которые занимают существенное время, возвращают ERROR_IO_PENDING. Когда действие закончено, вызывается событие указывающее об этом.Когда Вы определяете FILE_FLAG_OVERLAPPED, ReadFile, и функции WriteFile должны определить структуру TOverlapped.Когда FILE_FLAG_OVERLAPPED определен, операционная система не не обслуживает указатель файла. Позицию указателя файла нужно передать как часть параметра lpOverlapped (указывающий на структуру TOverlapped) к функциям WriteFile и ReadFile.
Этот флаг также позволяет выполняться более чем одному действию с указателем файла (например одновременный читать и писать).
- FILE_FLAG_NO_BUFFERING - Инструктирует операционную систему открывать файл без промежуточного буфера или кэширования.
- FILE_FLAG_RANDOM_ACCESS - Указывает, что к файлу обращаются беспорядочно. Windows может использовать это как намек, чтобы оптимизировать кэширование файла.
- FILE_FLAG_SEQUENTIAL_SCAN - Указывает, что к файлу нужно обратиться последовательно с начала до конца. Windows может использовать это как намек, чтобы оптимизировать кэширование файла.
FILE_FLAG_DELETE_ON_CLOSE - Указывает, что операционная система должна удалить файл немедленно после того, как все его указатели будут закрыты.
- FILE_FLAG_BACKUP_SEMANTICS - только для Windows NT: Указывает, что файл открывается или создается для резервирования или восстанавления. Операционная система гарантирует, что процесс запроса отвергает проверку безопасности файла. Уместные разрешения - SE_BACKUP_NAME, и SE_RESTORE_NAME.
FILE_FLAG_POSIX_SEMANTICS - Указывает, что к файлу нужно обратиться согласно правилам POSIX.
Если функция CreateFile открывает клиент канала, параметр dwFlagsAndAttributes может также содержать Security Quality of Service information. Когда приложение запрашивает флаг SECURITY_SQOS_PRESENT, параметр dwFlagsAndAttributes может содержать один или больше следующих флагов:
- SECURITY_ANONYMOUS - определяет Анонимнго клиента(Anonymous).
- SECURITY_IDENTIFICATION - определяет Идентифицируемого клиента(Identification).
- SECURITY_IMPERSONATION определяет клиента уровня IMPERSONATION.
SECURITY_DELEGATION - определяет клиента уровня DELEGATION.
- SECURITY_CONTEXT_TRACKING - определяет, что способ отслеживания безопасности является динамическим.
- SECURITY_EFFECTIVE_ONLY - определяет, что только позволенные аспекты содержания безопасности клиента доступны серверу. Если Вы не определяете этот флаг, все аспекты содержания безопасности клиента доступны. Этот флаг позволяет клиенту ограничивать группы и привилегии которые сервер может использовать при исполнении запроса клиента.
hTemplateFile - Определяет указатель с доступом GENERIC_READ к файлу шаблона. Файл шаблона задает признаки файла и расширенные признакаки для создаваемого файла.
Windows 95: Этот флаг должен быть равен NULL. Если Вы установливаете указатель под Windows 95, запрос терпит неудачу, и GetLastError возвращает ERROR_NOT_SUPPORTED.
Возвращаемые значения
Если функция преуспевает - открытый указатель к файлу. Если указанный файл существовал до запроса функции и dwCreationDistribution - CREATE_ALWAYS или OPEN_ALWAYS, запрос к GetLastError возвращает ERROR_ALREADY_EXISTS. Если файл не существовал перед запросом, GetLastError возвращает ноль.
Если функция терпит неудачу - INVALID_HANDLE_VALUE. Чтобы получить расширенную информацию об ошибке, вызовите GetLastError.
Примечания
Используйте функцию CloseHandle, чтобы закрыть указатель объекта, возвращенную CreateFile.
Как отмечено выше, определяя ноль для dwDesiredAccess функция позволяет узнать признаки устройства, фактически не обращаясь к устройству. Этоо полезено, например, если функция хочет узнать размер дискеты, и поддерживаемые форматы, при этом не имея дискеты в дисководе.
Файлы
При создании нового файла, функция CreateFile исполняет следующие действия:
· объединяет признаки файла и флаги, указанные dwFlagsAndAttributes с FILE_ATTRIBUTE_ARCHIVE.
· устанавливает длину файла на ноль.
· копирует расширенные признаки, заданные файлом шаблона к новому файлу, если параметр hTemplateFile определен.
При открытии существующего файла, CreateFile исполняет следующие действия:
· объединяет флаги файла, указанные dwFlagsAndAttributes с существующими признаками файла. CreateFile игнорирует признаки файла, указанные dwFlagsAndAttributes.
· устанавливает длину файла согласно флагу dwCreationDistribution.
· игнорирует параметр hTemplateFile.
· игнорирует параметр lpSecurityDescriptor структуры TSecurityAttributes, если lpSecurityAttributes параметр не является NULL. Другие параметры структуры используются. Параметр bInheritHandle - единственный способ указать, может ли указатель файла быть унаследованным.
Если Вы пытаетесь создавать файл на сменном накопителе(дискета, CD-ROM) который не имеет вставленного носиеля, система показывает окно сообщения, прося пользователя вставить диск или компакт-диск, соответственно. Чтобы препятствовать системе показывать это окно сообщения, вызовите функцию SetErrorMode с флагом SEM_FAILCRITICALERRORS.
Каналы(Pipes)
Если CreateFile открывает клиента, функция использует любой открытый клиент, которая находится в состоянии приема. Процесс открытия может дублировать указатель так много раз как требуется, но, когда-то открытый клиент не может быть открыт на другого клиента.
Mailslots
Если CreateFile открывает клиента-mailslot, функция возвращает INVALID_HANDLE_VALUE, если mailslot-клиент пытается открывать локальный mailslot прежде, чем mailslot-сервер создал его с функцией CreateMailSlot.
Ресурсы Коммуникаций
Функция CreateFile может создать указатель к ресурсу коммуникаций, типа последовательного порта COM1. Для ресурсов коммуникаций, dwCreationDistribution параметром должен быть OPEN_EXISTING, и hTemplate параметр должен быть NULL. Указатель можен быть открыть для записи, чтения, чтения-записи.
Дисковое устройство
Windows NT: Вы можете использовать функцию CreateFile, чтобы открыть дисковод. Функция возвращает указатель на дисковые устройства. Указатель может использоваться с функцией DeviceIOControl. Следующие требования должны быть выполнены:
· вызывающий должен иметь привилегии администратора.
· строка lpFileName должна иметь форму \.\PHYSICALDRIVEx, чтобы открыть жесткий диск x. Номера жесткого диска начинаются с нуля. Например: \.\PHYSICALDRIVE2 - получает указатель на третий физический диск на компьютере пользователя.
· строка lpFileName должна быть \.\x: чтобы открыть накопитель на гибких дисках. Например: \.\A: - получает указатель,на диск А. \.\C: - получает указатель,на диск C.
Windows 95: Эта функция не открывает логическое устройство. В Windows 95 это вызовет ошибку.
· параметр dwCreationDistribution должен иметь флаг OPEN_EXISTING.
· при открытии дискеты или жесткого диска, Вы должны установить флаг FILE_SHARE_WRITE в параметре dwShareMode .
Консоли (consoles)
Функция CreateFile может создать указатель ввод консоли (CONIN$). Если процесс имеет открытый указатель к нему в результате наследования или дублирования, то функция может также создать указатель на активный буфер экрана (CONOUT$). Процесс запроса должен быть присоединен к унаследованной консоли или один размещенный функцией AllocConsole. Для указателей консоли, установите параметры CreateFile следующим образом:
lpFileName - используют CONIN$, чтобы определить ввод консоли и CONOUT$, чтобы определить вывод консоли.
CONIN$ получает указатель на входной буфер консоли, даже если функция SetStdHandle переадресовывала стандартный указатель. Чтобы получить стандартный указатель, используйте функцию GetStdHandle.
CONOUT$ получает указатель на активный буфер экрана, даже если SetStdHandle переадресовывала стандартный указадель вывода. Чтобы получить стандартный указатель выводо используйте GetStdHandle.
dwDesiredAccess лучше устанавливать GENERIC_READ | GENERIC_WRITE, но любой может ограничить доступ.
dwShareMode, если процесс запроса унаследовал консоль или если дочерний процесс способен получить доступ, этот параметр должен быть FILE_SHARE_READ | FILE_SHARE_WRITE.
lpSecurityAttributes, если Вы хотите, чтобы консоль была унаследована,параметр bInheritHandle структуры TSecurityAttributes должен быть True.
dwCreationDistribution Вы должны определить OPEN_EXISTING при использовании CreateFile, чтобы открыть консоль.
dwFlagsAndAttributes игнорируется.
hTemplateFile игнорируется.
Следующий список показывает эффекты различных назначений fwdAccess и lpFileName.
lpFileName fwdAccess Результат
CON GENERIC_READ Открывает консоль для ввода
CON GENERIC_WRITE Открывает консоль для вывода
CON GENERIC_READ\GENERIC_WRITE Windows 95:Терпит неудачу; GetLastError возвращает ERROR_PATH_NOT_FOUND.
Windows NT: Терпит неудачу; GetLastError возвращает ERROR_FILE_NOT_FOUND.
Папки
Вызов функции CreateFile не может создать папку, чтобы создать папку надо вызвать CreateDirectory или CreateDirectoryEx.
Windows NT:Вы можете получить указатель к папку, подставив флаг FILE_FLAG_BACKUP_SEMANTICS . Указатель папки можно передать некоторым функциям Win32 вместо указателя файла. Некоторые файловые системы, типа NTFS, поддерживают сжатие для индивидуальных файлов и папок. На устройствах, форматированных для такой файловой системы, новая папка унаследует признак сжатия ее родительской папки.
Материал взят из:
Русская спpавка по Windows API
Этот параметр может содержать любую комбинацию файловых атрибутов. Все другие файловые атрибуты перезаписывают FILE_ATTRIBUTE_NORMAL.
Когда CreateFile открывает файл, атрибуты файла комбинируются с существующими атрибутами файла, и игнорируются любые запрошенные файловые атрибуты.
Следующие файловые атрибуты и флаги используются только для файловых объектов, а не для других типов объектов, которые создает CreateFile.
FILE_ATTRIBUTE_ARCHIVE
Файл может быть заархивирован. Приложение использует этот атрибут для пометки файлов для резервного копирования или перемещения.
FILE_ATTRIBUTE_ENCRYPTED
Фал или дериктория зашифрованы. Для файла, это означает, что все данные в файле зашифрованы. Для директории, это означает, что шифрование применяется по умолчанию для новосозданных файлов и поддиректорий.
Этот флаг не имеет эффекта, если также установлен FILE_ATTRIBUTE_SYSTEM.
FILE_ATTRIBUTE_HIDDEN
Файл спрятан (скрыт).
FILE_ATTRIBUTE_NORMAL
Файл не имеет других установленных атрибутов. Этот атрибут действителен, если он установлен одним.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
Файл не индексируется контекстом сервиса индексирования.
FILE_ATTRIBUTE_OFFLINE
Данные файла не являются немедленно достижимыми. Этот атрибут указывает, что данные файла физически перемещены на внешнее хранилище. Приложение не может произвольно изменять этот атрибут.
FILE_ATTRIBUTE_READONLY
Файл только для чтения. Приложение может читать из файла, но не может записываеть в него, или его удалить.
FILE_ATTRIBUTE_SYSTEM
Файл – это часть или используется исключительно операционной системой.
FILE_ATTRIBUTE_TEMPORARY
Файл будет использован для временного хранения. Файловая система избегает записи данных назад в хранилище, если имеется в распоряжении достаточно кэша, потому что приложение удаляет временный файл после того, как дескриптор закрывается. В этом случае, система может всецело избежать записи данных. В другом случае, данные записываются после закрытия дескриптора.
Этот параметр может также содержать любую комбинацию следующих флагов:
FILE_FLAG_BACKUP_SEMANTICS
Файл будет открыт или создан для операции резервного сохранения или восстановления. Система гарантирует, что вызывающий процесс не принимает во внимание проверку безопасности файла, когда процесс имеет привилегии SE_BACKUP_NAME и SE_RESTORE_NAME.
Вы можете установить этот флаг, получив дескриптор директории. Дескриптор директории может быть передан некоторым функциям вместо файлового дескриптора.
Windows Me/98/95: Этот флаг не поддерживается.
FILE_FLAG_DELETE_ON_CLOSE
Система удаляет файл сразу, когда все его дескрипторы будут закрыты, учитывая указанный дескриптор и любые откртые или скопированные дескрипторы.
Если существует открытые дескриптор файла, вызов функции будет не успешен, если только они (дескрипторы) не имеют режим разделяемости FILE_SHARE_DELETE.
Последовательные запросы на открытие для файла будут неудачны, если не указан режим разделяемости FILE_SHARE_DELETE.
FILE_FLAG_NO_BUFFERING
Система открывает файл без системного кэширования. Этот флаг не эффективен в кэшировании жесткого диска. Если он комбинирован с FILE_FLAG_OVERLAPPED, флаг дает максимальную производительность ассинхронности потому, что вв/выв не полагается на синхронные операции менеджера памяти. Тем не менее, некоторые операции вв/выв забирают больше времени потому, что данные не сохранены в кэше. Также, метаданные файла могут все еще кэшироваться. Для сброса метаданных на диск, используйте функцию FlushFileBuffers.
Приложение должно удовлевотворять определенным условиям когда работает с файлами, открытыми с флагом FILE_FLAG_NO_BUFFERING:
- Файловый доступ должен начинаться с байтового смещения внутри файла, которое имет целочислительную кратность с размером сектора раздела.
- Файловый доступ должен быть количеством байт, которое имет целочислительную кратность с размером сектора раздела. Например, если размер сектора 512 байт, приложение может затребовать чтение и записть 512, 1024, или 2048 байт, но не 335, 981, или 7171 байт.
- Адреса буфера для чтения или записи должны быть выровнены по сектору, что означает выравнивание по адресам памяти, которые имеют целочислительную кратность с размером сектора раздела. В зависимости от диска, это требование может быть не задействовано.
Приложение может получить размер сектора раздела, вызвав функцию GetDiskFreeSpace.
FILE_FLAG_OPEN_NO_RECALL
Данные файла были затребованы, но должно продолжаться их устраивание на удаленном хранилище. Этот флаг для использования системой удаленного хранения.
FILE_FLAG_OPEN_REPARSE_POINT
Система препятствует поведению возмещения файлововой системы NTFS точек препятствия. Этот флаг не может использоваться с флагом CREATE_ALWAYS.
FILE_FLAG_OVERLAPPED
Файл будет открыт или создан для ассинхронного вв/выв. Когда операция завершена, событие указанное к вызову в структуре OVERLAPPED, устанавливается в сигнальное состояние. Операции, которые требуют много количества времени процессу, возвращают ERROR_IO_PENDING.
Если указан этот флаг, файл может быть использован для одновременных операций чтения и записи. Система не изменяет файловый указатель – вы сами должны это делать, передавая файловую позицию к функциям чтения и записи в структуре OVERLAPPED, или обновлять файловый указатель.
Если этот флаг не указан, тогда операции вв/выв являются серийными, даже если в вызовах функций чтения и записи определена структура OVERLAPPED.
FILE_FLAG_POSIX_SEMANTICS
Доступ к файлу осуществляется по правилам POSIX. При этом учитывается регистр символов в имени файла, для файловых систем, которые учитывают такие имена. Используйте с осторожностью эту опцию потому, что создание файлов с этим флагом может быть не доступно приложениям, которые написаны для MS-DOS или 16-битного Windows.
FILE_FLAG_RANDOM_ACCESS
Доступ к файлу непоследователен. Система может использовать это как подсказку при кэшировании файла.
FILE_FLAG_SEQUENTIAL_SCAN
Доступ к файлу последователен от начала до конца. Система может использовать это как подсказку при кэшировании файла. Если приложение передвигает файловый указатель для произвольного доступа, оптимальное кэширование не происходит. Тем не менее, корректность операции гарантируется.
Установив этот флаг, можно подвысить производительность приложения, которое последовательно читает большие файлы.
FILE_FLAG_WRITE_THROUGH
Система записывает мимо любого промежуточного кэша прямо на диск.
Если также установлен флаг FILE_FLAG_NO_BUFFERING, систеное кэширование эффективно так, что данные записываются в системный кэш, но сбрасываются на диск без замедления.
Параметр dwFlagsAndAttributes может также содержать Качества Безопасности. Когда вызывающее приложение определяет флаг SECURITY_SQOS_PRESENT, параметр dwFlagsAndAttributes может принимать одно или более из следующих значений:
SECURITY_ANONYMOUS
Испольнять роль клиента в уровне анонимности.
SECURITY_CONTEXT_TRACKING
Режим выслеживания безопасности динамичен. Если этот флаг не указан, режим выслеживания безопасности статичен.
SECURITY_DELEGATION
Испольнять роль клиента в уровне делегации.
SECURITY_EFFECTIVE_ONLY
Допустить только аспекты контекста безопасности клиента допустимыми на сервере. Если вы не устанавливаете этот флаг, все аспекты контекста безопасности клиента доступны.
Это позволяет клинету ограничивать группы и привилегии, которы сервер может использовать исполняющий роль клиента.
SECURITY_IDENTIFICATION
Испольнять роль клиента в уровне опознавания.
SECURITY_IMPERSONATION
Испольнять роль клиента в уровне испольняющего роль.