OVERLAPPED structure (shobjidl.h)
Contains information used in asynchronous (overlapped) input/output (I/O).
Syntax
typedef struct _OVERLAPPED {
ULONG_PTR Internal;
ULONG_PTR InternalHigh;
union {
struct {
DWORD Offset;
DWORD OffsetHigh;
};
PVOID Pointer;
};
HANDLE hEvent;
} OVERLAPPED, *LPOVERLAPPED;
Members
Internal
Type: ULONG_PTR
Reserved for operating system use. This member, which specifies a system-dependent status, is valid when the IStreamAsync::OverlappedResult function returns without setting the extended error information to ERROR_IO_PENDING.
InternalHigh
Type: ULONG_PTR
Reserved for operating system use. This member, which specifies the length of the data transferred, is valid when the IStreamAsync::OverlappedResult function returns TRUE.
Offset
Type: DWORD
File position at which to start the transfer. The file position is a byte offset from the start of the file. The calling process must set this member before it calls the IStreamAsync::ReadAsync or IStreamAsync::WriteAsync function.
OffsetHigh
Type: DWORD
High-order word of the file position at which to start the transfer.
Pointer
Type: PVOID
Reserved.
hEvent
Type: handle
Handle to an event that is set to the signaled state when the operation has been completed. The calling process must set this member either to zero or a valid event handle before it calls any overlapped functions. To create an event object, use the CreateEvent function. This function returns a handle that can be used to synchronize simultaneous I/O requests for a device.
Functions such as IStreamAsync::ReadAsync and IStreamAsync::WriteAsync 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.
Functions such as IStreamAsync::OverlappedResult and the wait functions reset auto-reset events to the nonsignaled state. Therefore, if an auto-reset event is used, the application can stop responding if it waits for the operation to complete and then calls IStreamAsync::OverlappedResult.
Remarks
This structure should always be initialized to zero before it is used in a function call. If it is not, the function can fail and return ERROR_INVALID_PARAMETER.
Use the IStreamAsync::CancelIo function to cancel an asynchronous I/O operation.
A common mistake is to reuse an OVERLAPPED structure before the previous asynchronous operation has been completed. Use a separate structure for each request. Create an event object for each thread that processes data.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows Vista [desktop apps only] |
Minimum supported server | Windows Server 2008 [desktop apps only] |
Header | shobjidl.h |