función WinUsb_GetOverlappedResult (winusb.h)

Artículo
08/27/2023

La función WinUsb_GetOverlappedResult recupera los resultados de una operación superpuesta en el archivo especificado.

Sintaxis

BOOL WinUsb_GetOverlappedResult(
  [in]  WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]  LPOVERLAPPED            lpOverlapped,
  [out] LPDWORD                 lpNumberOfBytesTransferred,
  [in]  BOOL                    bWait
);

Parámetros

[in] InterfaceHandle

Identificador opaco de la primera interfaz del dispositivo, que devuelve WinUsb_Initialize.

[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.

[in] bWait

Si este parámetro es TRUE, la función no devuelve hasta que se haya completado la operación. Si este parámetro es FALSE y la operación sigue pendiente, la función devuelve FALSE y la función GetLastError devuelve ERROR_IO_INCOMPLETE.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es cualquier número 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.

Comentarios

Esta función es como la rutina de la API de Win32, GetOverlappedResult, con una diferencia, en lugar de pasar un identificador de archivo que se devuelve desde CreateFile, el autor de la llamada pasa un identificador de interfaz que se devuelve de WinUsb_Initialize. El autor de la llamada puede usar cualquiera de las rutinas de API, si se pasa el identificador adecuado. La función WinUsb_GetOverlappedResult extrae el identificador de archivo del identificador de interfaz y, a continuación, llama a GetOverlappedResult.

Los resultados notificados por la función WinUsb_GetOverlappedResult 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 rutina 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.

El autor de la llamada puede especificar que un objeto de evento se restablece manualmente en la estructura SUPERPUESTA . Si se usa un objeto de evento de restablecimiento automático, el identificador de eventos no debe especificarse en ninguna otra operación de espera en el intervalo entre iniciar la operación superpuesta y la llamada a WinUsb_GetOverlappedResult. Por ejemplo, el objeto de evento se especifica a veces en una de las rutinas de espera para esperar a que se complete la operación. Cuando la rutina de espera vuelve, el sistema establece el estado de un evento de restablecimiento automático en no asignado y una llamada sucesiva a WinUsb_GetOverlappedResult con el parámetro bWait establecido en TRUE hace que la función se bloquee indefinidamente.

Si el parámetro bWait es TRUE, WinUsb_GetOverlappedResult determina si la operación pendiente se ha completado esperando a que el objeto de evento esté en estado señalado.

Si el miembro hEvent de la estructura SUPERPUESTA es NULL, el sistema usa el estado del identificador de archivo para indicar cuándo se ha completado la operación. No use identificadores de archivo para este propósito. Es mejor 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. En esta situación, no se puede saber qué operación provocó que se señalizara el estado del objeto.