Méthode IWDFIoQueue ::RetrieveNextRequest (wudfddi.h)

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode RetrieveNextRequest récupère la requête d’E/S suivante à partir d’une file d’attente d’E/S.

Syntaxe

HRESULT RetrieveNextRequest(
  [out] IWDFIoRequest **ppRequest
);

Paramètres

[out] ppRequest

Pointeur vers une mémoire tampon qui reçoit un pointeur vers l’interface IWDFIoRequest pour l’objet de requête suivant, ou reçoit NULL si la file d’attente est vide ou si la requête suivante est introuvable.

Valeur retournée

RetrieveNextRequest retourne l’une des valeurs suivantes :

Code de retour	Description
S_OK	La demande d’E/S suivante a été récupérée à partir de la file d’attente d’E/S.
HRESULT_FROM_NT (STATUS_WDF_PAUSED)	La file d’attente ne distribue pas les demandes. Cette situation se produit si l’appareil subit une transition d’état d’alimentation et que toutes les files d’attente sont arrêtées de distribuer des demandes ou si le pilote a explicitement appelé IWDFIoQueue ::Stop pour arrêter la distribution des demandes. Cette situation peut également se produire si le pilote tente de supprimer une demande d’une file d’attente manuelle qui est gérée par l’alimentation et qui est hors tension ou si la file d’attente est suspendue.
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)	Aucune demande n’était dans la file d’attente.
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	L’appel a été effectué pour récupérer la demande à partir d’une file d’attente parallèle.

RetrieveNextRequest peut également retourner d’autres valeurs HRESULT.

Remarques

Si un pilote configure une file d’attente d’E/S pour la distribution manuelle des demandes d’E/S, il peut appeler la méthode RetrieveNextRequest pour obtenir la requête suivante à partir de la file d’attente. Pour plus d’informations sur la distribution manuelle des demandes d’E/S, consultez Configuration du mode de distribution pour une file d’attente d’E/S.

Si un pilote configure une file d’attente d’E/S pour la distribution séquentielle des demandes d’E/S, il peut toujours appeler la méthode RetrieveNextRequest pour obtenir la requête suivante de la file d’attente sans recevoir d’erreur. Bien que le framework autorise le pilote à appeler RetrieveNextRequest pour récupérer une requête à partir d’une file d’attente séquentielle, le pilote doit uniquement appeler RetrieveNextRequest avant que le pilote termine la requête actuelle. Sinon, si le pilote tente d’appeler RetrieveNextRequest une fois que le pilote a terminé la requête actuelle, une condition de course peut se produire. Cette condition de concurrence se produit entre la distribution automatique par l’infrastructure de la requête suivante à partir de la file d’attente séquentielle et l’appel du pilote à RetrieveNextRequest pour récupérer la requête suivante.

Exemples

L’exemple de code suivant, qui provient de l’exemple de pilote umdf_fx2 , interroge la file d’attente à la recherche de requêtes tant que les demandes peuvent être récupérées. Le code vérifie d’abord si les requêtes sont associées à un objet fichier spécifique.

VOID
CMyDevice::ServiceSwitchChangeQueue(
    __in SWITCH_STATE NewState,
    __in HRESULT CompletionStatus,
    __in_opt IWDFFile *SpecificFile
    )
{
    IWDFIoRequest *fxRequest;
    HRESULT enumHr = S_OK;
    do {
        HRESULT hr;
        //
        // Get the next request.
        //
        if (NULL != SpecificFile) {
        enumHr = m_SwitchChangeQueue->RetrieveNextRequestByFileObject(
                                        SpecificFile,
                                        &fxRequest
                                        );
        }
        else {
            enumHr = m_SwitchChangeQueue->RetrieveNextRequest(&fxRequest);
        }
        //
        // If a request was retrieved, complete it.
        //
        if (S_OK == enumHr) {
            if (S_OK == CompletionStatus) {
                IWDFMemory *fxMemory;
                //
                // Copy the result to the request buffer.
                //
                fxRequest->GetOutputMemory(&fxMemory);
                hr = fxMemory->CopyFromBuffer(0, 
                                              &NewState, 
                                              sizeof(SWITCH_STATE));
                                              fxMemory->Release();
            }
            else {
                 hr = CompletionStatus;
            }
            //
            // Complete the request with the copy or 
            // completion status.
            //
            if (S_OK == hr) {
                fxRequest->CompleteWithInformation(hr, 
                                                   sizeof(SWITCH_STATE));
            }
            else {
                fxRequest->Complete(hr);
            }
            fxRequest->Release();
        }
    }
    while (S_OK == enumHr);
}

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1.5
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IWDFIoQueue

IWDFIoQueue ::Stop

IWDFIoRequest

Partager via