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

  • Artículo

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El método RetrieveNextRequest recupera la siguiente solicitud de E/S de una cola de E/S.

Sintaxis

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

Parámetros

[out] ppRequest

Puntero a un búfer que recibe un puntero a la interfaz IWDFIoRequest del siguiente objeto de solicitud, o recibe NULL si la cola está vacía o si no se encuentra la siguiente solicitud.

Valor devuelto

RetrieveNextRequest devuelve uno de los siguientes valores:

Código devuelto Descripción
S_OK
 La siguiente solicitud de E/S se recuperó correctamente de la cola de E/S.
HRESULT_FROM_NT (STATUS_WDF_PAUSED)
 La cola no envía solicitudes. Esta situación se produce si el dispositivo se somete a una transición de estado de energía y todas las colas dejan de enviar solicitudes o si el controlador llamó explícitamente A IWDFIoQueue::Stop para detener el envío de solicitudes. Esta situación también puede producirse si el controlador intenta quitar una solicitud de una cola manual administrada por energía y que está apagada o si la cola está en pausa.
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)
 No había solicitudes en la cola.
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)
 La llamada se realizó para recuperar la solicitud de una cola paralela.
 

RetrieveNextRequest también podría devolver otros valores HRESULT.

Comentarios

Si un controlador configura una cola de E/S para el envío manual de solicitudes de E/S, el controlador puede llamar al método RetrieveNextRequest para obtener la siguiente solicitud de la cola. Para obtener más información sobre cómo enviar manualmente solicitudes de E/S, consulte Configuración del modo de distribución para una cola de E/S.

Si un controlador configura una cola de E/S para el envío secuencial de solicitudes de E/S, el controlador todavía puede llamar al método RetrieveNextRequest para obtener la siguiente solicitud de la cola sin recibir un error. Aunque el marco permite al controlador llamar a RetrieveNextRequest para recuperar una solicitud de una cola secuencial, el controlador solo debe llamar a RetrieveNextRequest antes de que el controlador complete la solicitud actual. De lo contrario, si el controlador intenta llamar a RetrieveNextRequest después de que el controlador complete la solicitud actual, podría producirse una condición de carrera. Esta condición de carrera se produce entre el envío automático del marco de la siguiente solicitud de la cola secuencial y la llamada del controlador a RetrieveNextRequest para recuperar la siguiente solicitud.

Ejemplos

En el ejemplo de código siguiente, que procede del controlador de ejemplo de umdf_fx2 , se sondea la cola de solicitudes siempre que se puedan recuperar las solicitudes. El código comprueba primero si las solicitudes están asociadas a un objeto de archivo específico.

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);
}

Requisitos

Requisito Value
Finalización del soporte técnico No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino Escritorio
Versión mínima de UMDF 1.5
Encabezado wudfddi.h (incluya Wudfddi.h)
Archivo DLL WUDFx.dll

Consulte también

IWDFIoQueue

IWDFIoQueue::Stop

IWDFIoRequest