GetOverlappedResult

Devuelve el resultado de una operación superpuesta (overlapped) en un fichero especificado, tubería con nombre o dispositivo de comunicaciones.

Windows 95: esta función funciona sólo en dispositivos serie o en ficheros abiertos usando la función DeviceIoControl.

Sintaxis

BOOL GetOverlappedResult(
    HANDLE hFile,                        // manipulador de fichero, tubería o dispositivo de comunicaciones
    LPOVERLAPPED lpOverlapped,           // dirección de estructura overlapped
    LPDWORD lpNumberOfBytesTransferred,  // dirección de contador de bytes actual
    BOOL bWait                           // flag de espera
   );

Parámetros:

hFile: identifica el fichero, tubería con nombre o dispositivo de comunicaciones. Este es el mismo manipulador que fue especificado cuando se lanzó la operación superpuesta mediante la llamada a ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl o WaitCommEvent.

lpOverlapped: puntero a estructura OVERLAPPED que fue especificada cuando se lanzó la operación superpuesta.

lpNumberOfBytesTransferred: puntero a variable de 32 bits que recibirá el número de bytes que han sido transferidos por la operación de lectura o escritura. Para la operación TransactNamedPipe, este es el número de bytes que fueron leídos desde la tubería. Para una operación DeviceIoControl, este es el número de bytes de datos de salida devueltos por el driver del dispositivo. Para operaciones ConnectNamedPipe o WaitCommEvent, este valor no está definido.

bWait: especifica si la función debe esperar a que se complete una operación superpuesta pendiente. Si es TRUE, la función no regresa hasta que la operación haya sido completada. Si es FALSE y la operación permanece pendiente, la función regresa con FALSE y la función GetLastError devuelve ERROR_IO_INCOMPLETE.

Valor de retorno

Si la función tiene éxito, el valor de retorno es TRUE.

Si la función falla, el valor de retorno es FALSE. Para obtener información adicional sobre el error, llamar a GetLastError.

Observaciones

Los resultados devueltos por GetOverlappedResult corresponden a la última operación superpuesta del manipulador especificado para la estructura OVERLAPPED suministrada y para la que quedan resultados pendientes de la operación. Una operación pendiente se indica cuando la función que comenzó la operación devuelve FALSE, y la función GetLastError devuelve ERROR_IO_PENDING. Cuando una operación I/O está pendiente, la función que empezó la operación resetea el miembro hEvent de la estructura OVERLAPPED al estado "no señalizado". Entonces, cuando la operación pendiente ha sido completada, el sistema pone el objeto evento al estado "señalizado".

Si el parámetro bWait es TRUE, GetOverlappedResult determina si la operación pendiente ha sido completada esperando a que el objeto evento pase al estado "señalizado".

Si el miembro hEvent de la estructura OVERLAPPED es NULL, el sistema usa el estado del manipulador hFile para señalar cuando se ha completado la operación. El uso de manipuladores de fichero, tubería con nombre o dispositivo de comunicaciones para este propósito esta desaconsejado. Es más seguro usar el objeto evento porque puede ocurrir una confusión cuando se realizan múltiples operaciones superpuestas simultaneas en el mismo fichero, tubería o dispositivo de comunicaciones. En esta situación, no hay forma se saber cual de las operaciones ha provocado que el estado del objeto se haya señalizado.

Se debe especificar un objeto evento de reset manual en la estructura OVERLAPPED. Si se usa un objeto evento de reset automáticamente, el manipulador de evento no debe ser especificado en ninguna otra operación de espera dentro del intervalo entre el comienzo de la operación superpuesta y la llamada a GetOverlappedResult. Por ejemplo, el objeto evento se especifica algunas veces en una de las funciones de espera para esperar a que se complete la operación. Cuando la función de espera regresa, el sistema pone el estado del evento de reset automático a "no señalizado", y subsiguientes llamadas a GetOverlappedResult con el parámetro bWait con valor TRUE hacen que la función quede bloqueada indefinidamente.