QWinOverlappedIoNotifier Class

The QWinOverlappedIoNotifier class provides support for overlapped I/O notifications on Windows. \since 5.0 \internal. More...

Header: #include <QWinOverlappedIoNotifier>
Inherits: QObject

Public Functions

OVERLAPPED *waitForAnyNotified(QDeadlineTimer deadline)
bool waitForNotified(QDeadlineTimer deadline, OVERLAPPED *overlapped)

Detailed Description

\inmoduleQtCore

The QWinOverlappedIoNotifier class makes it possible to use efficient overlapped (asynchronous) I/O notifications on Windows by using an I/O completion port.

Once you have obtained a file handle, you can use setHandle() to get notifications for I/O operations. Whenever an I/O operation completes, the notified() signal is emitted which will pass the number of transferred bytes, the operation's error code and a pointer to the operation's OVERLAPPED object to the receiver.

Every handle that supports overlapped I/O can be used by QWinOverlappedIoNotifier. That includes file handles, TCP sockets and named pipes.

Note that you must not use ReadFileEx() and WriteFileEx() together with QWinOverlappedIoNotifier. They are not supported as they use a different I/O notification mechanism.

The hEvent member in the OVERLAPPED structure passed to ReadFile() or WriteFile() is ignored and can be used for other purposes.

Warning: This class is only available on Windows.

Due to peculiarities of the Windows I/O completion port API, users of QWinOverlappedIoNotifier must pay attention to the following restrictions:

  • File handles with a QWinOverlappedIoNotifer are assigned to an I/O completion port until the handle is closed. It is impossible to disassociate the file handle from the I/O completion port.
  • There can be only one QWinOverlappedIoNotifer per file handle. Creating another QWinOverlappedIoNotifier for that file, even with a duplicated handle, will fail.
  • Certain Windows API functions are unavailable for file handles that are assigned to an I/O completion port. This includes the functions ReadFileEx and WriteFileEx.

See also the remarks in the MSDN documentation for the CreateIoCompletionPort function.

Member Function Documentation

OVERLAPPED *QWinOverlappedIoNotifier::waitForAnyNotified(QDeadlineTimer deadline)

\internalWait synchronously for any notified signal.

The function returns a pointer to the OVERLAPPED object corresponding to the completed I/O operation. In case no I/O operation was completed during the msec timeout, this function returns a null pointer.

bool QWinOverlappedIoNotifier::waitForNotified(QDeadlineTimer deadline, OVERLAPPED *overlapped)

\internalWait synchronously for the notified signal.

The function returns true if the notified signal was emitted for the I/O operation that corresponds to the OVERLAPPED object.