Структура OVERLAPPED (minwinbase.h)

Статья
03/05/2024

Содержит сведения, используемые в асинхронных (или перекрывающихся) входных и выходных данных (ввода-вывода).

Синтаксис

typedef struct _OVERLAPPED {
  ULONG_PTR Internal;
  ULONG_PTR InternalHigh;
  union {
    struct {
      DWORD Offset;
      DWORD OffsetHigh;
    } DUMMYSTRUCTNAME;
    PVOID Pointer;
  } DUMMYUNIONNAME;
  HANDLE    hEvent;
} OVERLAPPED, *LPOVERLAPPED;

Члены

Internal

Код состояния для запроса ввода-вывода. При выдаче запроса система задает этому участнику значение STATUS_PENDING , чтобы указать, что операция еще не запущена. После завершения запроса система задает этому участнику код состояния для завершенного запроса.

Внутренний элемент изначально был зарезервирован для использования системой, и его поведение может измениться.

InternalHigh

Количество байтов, переданных для запроса ввода-вывода. Система задает этот член, если запрос выполнен без ошибок.

Элемент InternalHigh изначально был зарезервирован для использования системой, и его поведение может измениться.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Offset

Часть файла с низким порядком, с которой запускается запрос ввода-вывода, как указано пользователем.

Этот элемент является ненулевым только при выполнении запросов ввода-вывода на ищущем устройстве, которое поддерживает концепцию смещения (также называемого механизмом указателя на файл), например файл. В противном случае этот элемент должен быть равен нулю.

Дополнительные сведения см. в разделе Примечания.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.OffsetHigh

Высокоупорядоченная часть позиции файла, с которой запускается запрос ввода-вывода, как указано пользователем.

Дополнительные сведения см. в разделе Примечания.

DUMMYUNIONNAME.Pointer

Зарезервировано для использования системой; не используйте после инициализации равным нулю.

hEvent

Дескриптор события, которое будет задано системой в состояние сигнала после завершения операции. Пользователь должен инициализировать этот элемент до нуля или допустимого дескриптора события с помощью функции CreateEvent перед передачей этой структуры в любые перекрывающиеся функции. Затем это событие можно использовать для синхронизации одновременных запросов ввода-вывода для устройства. Дополнительные сведения см. в разделе Примечания.

Такие функции, как ReadFile и WriteFile , устанавливают для этого дескриптора состояние без знака перед началом операции ввода-вывода. После завершения операции дескриптор получает состояние сигнала.

Такие функции, как GetOverlappedResult и функции ожидания синхронизации, сбрасывают события автоматического сброса в состояние без знака. Поэтому следует использовать событие сброса вручную; Если вы используете событие автоматического сброса, приложение может перестать отвечать на запросы, если вы дождетесь завершения операции и вызовите Метод GetOverlappedResult с параметром bWait, равным TRUE.

Все неиспользуемые элементы этой структуры всегда должны быть инициализированы до нуля, прежде чем структура будет использоваться в вызове функции. В противном случае функция может завершиться ошибкой и возвратить ERROR_INVALID_PARAMETER.

Элементы Offset и OffsetHigh вместе представляют 64-разрядную позицию файла. Это смещение в байтах от начала файла или файлового устройства, которое задается пользователем; система не будет изменять эти значения. Вызывающий процесс должен задать этот элемент перед передачей структуры OVERLAPPED в функции, использующие смещение , такие как ReadFile или WriteFile (и связанные функции).

Макрос HasOverlappedIoCompleted можно использовать для проверка, завершена ли асинхронная операция ввода-вывода, если getOverlappedResult слишком громоздки для вашего приложения.

Для отмены асинхронной операции ввода-вывода можно использовать функцию CancelIo .

Распространенной ошибкой является повторное использование структуры OVERLAPPED до завершения предыдущей асинхронной операции. Для каждого запроса следует использовать отдельную структуру. Необходимо также создать объект события для каждого потока, обрабатывающего данные. При хранении дескрипторов событий в массиве можно легко дождаться передачи сигналов обо всех событиях с помощью функции WaitForMultipleObjects .

Дополнительные сведения и потенциальные ошибки использования асинхронных операций ввода-вывода см. в разделе CreateFile, ReadFile, WriteFile и связанных функций.

Общие сведения о синхронизации и концептуальные сведения об использовании OVERLAPPED см. в разделе Синхронизация и перекрытие входных и выходных данных и связанных с ними разделах.

Общие сведения о синхронных и асинхронных операциях ввода-вывода для файловых операций ввода-вывода см. в статье Синхронные и асинхронные операции ввода-вывода.

Примеры

Пример см. в разделе Сервер именованного канала с использованием перекрывающихся операций ввода-вывода.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Верхняя часть	minwinbase.h (включает Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)