Función GetOverlappedResultEx (ioapiset.h)

Artículo
08/24/2023

Recupera los resultados de una operación superpuesta en el archivo especificado, canalización con nombre o dispositivo de comunicaciones dentro del intervalo de tiempo de espera especificado. El subproceso que realiza la llamada puede realizar una espera alertable.

Sintaxis

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Parámetros

[in] hFile

Identificador del archivo, canalización con nombre o dispositivo de comunicaciones. Este es el mismo identificador que se especificó cuando se inició la operación superpuesta mediante una llamada a la función ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl o WaitCommEvent .

[in] lpOverlapped

Puntero a una estructura SUPERPUESTA que se especificó cuando se inició la operación superpuesta.

[out] lpNumberOfBytesTransferred

Puntero a una variable que recibe el número de bytes transferidos realmente por una operación de lectura o escritura. Para una operación TransactNamedPipe , este es el número de bytes leídos de la canalización. Para una operación DeviceIoControl , este es el número de bytes de datos de salida devueltos por el controlador de dispositivo. Para una operación ConnectNamedPipe o WaitCommEvent , este valor no está definido.

[in] dwMilliseconds

El intervalo de tiempo de espera en milisegundos.

Si dwMilliseconds es cero y la operación sigue en curso, la función devuelve inmediatamente y la función GetLastError devuelve ERROR_IO_INCOMPLETE.

Si dwMilliseconds es distinto de cero y la operación sigue en curso, la función espera hasta que se señaliza el objeto, se pone en cola una rutina de finalización de E/S o APC, o el intervalo transcurre antes de volver. Use GetLastError para obtener información de error extendida.

Si dwMilliseconds es INFINITE, la función solo devuelve cuando se señala el objeto o se pone en cola una rutina de finalización de E/S o APC.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 y Windows Server 2008 R2: El valor dwMilliseconds incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el tiempo de espera continúa contando mientras el equipo está inactivo.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 y Windows Server 2016: El valor dwMilliseconds no incluye el tiempo invertido en estados de bajo consumo. Por ejemplo, el tiempo de espera no continúa contando hacia abajo mientras el equipo está dormido.

[in] bAlertable

Si este parámetro es TRUE y el subproceso que realiza la llamada está en estado de espera, la función devuelve cuando el sistema pone en cola una rutina de finalización de E/S o APC. A continuación, el subproceso que realiza la llamada ejecuta la rutina o función. De lo contrario, la función no devuelve y no se ejecuta la rutina de finalización o la función de APC.

Una rutina de finalización se pone en cola cuando se ha completado la función ReadFileEx o WriteFileEx en la que se especificó. La función devuelve y solo se llama a la rutina de finalización si bAlertable es TRUE y el subproceso que realiza la llamada es el subproceso que inició la operación de lectura o escritura. Una instancia de APC se pone en cola cuando se llama a QueueUserAPC.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError. Entre los códigos de error comunes se incluyen los siguientes:

Si dwMilliseconds es cero y la operación sigue en curso, GetLastError devuelve ERROR_IO_INCOMPLETE.
Si dwMilliseconds es distinto de cero y se pone en cola una rutina de finalización de E/S o APC, GetLastError devuelve WAIT_IO_COMPLETION.
Si dwMilliseconds es distinto de cero y transcurre el intervalo de tiempo de espera especificado, GetLastError devuelve WAIT_TIMEOUT.

Comentarios

La función GetOverlappedResultEx difiere de GetOverlappedResult de las siguientes maneras: El parámetro dwMilliseconds puede especificar un intervalo de tiempo de espera para la operación y el parámetro bAlertable puede especificar que el subproceso que realiza la llamada debe realizar una espera alertable.

Los resultados notificados por la función GetOverlappedResultEx son los de la última operación superpuesta del identificador especificado a la que se proporcionó la estructura SUPERPUESTA especificada y para la que estaban pendientes los resultados de la operación. Se indica una operación pendiente cuando la función que inició la operación devuelve FALSE y la función GetLastError devuelve ERROR_IO_PENDING. Cuando hay una operación de E/S pendiente, la función que inició la operación restablece el miembro hEvent de la estructura SUPERPUESTA al estado no asignado. Después, cuando se haya completado la operación pendiente, el sistema establece el objeto de evento en el estado señalado.

Especifique un objeto de evento de restablecimiento manual en la estructura SUPERPUESTA . Si se usa un objeto de evento de restablecimiento automático, el identificador de eventos no se debe especificar en ninguna otra operación de espera en el intervalo entre iniciar la operación superpuesta y la llamada a GetOverlappedResultEx. Por ejemplo, el objeto de evento se especifica a veces en una de las funciones de espera para esperar la finalización de la operación. Cuando se devuelve la función wait, el sistema establece el estado de un evento de restablecimiento automático en no asignado y una llamada posterior a GetOverlappedResultEx con el parámetro dwMilliseconds establecido en INFINITE hace que la función se bloquee indefinidamente.

Si el miembro hEvent de la estructura SUPERPUESTA es NULL, el sistema usa el estado del identificador hFile para indicar cuándo se ha completado la operación. No se recomienda el uso de identificadores de archivo, canalización con nombre o dispositivos de comunicaciones para este propósito. Es más seguro usar un objeto de evento debido a la confusión que puede producirse cuando se realizan varias operaciones superpuestas simultáneas en el mismo archivo, canalización con nombre o dispositivo de comunicaciones. En esta situación, no hay ninguna manera de saber qué operación provocó que se señalizara el estado del objeto.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8 [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2012 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	ioapiset.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll