Функция WriteFile

Синтаксис

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

Параметры

hFile

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

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

lpBuffer

nNumberOfBytesToWrite

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

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

lpNumberOfBytesWritten

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

Если 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 не возвращает значения до тех пор, пока операция не будет закончена. Система после завершения операции модернизирует указатель позиции в файле.

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

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

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

Замечания

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

• Доступ  к файлу должен начаться при смещениях байтов в пределах файла, которые должны быть целыми числами кратными размеру сектора тома. Чтобы выяснить размер сектора тома, вызовите функцию GetDiskFreeSpace.
• Доступ  к файлу должен быть числом байтов, которое является целым числом кратным размеру сектора тома. Например, если размер сектора - 512 байтов, приложение может запросить для чтения и записи  512, 1024 или 2048 байтов, но не 335, 981 или 7171 байт.
• Адреса буферов для операций чтения и записи должны выравниваться кратно сектору (выравниваются адреса в памяти, которые являются целыми числами, кратными размеру сектора тома). Одним из способов выравнивания буфера кратно сектору, является использование функции VirtualAlloc, которая назначает буфера. Эта функция выделяет память, выравнивая их по адресам, которые являются целыми числами, кратными размеру страницы памяти  системы. Поскольку размеры и страницы памяти и  сектора тома являются степенью 2, память, выровненная кратно размеру страницы памяти системы, также выравнивается кратно и размеру сектора тома.

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

Код примера

Смотри также 

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