función FILTER_SYNCHRONOUS_OID_REQUEST (ndis.h)

NDIS llama a la función FilterSynchronousOidRequest de un controlador de filtro para obtener una vista previa de una solicitud de OID sincrónica antes de que la solicitud se dé al controlador de miniport subyacente.

Esta función se admite en NDIS 6.81 y versiones posteriores.

Sintaxis

NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
            NDIS_HANDLE      FilterModuleContext,
  [in, out] NDIS_OID_REQUEST *OidRequest,
  [out]     PVOID            *CallContext
);

Parámetros

FilterModuleContext

Identificador del área de contexto del módulo de filtro que es el destino de esta solicitud. El controlador de filtro creó e inicializó este área de contexto en la función FilterAttach .

[in, out] OidRequest

Puntero a una estructura NDIS_OID_REQUEST que especifica la operación solicitada.

[out] CallContext

Ranura de almacenamiento de tamaño PVOID para que el controlador de filtro comparta el estado entre sus controladores FilterSynchronousOidRequest y FilterSynchronousOidRequestComplete . NDIS garantiza que esto apunta inicialmente a un valor cero. Vea la sección Comentarios para obtener más información.

Valor devuelto

Esta función devuelve uno de los siguientes códigos de NDIS_STATUS adecuados:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	Permita que la solicitud de OID continúe propagando al controlador de minipuerto. Los controladores de filtro deben devolver este código de estado para cualquier tipo no reconocido de OID.
NDIS_STATUS_ALREADY_COMPLETE	Detenga la propagación de la solicitud de OID y, en su lugar, vuelva al autor de la llamada con el estado NDIS_STATUS_SUCCESS.
NDIS_STATUS_BUFFER_TOO_SHORT NDIS_STATUS_INVALID_LENGTH NDIS_STATUS_INVALID_DATA	Igual que FilterDirectOidRequest.
NDIS_STATUS_RESOURCES	Igual que FilterDirectOidRequest, pero con precaución de que las solicitudes de OID sincrónicas deben completarse rápidamente, por lo que los controladores de filtro normalmente deben evitar asignar recursos.
NDIS_STATUS_NOT_SUPPORTED	Los controladores de filtro no deben devolver este código simplemente porque no se reconoce el OID. Los controladores de filtro solo pueden devolver esto si el filtro reconoce la operación, pero no lo puede realizar por algún motivo.

Comentarios

FilterSynchronousOidRequest es una función opcional. Si no es necesario que un controlador de filtro observe o modifique las solicitudes de OID sincrónicas enviadas al controlador de miniporte, el controlador de filtro debe establecer el punto de entrada de esta función en NULL cuando llama a NdisFRegisterFilterDriver.

NDIS llama a la función FilterSynchronousOidRequest del controlador de filtro para procesar solicitudes de OID sincrónicas que se originan mediante controladores excesivos. Los controladores de filtro pueden leer o modificar algunos campos de la estructura NDIS_OID_REQUEST de la siguiente manera:

Campo	Filtrado del acceso
Encabezado	Solo lectura
RequestType	Lectura/escritura
PortNumber	Lectura/escritura
Tiempo de espera	No acceder
RequestId	No acceder
RequestHandle	Lectura/escritura
DATA	Lectura/escritura
NdisReserved	No acceder
MiniportReserved	No acceder
SourceReserved	No acceder
SupportedRevision	Lectura/escritura
Reserved1, Reserved2	No acceder
SwitchId	Lectura/escritura
VPortId	Lectura/escritura
Marcas	Lectura/escritura

Además de modificar la estructura de NDIS_OID_REQUEST , los controladores de filtro pueden controlar la solicitud mediante el código de retorno de FilterSynchronousOidRequest:

• NDIS_STATUS_SUCCESS: el OID continúa propaguándose hasta el controlador de minipuerto.
• NDIS_STATUS_ALREADY_COMPLETE: el OID se completa inmediatamente de nuevo a los controladores que se sobreponen, sin propagarse primero al controlador de minipuerto. La solicitud de OID se completa en el controlador de sobreaprovisionamiento con NDIS_STATUS_SUCCESS.
• Cualquier otro código de estado: el OID se vuelve a completar inmediatamente en los controladores que se sobreponen, sin propagarse primero al controlador de minipuerto. La solicitud de OID se completa en el controlador de sobreasignación con el código de estado devuelto por el controlador de filtro.

Si el controlador de filtro también registra un controlador FilterSynchronousOidRequestComplete , NDIS garantiza que se llamará al controlador FilterSynchronousOidRequestComplete si y solo si el controlador FilterSynchronousOidRequest devuelve NDIS_STATUS_SUCCESS.

El controlador FilterSynchronousOidRequest puede escribir cualquier valor de tamaño PVOID en *CallContext y se devolverá el mismo valor al controlador de filtro FilterSynchronousOidRequestComplete cuando se complete la solicitud OID. El controlador de filtro puede usarlo para transportar el estado entre los dos controladores. Dado que el controlador FilterSynchronousOidRequestComplete solo se invoca si el controlador FilterSynchronousOidRequest devuelve NDIS_STATUS_SUCCESS, no hay ninguna razón para escribir un valor en *CallContext al devolver cualquier otro código. Del mismo modo, no hay ninguna razón para escribir un valor en *CallContext si el controlador de filtro no proporciona un controlador FilterSynchronousOidRequestComplete .

Los controladores de filtro no deben devolver NDIS_STATUS_PENDING desde un controlador FilterSynchronousOidRequest . Las solicitudes de OID sincrónicas no se pueden suspender ni cancelar.

Se espera que los controladores de filtro vuelvan de su controlador FilterSynchronousOidRequest rápidamente, sin bloquear, esperar ni dormir. Las solicitudes de OID sincrónicas solo se usan para las operaciones de baja latencia y los controladores de filtro deben esforzarse por continuar o completarlas dentro de varios milisegundos. NDIS no serializa las solicitudes de OID sincrónicas entre sí, contra otras solicitudes de OID o con FilterPause. Es responsabilidad del controlador de filtro implementar cualquier sincronización necesaria.

NDIS serializa las solicitudes de OID sincrónicas en FilterDetach: NDIS garantiza que ninguna solicitud OID sincrónica estará activa una vez que se invoque FilterDetach .

Los controladores de filtro no deben llamar a NdisAllocateCloneOidRequest o NdisCancelOidRequest en una solicitud de OID sincrónica. Los controladores de filtro no deben llamar a NdisFSynchronousOidRequest en una solicitud de OID que se recibe a través de un controlador FilterSynchronousOidRequest .

Si un controlador de filtro genera el IRQL en su controlador FilterSynchronousOidRequest , debe restaurar irQL a su nivel inicial antes de volver de su controlador FilterSynchronousOidRequest .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10, versión 1709
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL

Consulte también

FilterSynchronousOidRequestComplete

NdisFSynchronousOidRequest

Interfaz de solicitud de OID sincrónica en NDIS 6.80