Функция WriteFile


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

Функция WriteFileEx предназначена исключительно для асинхронной операции. 

Синтаксис

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

Параметры

hFile

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

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

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

lpBuffer

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

nNumberOfBytesToWrite

[in] Число байтов, которые будут записаны в файл.

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

Операции записи в именованном канале по всей сети ограничены 65 535 байтами.

lpNumberOfBytesWritten

[out] Указатель на переменную, которая получает число записанных байтов. Функция WriteFile устанавливает это значение в  нуль перед выполнением какой-либо работы или выявлением ошибок.

Windows NT/2000/XP: Если параметр lpOverlapped равен ПУСТО (NULL), то параметр lpNumberOfBytesWritten не может быть ПУСТО (NULL). Если lpOverlapped - не ПУСТО (NULL), lpNumberOfBytesWritten может быть ПУСТО (NULL). Если это асинхронная операция записи, Вы можете получить число записанных байтов при помощи вызова функции GetOverlappedResult. Если параметр hFile связан с портом завершения ввода-вывода (I/O), Вы можете получить число записанных байтов при помощи вызова функции GetQueuedCompletionStatus.

Если порты завершения ввода-вывода (I/O) используются, а Вы используете процедуру обратного вызова, чтобы освободить занимаемую память структурой OVERLAPPED, на которую указывает параметр lpOverlapped, установите  ПУСТО (NULL) как значение этого параметра, чтобы избежать проблемы порчи данных в памяти в ходе освобождения ресурса. Эта проблема порчи данных в памяти становится причиной неправильного числа байтов, которые возвращаются в этом параметре.

Windows 95/98/Me: Этот параметр не может быть ПУСТО (NULL).

lpOverlapped

[in] Указатель на структуру OVERLAPPED. Эта структура требуется тогда, если параметр hFile создавался с флажком FILE_FLAG_OVERLAPPED.

Если hFile был открыт с флажком FILE_FLAG_OVERLAPPED, у параметра lpOverlapped  не должно быть значения ПУСТО (NULL). Он должен указывать на правильную структуру OVERLAPPED. Если hFile был открыт с флажком FILE_FLAG_OVERLAPPED, а lpOverlapped имеет значение ПУСТО (NULL), функция может неправильно сообщить о завершении операции записи.

Если hFile был открыт с флажком FILE_FLAG_OVERLAPPED, а lpOverlapped имеет значение не ПУСТО (NULL), операция записи начинается при смещении, заданном в структуре OVERLAPPED, а WriteFile может возвратить значение прежде, чем операция записи будет закончена. В этом случае, WriteFile возвращает значение ЛОЖЬ (FALSE), а функция GetLastError возвращает значение ERROR_IO_PENDING. Это дает возможность вызывающему процессу продолжать работу до тех пор, пока операция записи не закончится. После завершения операции записи, событие, определяемое в структуре OVERLAPPED устанавливается в сигнальное состояние. Вызывающая программа должна корректировать позицию указателя позиции в файле после завершения операции.

Если hFile не открывался с флажком  FILE_FLAG_OVERLAPPED, а lpOverlapped - значение ПУСТО (NULL), операция записи начинается с текущей позиции в файле и WriteFile не возвращает значения до тех пор, пока операция не будет закончена. Система после завершения операции модернизирует указатель позиции в файле.

Функция WriteFile сбрасывает событие, заданное членом hEvent структуры OVERLAPPED в несигнальное состояние, когда она начинает операцию ввода-вывода (I/O). Поэтому, нет какой-либо необходимости вызывающей программе проделывать эту процедуру.

Windows NT/2000/XP: Если hFile не был открыт с флажком FILE_FLAG_OVERLAPPED и lpOverlapped - не ПУСТО (NULL), то операция записи начнется со смещения, заданного в структуре  OVERLAPPED, а WriteFile не возвращает значение до тех пор, пока операция записи не завершится.

Windows 95/98/Me: Для операций с файлами, дисками, каналами или почтовыми ящиками в ядре Windows, этим параметром должно быть значение ПУСТО (NULL); указатель на структуру OVERLAPPED порождает вызов, который завершиться ошибкой. Тем не менее, Windows 95/98/Me поддерживает асинхронные операции на последовательных и параллельном портах.

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

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

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

Замечания

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

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

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

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

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

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

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

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

При записи в неблокированный, байтового режима дескриптор канала с недостаточным буферным пространством, WriteFile возвращает значение ИСТИНА (TRUE) с параметрами *lpNumberOfBytesWritten < nNumberOfBytesToWrite.

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

Если дескриптор анонимного  канала чтения был закрыт, а WriteFile пытается записывать, используя соответствующий дескриптора анонимного канала записи, функция возвращает значение ЛОЖЬ (FALSE), а GetLastError возвращает ошибку ERROR_BROKEN_PIPE.

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

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

Код примера

Пример см. в статье Создание и использование временного файла.

Смотри также 

Обзор Управление файлами Функции для файлового ввода-вывода (I/O), CancelIo, CreateFile, GetLastError, GetOverlappedResult , GetQueuedCompletionStatusOVERLAPPEDReadFileSetCommTimeoutsSetEndOfFile, SetErrorMode, WriteFileEx

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

К

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

Нет

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

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки
Перевод 11.03.2004 12:45 ©Copyright V. Sokovikov
Hosted by uCoz