| 术语 | writefilegather |
| 释义 | WriteFileGather 语法： C++ BOOL WINAPI WriteFileGather( __in HANDLE hFile, __in FILE_SEGMENT_ELEMENT aSegmentArray[], __in DWORD nNumberOfBytesToWrite, __reserved LPDWORD lpReserved, __inout LPOVERLAPPED lpOverlapped ); WriteFileGather功能 检索数据从一个缓冲区的数组和数据写入到一个文件。 函数开始写在一个由一个OVERLAPPED结构指定位置的数据文件。该WriteFileGather异步运行的功能。 参数 hFile [in] 阿处理该文件。文件句柄必须创建与GENERIC_WRITE访问权和FILE_FLAG_OVERLAPPED和FILE_FLAG_NO_BUFFERING标志。有关更多信息，请参阅文件安全性和访问权限。 aSegmentArray [in] 一个对数组的指针的FILE_SEGMENT_ELEMENT缓冲区包含数据。对于这个联盟说明，请参见备注。 每个元素包含一个数据页。 注意：要确定一个系统页的大小，使用的GetSystemInfo函数。 该数组的元素必须包含足够的存储数据nNumberOfBytesToWrite字节，一个终止空元素。例如，如果有40 KB的读取和页大小为4 KB，数组必须有11种元素，其中包括10个数据，一个用于空元素的元素。 每个缓冲区必须至少在一个系统内存页面大小，必须在一个系统内存页大小的边界上对齐。该系统写入一个系统从每个缓冲区数据存储器页。 函数集的顺序在缓冲区的数据。例如，将数据写入到从第一个缓冲文件，然后在第二个缓冲区，依此类推，直到有没有更多的数据。 由于这一职能异步操作，必须采取预防措施，以确保该参数始终引用为终生有效的内存异步写入。例如，一个常见的编程错误是使用本地堆栈存储，然后让执行运行范围内。 nNumberOfBytesToWrite [in] 总字节数要写入。每个aSegmentArray元素包含一个单页的其中一块。因为该文件必须与FILE_FLAG_NO_BUFFERING打开的字节数必须是一个文件系统的多个部门的规模该文件的位置。 如果nNumberOfBytesToWrite是零(0)，函数执行一个空写操作。一个空的行为写操作依赖于底层文件系统。如果nNumberOfBytesToWrite不为零(0)和偏移和写入超出了文件的当前年底的数据长度，WriteFileGather功能扩展了该文件。 lpReserved 这个参数是保留供将来使用，必须为NULL。 lpOverlapped [ in , out ] 一个OVERLAPPED数据结构的指针。 该WriteFileGather函数需要一个有效的OVERLAPPED结构。该lpOverlapped参数不能为NULL。 该WriteFileGather函数开始写作时，这是由偏移和OVERLAPPED结构OffsetHigh成员指定位置的数据文件。 该WriteFileGather函数可能返回写操作前完成。在这种情况下，该WriteFileGather函数返回值零(0)，GetLastError函数返回值ERROR_IO_PENDING。这个WriteFileGather功能异步操作允许调用进程继续下去，而写入操作完成。您可以调用GetOverlappedResult，HasOverlappedIoCompleted，或GetQueuedCompletionStatus函数以获取有关的写操作完成的信息。有关更多信息，请参阅同步和异步I / O。 返回值 如果函数成功，返回值为非零。 如果函数失败，返回值是零(0)。为了获得更多错误信息，调用GetLastError函数。 如果写操作之前，函数返回完成后，该函数返回零(0)，GetLastError函数返回ERROR_IO_PENDING。 备注 此功能不支持32 -基于英特尔Itanium处理器系列的WOW64位应用程序。 该FILE_SEGMENT_ELEMENT工会的定义如下： typedef工会_FILE_SEGMENT_ELEMENT( PVOID64缓冲区; ULONGLONG对齐; )FILE_SEGMENT_ELEMENT，* PFILE_SEGMENT_ELEMENT; 分配给该缓冲区的成员指针将符号扩展，如果代码被编译的价值为32位，这可以打破大报告的应用程序运行的系统配置与使用/ 3GB。在那里，使用PtrToPtr64宏在分配缓冲区的指针。 如果由hFile指定的文件的一部分被锁定，由另一个进程，并写操作锁定重叠部分，WriteFileGather函数失败。 交易业务 如果绑定到文件处理事务，那么操作交易。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 CreateFile 文件管理函数 GetOverlappedResult GetQueuedCompletionStatus HasOverlappedIoCompleted 的OVERLAPPED ReadFile ReadFileEx ReadFileScatter 同步和异步I / O 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝WriteFileGather Function Retrieves data from an array of buffers and writes the data to a file. The function starts writing data to the file at a position that is specified by an OVERLAPPED structure. The WriteFileGather function operates asynchronously. Syntax C++ BOOL WINAPI WriteFileGather( __in HANDLE hFile, __in FILE_SEGMENT_ELEMENT aSegmentArray[], __in DWORD nNumberOfBytesToWrite, __reserved LPDWORD lpReserved, __inout LPOVERLAPPED lpOverlapped ); Parameters hFile [in] A handle to the file. The file handle must be created with the GENERIC_WRITE access right, and the FILE_FLAG_OVERLAPPED and FILE_FLAG_NO_BUFFERING flags. For more information, see File Security and Access Rights . aSegmentArray [in] A pointer to an array of FILE_SEGMENT_ELEMENT buffers that contain the data. For a description of this union, see Remarks. Each element contains one page of data. Note To determine the size of a system page, use the GetSystemInfo function. The array must contain enough elements to store nNumberOfBytesToWrite bytes of data, and one element for the terminating NULL. For example, if there are 40 KB to be read and the page size is 4 KB, the array must have 11 elements that includes 10 elements for the data and one element for the NULL. Each buffer must be at least the size of a system memory page and must be aligned on a system memory page size boundary. The system writes one system memory page of data from each buffer. The function gathers the data from the buffers in a sequential order. For example, it writes data to the file from the first buffer, then the second buffer, and so on until there is no more data. Due to the asynchronous operation of this function, precautions must be taken to ensure that this parameter always references valid memory for the lifetime of the asynchronous writes. For instance, a common programming error is to use local stack storage and then allow execution to run out of scope. nNumberOfBytesToWrite [in] The total number of bytes to be written. Each element of aSegmentArray contains a one-page chunk of this total. Because the file must be opened with FILE_FLAG_NO_BUFFERING, the number of bytes must be a multiple of the sector size of the file system where the file is located. If nNumberOfBytesToWrite is zero (0), the function performs a null write operation. The behavior of a null write operation depends on the underlying file system. If nNumberOfBytesToWrite is not zero (0) and the offset and length of the write place data beyond the current end of the file, the WriteFileGather function extends the file. lpReserved This parameter is reserved for future use and must be NULL. lpOverlapped [in, out] A pointer to an OVERLAPPED data structure. The WriteFileGather function requires a valid OVERLAPPED structure. The lpOverlapped parameter cannot be NULL. The WriteFileGather function starts writing data to the file at a position that is specified by the Offset and OffsetHigh members of the OVERLAPPED structure. The WriteFileGather function may return before the write operation is complete. In that scenario, the WriteFileGather function returns the value zero (0), and the GetLastError function returns the value ERROR_IO_PENDING. This asynchronous operation of the WriteFileGather function lets the calling process continue while the write operation completes. You can call the GetOverlappedResult , HasOverlappedIoCompleted , or GetQueuedCompletionStatus function to obtain information about the completion of the write operation. For more information, see Synchronous and Asynchronous I/O . Return Value If the function succeeds, the return value is nonzero. If the function fails, the return value is zero (0). To get extended error information, call the GetLastError function. If the function returns before the write operation is complete, the function returns zero (0), and the GetLastError function returns ERROR_IO_PENDING. Remarks This function is not supported for 32-bit applications by WOW64 on the Intel Itanium Processor Family. The FILE_SEGMENT_ELEMENT union is defined as follows: typedef union _FILE_SEGMENT_ELEMENT { PVOID64 Buffer; ULONGLONG Alignment; }FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT; Assigning a pointer to the Buffer member will sign-extend the value if the code is compiled as 32-bits; this can break large-address aware applications running on systems configured with /3GB. There, use the PtrToPtr64 macro when assigning pointers to Buffer. If part of the file specified by hFile is locked by another process, and the write operation overlaps the locked portion, the WriteFileGather function fails. Transacted Operations If there is a transaction bound to the file handle, then the operation is transacted. Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinBase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll See Also CreateFile File Management Functions GetOverlappedResult GetQueuedCompletionStatus HasOverlappedIoCompleted OVERLAPPED ReadFile ReadFileEx ReadFileScatter Synchronous and Asynchronous I/O Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa365749(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。