Функция WriteFile
ФункциятаWriteFileзаписва данни във файла от местоположението, посочено от индикатора за позиция на файла. Тази функция е както за синхронна, така и за асинхронна работа.
ФункциятаWriteFileExе само за асинхронна работа.
[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, именувани канали или дискови файлове.
[in] Указател към буфер, съдържащ данните, които трябва да бъдат записани в .
[in] Броят байтове, които трябва да бъдат записани в .
Стойност нула определя празна операция за запис. Поведението на празна операция за запис зависи от основната файлова система. За да съкратите или разширите файл, използвайте функциятаSetEndOfFile.
Записите на именувани канали в цялата мрежа са ограничени до 65 535 байта.
[out] Указател към променлива, която получава броя на записаните байтове. ФункциятаWriteFileзадава тази стойност на нула, преди да извърши каквато и да е работа или да открие грешки.
Windows NT/2000/XP:АкоlpOverlappedе NULL,lpNumberOfBytesWrittenне може да бъде NULL. АкоlpOverlappedне е NULL,lpNumberOfBytesWrittenможе да бъде NULL. Ако това е асинхронна операция за запис, можете да получите броя на записаните байтове, като извикате функциятаGetOverlappedResult. Ако параметърhFileе свързан с I/O порт за завършване (I/O), можете да получите броя на записаните байтове чрез извикване на функциятаGetQueuedCompletionStatus.
Ако I/O Completion Ports (I/O) се използват и използвате процедура за обратно извикване, за да освободите заетата памет от структуратаOVERLAPPED, към която сочи параметърътlpOverlapped, задайте стойността на този параметър на NULL, за да избегнете проблема с повреда на паметта по време на освобождаване на ресурси. Този проблем с повреда на паметта причинява връщането на грешен брой байтове в този параметър.
Windows 95/98/Me:Този параметър не може да бъде NULL.
[in] Указател към структураPRELAPTED. Тази структура е необходима, ако параметърътhFileе създаден с флагаFILE_FLAG_OVERLAPPED.
АкоhFileе отворен сFILE_FLAG_OVERLAPPEDфлаг,lpOverlappedне трябва да е NULL. Тя трябва да сочи към валидна структураПРЕОПОЛАГАНЕ. Ако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 операция (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 заявки.
За да отмените всички чакащи асинхронни I/O (I/O) операции, използвайте функциятаCancelIo. Тази функция отменя само операциите, породени от извикващата нишка за дадения файлов дескриптор. I/O операции (I/O), които се отменят, се провалят сERROR_OPERATION_ABORTED.
Когато пишете във файл, последното време за запис не се актуализира напълно, докато всички манипулатори, използвани за запис, не бъдат затворени. Следователно, за да гарантирате точното последно време за запис, затворете файловия дескриптор веднага след като файлът е записан.
Ако част от файла е заключена от друг процес и операция за запис припокрива заключената част, функциятаWriteFileе неуспешна.
Достъпът до изходен буфер, докато операция за запис използва буфера, може да повреди данните, записани от този буфер. Приложенията не трябва да записват, преразпределят или освобождават изходния буфер, който операцията за запис използва, докато не приключиработа.
Приложението трябва да отговаря на определени изисквания при работа с файлове, отворени с флагFILE_FLAG_NO_BUFFERING:
Системата интерпретира нулеви байтове за запис като дефиниция на празна операция за запис иWriteFileне съкращава или разширява файла. За да изрежете или разширите файл, използвайте функциятаSetEndOfFile.
Когато записвате в неблокиращ манипулатор на тръба в байтов режим с недостатъчно буферно пространство,WriteFileвръща TRUE с опции*lpNumberOfBytesWritten
Когато дадено приложение използва функциятаWriteFileза запис в канал, операцията по запис не може да завърши, ако буферът на канала е пълен. Операцията за запис приключва, когато операцията за четене (използвайки функциятаReadFile) освободи повече буферно пространство.
Ако манипулаторът за анонимен канал за четене е затворен иWriteFileсе опитва да пише, използвайки съответния манипулатор за канал за анонимен запис, функцията връща FALSE иGetLastErrorвръща грешкатаERROR_BROKEN_PIPE.
Букви или знаци могат да се записват в екранния буфер с помощта на функциятаWriteFileс манипулатор към изхода на конзолата. Конзолният режим на работа определя правилното поведение на функцията. Данните се записват в текущата позиция на курсора. Позицията на курсора се актуализира след операцията за запис.
Ако се опитате да пишете на флопи устройство, което няма флопи диск, системата показва поле със съобщение, подканващо потребителя да опита отново операцията. За да попречите на системата да показва този прозорец със съобщения, извикайте функциятаSetErrorModeс флагаSEM_NOOPENFILEERRORBOX.
Поставяне исъвместимостWriteFile