fonction WinUsb_GetOverlappedResult (winusb.h)

Article
03/06/2024

La fonction WinUsb_GetOverlappedResult récupère les résultats d’une opération qui se chevauche sur le fichier spécifié.

Syntaxe

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

Paramètres

[in] InterfaceHandle

Poignée opaque à la première interface de l’appareil, qui est retournée par WinUsb_Initialize.

[in] lpOverlapped

Pointeur vers une structure CHEVAUCHÉE qui a été spécifiée lors du démarrage de l’opération qui se chevauche.

[out] lpNumberOfBytesTransferred

Pointeur vers une variable qui reçoit le nombre d’octets réellement transférés par une opération de lecture ou d’écriture.

[in] bWait

Si ce paramètre a la valeur TRUE, la fonction ne retourne pas tant que l’opération n’est pas terminée. Si ce paramètre a la valeur FALSE et que l’opération est toujours en attente, la fonction retourne FALSE et la fonction GetLastError retourne ERROR_IO_INCOMPLETE.

Valeur retournée

Si la fonction réussit, la valeur de retour est n’importe quel nombre autre que zéro. Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Cette fonction est semblable à la routine de l’API Win32, GetOverlappedResult, à une différence près : au lieu de passer un handle de fichier retourné à partir de CreateFile, l’appelant passe un handle d’interface retourné par WinUsb_Initialize. L’appelant peut utiliser l’une ou l’autre routine d’API si le handle approprié est passé. La fonction WinUsb_GetOverlappedResult extrait le handle de fichier du handle d’interface, puis appelle GetOverlappedResult.

Les résultats qui sont signalés par la fonction WinUsb_GetOverlappedResult sont ceux de la dernière opération de chevauchement du handle spécifié à laquelle la structure CHEVAUCHEMENT SPÉCIFIÉE a été fournie et pour laquelle les résultats de l’opération étaient en attente. Une opération en attente est indiquée lorsque la fonction qui a démarré l’opération retourne FALSE et que la routine GetLastError retourne ERROR_IO_PENDING. Lorsqu’une opération d’E/S est en attente, la fonction qui a démarré l’opération réinitialise le membre hEvent de la structure OVERLAPPED à l’état non signé. Une fois l’opération en attente terminée, le système définit l’objet événement à l’état signalé.

L’appelant peut spécifier qu’un objet d’événement est réinitialisé manuellement dans la structure CHEVAUCHEMENT . Si un objet d’événement de réinitialisation automatique est utilisé, le handle d’événement ne doit pas être spécifié dans une autre opération d’attente dans l’intervalle entre le démarrage de l’opération qui se chevauche et l’appel à WinUsb_GetOverlappedResult. Par exemple, l’objet événement est parfois spécifié dans l’une des routines d’attente pour attendre que l’opération soit terminée. Lorsque la routine d’attente retourne, le système définit l’état d’un événement de réinitialisation automatique sur non signé, et un appel successif à WinUsb_GetOverlappedResult avec le paramètre bWait défini sur TRUE entraîne le blocage indéfini de la fonction.

Si le paramètre bWait a la valeur TRUE, WinUsb_GetOverlappedResult détermine si l’opération en attente est terminée en attendant que l’objet d’événement soit à l’état signalé.

Si le membre hEvent de la structure CHEVAUCHEMENT ESTNULL, le système utilise l’état du handle de fichier pour signaler quand l’opération est terminée. N’utilisez pas de handles de fichiers à cet effet. Il est préférable d’utiliser un objet d’événement en raison de la confusion qui peut se produire lorsque plusieurs opérations simultanées se chevauchent sur le même fichier. Dans ce cas, vous ne pouvez pas savoir quelle opération a provoqué le signal de l’état de l’objet.