OVERLAPPED structure

看CSerialPort串口类的时候，有几个结构体不是很认识，所以你懂得的。

---------------------加强版分割线----------------------

手工翻译，转载请显要的注明出处，并保持文章的完整性。

原文链接：http://msdn.microsoft.com/en-us/library/windows/desktop/ms684342%28v=vs.85%29.aspx

-----------------------------------------------你在找我吗？-----------------------------------------------

文章全文复制于MSDN，我只是翻译一下，改了一点格式，并加上了自己的一些注释。

----------------------------------------------------------------------------------------------------------------

OVERLAPPED structure

Contains information used in asynchronous (or overlapped) input and output (I/O).包含了同步（或者重叠）I/O所使用的信息。

Syntax

C++

typedef struct _OVERLAPPED {ULONG_PTR Internal;ULONG_PTR InternalHigh;union {struct {DWORD Offset;//文件低位DWORD OffsetHigh;//文件高位};PVOID  Pointer;};HANDLE    hEvent;//} OVERLAPPED, *LPOVERLAPPED;

Members

Internal

The status code for the I/O request. When the request is issued, the system sets this member toSTATUS_PENDING to indicate that the operation has not yet started. When the request is completed, the system sets this member to the status code for the completed request.I/O请求的状态码。当发出了请求，系统将这个成员设置为STATUS_PENDING来表示操作还没有开始。当请求完成，系统将这个成员的状态设置为完成请求。

The Internal member was originally reserved for system use and its behavior may change.这个成员最初被设计为供系统使用，他的行为是不确定的。

InternalHigh

The number of bytes transferred for the I/O request. The system sets this member if the request is completed without errors.I/O请求转移的字节数。如果请求完成后没有出现错误，系统会设置这个成员。

The InternalHigh member was originally reserved for system use and its behavior may change.这个成员最初被设计为供系统使用，他的行为是不确定的。

Offset

The low-order portion of the file position at which to start the I/O request, as specified by the user.由用户指定的I/O请求开始的文件的低段部分。

This member is nonzero only when performing I/O requests on a seeking device that supports the concept of an offset (also referred to as a file pointer mechanism), such as a file. Otherwise, this member must be zero.这个成员只有当在支持offset的seeking设备上作为文件（也使用文件指针机制）来执行I/O请求的时候才不为0。否则，这个成员必须为0。

For additional information, see Remarks.更多信息参见Remarks。

OffsetHigh

The high-order portion of the file position at which to start the I/O request, as specified by the user.由用户指定的I/O请求开始的文件的高段部分。

This member is nonzero only when performing I/O requests on a seeking device that supports the concept of an offset (also referred to as a file pointer mechanism), such as a file. Otherwise, this member must be zero..这个成员只有当在支持offset的seeking设备上作为文件（也使用文件指针机制）来执行I/O请求的时候才不为0。否则，这个成员必须为0。

For additional information, see Remarks.更多信息参见Remarks。

Pointer

Reserved for system use; do not use after initialization to zero.系统保留，初始化为0后请勿使用。

hEvent

A handle to the event that will be set to a signaled state by the system when the operation has completed. The user must initialize this member either to zero or a valid event handle using theCreateEvent function before passing this structure to any overlapped functions. This event can then be used to synchronize simultaneous I/O requests for a device. For additional information, see Remarks.当操作完成后会被系统设置为有信号状态的事件句柄。用户必须初始化这个变量为0或者在把这个结构体传递给其他重叠函数之前使用CreateEvent函数创建一个可用的事件句柄。这个事件可以用来同步同一设备同时发生的IO请求。更多信息参见Remarks。

Functions such as ReadFile and WriteFile set this handle to the nonsignaled state before they begin an I/O operation. When the operation has completed, the handle is set to the signaled state.类似于ReadFile和Writefile的函数在他们开始I/O操作之前会设置这个句柄为无信号状态。当操作完成后，这个句柄被设置为有信号状态。

Functions such as GetOverlappedResult and the synchronization wait functions reset auto-reset events to the nonsignaled state. Therefore, you should use a manual reset event; if you use an auto-reset event, your application can stop responding if you wait for the operation to complete and then callGetOverlappedResult with the bWait parameter set to TRUE.类似于GetOverlappedResult的函数和同步等待函数重置自动重置事件为无信号状态。因此，你需要使用人工重置事件；如果你使用了自动重置事件，当你等待操作完成后使用GetOverlappedResult函数并将bWait参数置为TRUE时，你的应用程序可能会停止响应。

Remarks

Any unused members of this structure should always be initialized to zero before the structure is used in a function call. Otherwise, the function may fail and returnERROR_INVALID_PARAMETER.这个结构体中任何未使用的成员在函数中使用之前都必须初始化为0。

The Offset and OffsetHigh members together represent a 64-bit file position. It is a byte offset from the start of the file or file-like device, and it is specified by the user; the system will not modify these values. The calling process must set this member before passing the OVERLAPPED structure to functions that use an offset, such as theReadFile or WriteFile (and related) functions.Offset和OffsetHigh成员一起代表了64位的文件位置。这是一个从文件或者文件类设备头部开始的字节偏移，由用户指定；系统不会修改这些值。调用进程在传递OVERLAPPED结构体给一个使用偏移的函数之前（例如Readfile和WriteFile），必须设置这（两）个成员。

You can use the HasOverlappedIoCompleted macro to check whether an asynchronous I/O operation has completed ifGetOverlappedResult is too cumbersome for your application.如果GetOverlappedResult函数对你的程序来说太繁重了，你也可以使用HasOverlappedIoCompleted宏来检测异步I/O操作是否完成。

You can use the CancelIo function to cancel an asynchronous I/O operation.你可以使用CancelIo函数来取消一个异步I/O操作。

A common mistake is to reuse an OVERLAPPED structure before the previous asynchronous operation has been completed. You should use a separate structure for each request. You should also create an event object for each thread that processes data. If you store the event handles in an array, you could easily wait for all events to be signaled using theWaitForMultipleObjects function.一个常见的错误是在先前的异步操作完成之前重用同一个OVERLAPPED结构体。你需要为每一个请求单独使用一个结构体。你也必须为每一个处理数据的线程创建一个单独的事件对象。如果你把事件句柄存在数组里，你能够轻松的使用waitForMultipleObjects函数来等待所有的事件变成有信号状态。

For additional information and potential pitfalls of asynchronous I/O usage, seeCreateFile,ReadFile,WriteFile, and related functions.更多的关于异步I/O用法的信息和一些潜在的误区，参见CreateFile,ReadFile,Writefile。

For a general synchronization overview and conceptual OVERLAPPED usage information, seeSynchronization and Overlapped Input and Output and related topics.一般的……

For a file I/O–oriented overview of synchronous and asynchronous I/O, see Synchronous and Asynchronous I/O.基于文件的……

Examples

For an example, see Named Pipe Server Using Overlapped I/O.

Requirements

Minimum supported client

Windows XP [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2003 [desktop apps | Windows Store apps]

Header

WinBase.h on Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008, and Windows Server 2008 R2 (include Windows.h);

MinWinBase.h on Windows 8 and Windows Server 2012

See also

CancelIo

CreateFile

GetOverlappedResult

HasOverlappedIoCompleted

ReadFile

Synchronization and Overlapped Input and Output

Synchronous and Asynchronous I/O

WriteFile