Función GetOverlappedResultEx (ioapiset.h)

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.

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

Vea también

CancelIo

ConnectNamedPipe

CreateEvent

DeviceIoControl

Obtener último error

GetOverlappedResult

OVERLAPPED

Entrada y salida superpuestas

ReadFile

Funciones de sincronización

TransactNamedPipe

WaitCommEvent

WriteFile