Функция WriteFileEx


Функция WriteFileEx пишет данные в файл. Она сообщает о своем состоянии завершения асинхронно, вызывая заданную процедуру завершения, когда запись завершается или отменяется, а вызывающий поток находится в готовом к действию режиме ожидания.

Чтобы записать данные в файл синхронно, используйте функцию WriteFile.

Синтаксис

BOOL WriteFileEx(
  HANDLE hFile,                      // дескриптор файла вывода
  LPCVOID lpBuffer,                  // буфер данных
  DWORD nNumberOfBytesToWrite,       // число байтов для записи
  LPOVERLAPPED lpOverlapped,         // асинхронный буфер
  LPOVERLAPPED_COMPLETION_ROUTINE
              lpCompletionRoutine    // процедура завершения
);

Параметры

hFile
[in] Дескриптор файла. Этот дескриптор файла должен быть создан с флажком FILE_FLAG_OVERLAPPED и правом доступа GENERIC_WRITE. Подробную информацию о правах доступа, см. в статье Защита файла и права доступа.

Windows NT/2000/XP: Этот параметр может быть любым дескриптором, открытым с флажком FILE_FLAG_OVERLAPPED функцией CreateFile, или дескриптором сокета, возвращенного функцией socket или accept.

Windows 95/98/Me: Этим параметром может быть коммуникационный ресурс, открытый с флажком FILE_FLAG_OVERLAPPED функцией CreateFile или дескриптором сокета, возвращенным socket или accept. Вы не можете исполнить асинхронные операции записи в почтовом ящике ядра Windows, в именованных каналах или дисковых файлах.

lpBuffer
[in] Указатель на буфер, содержащий данные для записи в файл.

Этот буфер должен оставаться допустимым на время операции записи. Вызывающая программа не должна использовать этот буфер до тех пор, пока операция записи не завершится.

nNumberOfBytesToWrite
[in] Число байтов для записи в файл.

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

lpOverlapped
[in] Указатель на структуру данных OVERLAPPED, которая предоставляет данные, используемые в ходе перекрывающей (асинхронной) операции записи.
Для файлов, которые поддерживают смещения байтов, Вы должны задать смещение байта так, чтобы начать писать в файл. Вы определяете это смещение, устанавливая члены Offset и OffsetHigh  структуры OVERLAPPED. Для файлов, которые не поддерживают, смещения байтов, члены Offset и OffsetHigh игнорируются.

Функция WriteFileEx игнорирует член hEvent структуры OVERLAPPED. Приложение может свободно использовать этот член структуры для своих собственных целей в контексте вызова WriteFileEx. Функция WriteFileEx подает сигнал о  завершении ее операции записи при помощи вызова, или постановки в очередь вызова процедуры завершения работы, на которую указывает параметр lpCompletionRoutine, так что обработка события не требуется .

Функция WriteFileEx использует члены Internal и InternalHigh структуры OVERLAPPED. Вы не должны менять значения этих членов структуры.

Структура данных OVERLAPPED должна оставаться допустимой в ходе операции записи. Она не должна быть переменной, которая может выйти из пределов видимости, когда происходит задержка завершения операции записи.

lpCompletionRoutine

[in] Указатель на процедуру завершения, которая вызывается тогда, когда операция записи завершилась, а вызывающий поток, находится в готовом к действию состоянии ожидания. Для получения дополнительной информации об этой процедуре завершения см. описание функции FileIOCompletionRoutine.

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

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

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

Если функция WriteFileEx завершается успешно, вызывающий поток имеет задержку асинхронной операции I/O (ввода/вывода): асинхронной операции записи в файл. Когда эта операция ввода-вывода (I/O) достигает конца, а вызывающий поток заблокирован в готовом к действию состоянии ожидания, операционная система вызывает функцию, на которую указывает параметр lpCompletionRoutine, и ожидает завершения с кодом возврата WAIT_IO_COMPLETION.

Если функция завершается успешно и достигается конец операции записи в файл, но вызывающий поток не находится в готовом к действию состоянии ожидания, система ставит в очередь вызов  *lpCompletionRoutine, удерживая его до тех пор, пока вызывающий поток не войдет в готовое к действию состояние ожидания. Для получения дополнительной информации о готовых к действию состояниях ожидания и асинхронных операциях ввода-вывода см. главу Синхронизация.

Замечания

При использовании WriteFileEx вам следует делать проверку на ошибки при помощи GetLastError даже тогда,  когда функция возвращает значение "успешно", чтобы проверять состояния, которые являются "успешными", но могут иметь определенный результат, о котором Вы хотели  бы знать. Например, буфер переполняется, когда вызов WriteFileEx возвращает значение ИСТИНА (TRUE), а GetLastError сообщит о переполнении с ошибкой ERROR_MORE_DATA. Если вызов функции завершился успешно и нет никаких настораживающих состояний, GetLastError возвратит значение ERROR_SUCCESS.

Функция WriteFileEx может завершиться ошибкой, если имеется слишком много ожидающих обработки асинхронных запросов ввода - вывода, возвращая сообщение ERROR_INVALID_USER_BUFFER или ERROR_NOT_ENOUGH_MEMORY.

Чтобы отменить  все незаконченные асинхронные операции ввода-вывода (I/O), используйте функцию CancelIo. Эта функция  отменяет только операции, порождаемые вызывающим потоком, для заданного дескриптора файла. Отмененные операции ввода-вывода (I/O) завершаются ошибкой ERROR_OPERATION_ABORTED.

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

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

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

Когда работа с файлами открывается с флажком FILE_FLAG_NO_BUFFERING, приложение должно соответствовать некоторым требованиям:

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

Если Вы пытаетесь писать в накопителе на гибких дисках, который не имеет дискеты, система показывает на экране окно сообщения, предлагающее пользователю повторить  операцию. Чтобы воспрепятствовать системе показывать это окно, вызовите функцию SetErrorMode с флажком SEM_NOOPENFILEERRORBOX.

Приложение использует функции MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx, SignalObjectAndWait и  SleepEx, чтобы войти в готовый к действию режим ожидания. Для получения дополнительной информации о готовых к действию состояниях ожидания и асинхронных операциях ввода - вывода обращайтесь к описанию этих функций и к главе Синхронизация.

Windows 95/98/Me: Ни ReadFileEx, ни WriteFileEx   последовательными портами коммуникации использоваться не могут. Однако, чтобы выполнить асинхронный обмен данными, Вы можете использовать функции ReadFile и WriteFile.

Код примера

Пример смотри в статье Использование процедуры завершения работы сервером именованного канала

Смотри также 

Обзор Управление файлами Функции для файлового ввода-вывода (I/O), CancelIo, CreateFile, FileIOCompletionRoutine, MsgWaitForMultipleObjectsEx, OVERLAPPED, ReadFileEx, SetEndOfFile, SetErrorMode,  SleepEx, SignalObjectAndWait, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFile

 

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

К

Windows XP

Да 

л

Windows 2000 Professional

Да

и

Windows NT Workstation

Да

е

Windows Me

Да

н

Windows 98

Да

т

Windows 95

Да

 
С

Windows Server 2003

Да

е Windows 2000 Server Да
р Windows NT Server Да
в    
е    
р    

Используемая библиотека

Kernel32.lib

Используемая DLL -
Заголовочный файл  

- объявлено в

Winbase.h

 - включено в

Windows.h

 Unicode

Нет

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz