Función NdisCoOidRequest (ndis.h)

Artículo
03/08/2023

La función NdisCoOidRequest reenvía una solicitud a los controladores CoNDIS de destino para consultar o establecer información especificada por OID del controlador de destino.

Sintaxis

NDIS_STATUS NdisCoOidRequest(
  [in]           NDIS_HANDLE       NdisBindingHandle,
  [in, optional] NDIS_HANDLE       NdisAfHandle,
  [in, optional] NDIS_HANDLE       NdisVcHandle,
  [in, optional] NDIS_HANDLE       NdisPartyHandle,
  [in, out]      PNDIS_OID_REQUEST OidRequest
);

Parámetros

[in] NdisBindingHandle

Identificador que devolvió la función NdisOpenAdapterEx que identifica el adaptador de destino para el enlace.

[in, optional] NdisAfHandle

Identificador que identifica la familia de direcciones (AF) que se comparte entre el cliente, el administrador de llamadas y el NDIS. Este identificador se obtuvo de la siguiente manera:

Si el autor de la llamada es un cliente que realiza una solicitud al administrador de llamadas, el cliente obtuvo originalmente este identificador de una llamada correcta a la Función NdisClOpenAddressFamilyEx .
Si el autor de la llamada es un administrador de llamadas independiente o un administrador de llamadas de miniporte (MCM) que realiza una solicitud a un cliente, el administrador de llamadas o MCM obtuvo originalmente este identificador como parámetro de entrada para su función ProtocolCmOpenAf .

Para realizar una solicitud desde un cliente o un administrador de llamadas independiente al controlador de miniporte subyacente, este parámetro debe ser NULL.

[in, optional] NdisVcHandle

Identificador que identifica la conexión virtual (VC) para la que el autor de la llamada solicita o establece información, si la solicitud es específica de VC. De lo contrario, si este parámetro es NULL, la solicitud no es específica de VC. Para cualquier solicitud específica de VC, el autor de la llamada obtuvo originalmente este identificador cuando creó la credencial verificable con la función NdisCoCreateVc o como parámetro de entrada para su función ProtocolCoCreateVc . Para una solicitud específica de VC dirigida al controlador de miniport subyacente, este identificador identifica la credencial verificable, mientras que NdisAfHandle y NdisPartyHandle son NULL.

[in, optional] NdisPartyHandle

Identificador que identifica a la entidad en un VC de varios puntos para el que el autor de la llamada solicita o establece información, si la solicitud es específica de la entidad. De lo contrario, si este parámetro es NULL, la solicitud no es específica de terceros. Para cualquier solicitud específica de la entidad, un cliente obtuvo originalmente este identificador de una llamada correcta a la función NdisClAddParty o a la función NdisClMakeCall o al administrador de llamadas obtuvo este identificador como parámetro de entrada para su función ProtocolCmAddParty . Si NdisAfHandle es NULL, NdisPartyHandle también es NULL.

[in, out] OidRequest

Puntero a una estructura de NDIS_OID_REQUEST que especifica la operación solicitada con un código OID_XXX determinado para consultar o establecer información.

Valor devuelto

El controlador de destino determina qué código NDIS_STATUS_XXXdevuelve NdisCoOidRequest , normalmente uno de los siguientes valores:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	La operación de solicitud se completó correctamente.
NDIS_STATUS_PENDING	La solicitud se controla de forma asincrónica y NDIS llamará al autor de la llamada. Función ProtocolCoOidRequestComplete cuando se completa la solicitud.
NDIS_STATUS_INVALID_OID	El código OID_XXX especificado en el miembro Oid de la estructura NDIS_OID_REQUEST en el parámetro OidRequest no es válido o no es compatible con el controlador subyacente.
NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT	El valor especificado en el miembro InformationBufferLength del búfer estructurado de NDIS_OID_REQUEST en OidRequest no coincide con los requisitos del código OID_XXX especificado. Si el búfer de información es demasiado pequeño, el miembro BytesNeeded de NDIS_OID_REQUEST contiene el valor correcto para InformationBufferLength, cuando devuelve NdisCoOidRequest .
NDIS_STATUS_INVALID_DATA	Los datos proporcionados en InformationBuffer en la estructura de NDIS_OID_REQUEST especificada no son válidos para el código OID_XXX especificado.
NDIS_STATUS_NOT_SUPPORTED o NDIS_STATUS_NOT_RECOGNIZED	El controlador subyacente no admite la operación solicitada.
NDIS_STATUS_RESOURCES	No se pudo satisfacer la solicitud debido a una escasez de recursos. Normalmente, este valor devuelto indica que un intento de asignar memoria no se realizó correctamente, pero no indica necesariamente que la misma solicitud, si se envía más adelante, producirá un error por el mismo motivo.
NDIS_STATUS_NOT_ACCEPTED	El controlador subyacente intentó la operación solicitada, normalmente una solicitud establecida, pero se produjo un error en la operación. Por ejemplo, un intento de establecer demasiadas direcciones de multidifusión podría hacer que NdisCoOidRequest devuelva este valor.
NDIS_STATUS_CLOSING o NDIS_STATUS_CLOSING_INDICATING	El controlador subyacente produjo un error en la operación solicitada porque hay una operación de cierre en curso.
NDIS_STATUS_RESET_IN_PROGRESS	El controlador de miniport subyacente no puede satisfacer la solicitud en este momento porque actualmente está restableciendo la NIC afectada. La función ProtocolStatusEx del autor de la llamada era o se llamará con NDIS_STATUS_RESET_START para indicar que un restablecimiento está en curso. Este valor devuelto no indica necesariamente que la misma solicitud, si se envía más adelante, producirá un error por el mismo motivo.
NDIS_STATUS_FAILURE	Este valor suele ser un valor predeterminado no específico que se devuelve cuando ninguno de los NDIS_STATUS_XXX más específicos hizo que el controlador subyacente generara un error en la solicitud.
NDIS_STATUS_REQUEST_ABORTED	El controlador de minipuerto detuvo el procesamiento de la solicitud. Por ejemplo, NDIS llama miniportador subyacente MiniportResetEx o Función MiniportCancelOidRequest .

Comentarios

Los clientes de CoNDIS y los administradores de llamadas independientes pueden llamar a la función NdisCoOidRequest para enviar una solicitud OID para consultar o establecer información especificada por OID en un controlador de destino. El controlador de destino puede ser otro controlador de protocolo CoNDIS o un controlador subyacente.

El autor de la llamada de NdisCoOidRequest debe asignar memoria suficiente para contener el búfer de información asociado al OID especificado. El autor de la llamada también debe asignar y configurar el búfer en OidRequest antes de llamar a NdisCoOidRequest. Ambos búferes se deben asignar desde un grupo no paginado porque el controlador de destino se puede ejecutar en IRQL generado mientras procesa la solicitud.

Algunos errores que devuelve NdisCoOidRequest son recuperables, incluidos los siguientes:

NDIS_STATUS_INVALID_OID
NDIS_STATUS_INVALID_LENGTH
NDIS_STATUS_BUFFER_TOO_SHORT
NDIS_STATUS_INVALID_DATA
NDIS_STATUS_RESOURCES
NDIS_STATUS_RESET_IN_PROGRESS

Es decir, un controlador puede modificar el paquete en OidRequest adecuadamente para corregir el código OID_XXX o el tamaño o el contenido del búfer en InformationBuffer y volver a enviar el paquete de solicitud a NdisCoOidRequest. Es posible que se cumpla el mismo paquete cuando el controlador lo vuelva a enviar a NdisCoOidRequest si la llamada original indica un restablecimiento en curso o que una escasez de recursos, que podría ser temporal, impedía que se llevara a cabo esa solicitud.

Según el valor del parámetro NdisAfHandle , los clientes y los administradores de llamadas independientes llaman a NdisCoOidRequest para comunicarse entre sí o con el controlador de miniport subyacente orientado a la conexión.

Si un controlador pasa NULL para NdisVcHandle, la solicitud es global por naturaleza, si la solicitud se dirige al cliente, al administrador de llamadas o al controlador de miniporte. Por ejemplo, si el autor de la llamada proporciona un valor distinto de NULL para NdisVcHandle, una solicitud de OID de OID_GEN_CO_RCV_CRC_ERROR a un controlador de miniporte orientado a la conexión subyacente devuelve el número de errores de comprobación de redundancia cíclica (CRC) que se encontraron para un VC determinado. Para la misma solicitud con NULL para NdisVcHandle, el controlador de minipuerto subyacente devuelve el número total de errores CRC que se encontraron para todas las máquinas virtuales.

Los clientes y los administradores de llamadas independientes deben llamar a la función NdisOidRequest para todos los OID que no están orientados a la conexión, como los que se devuelven en una consulta de OID_GEN_SUPPORTED_LIST , que se emite normalmente durante la inicialización después de que el controlador de protocolo se haya enlazado al controlador NIC subyacente.

Si NdisCoOidRequest devuelve NDIS_STATUS_PENDING, la solicitud se controla de forma asincrónica y NDIS llamará al controlador. Función ProtocolCoOidRequestComplete cuando se completa la solicitud. Si NdisCoOidRequest devuelve cualquier otro estado, la solicitud se completa cuando devuelve NdisCoOidRequest y NDIS no llama a ProtocolCoOidRequestComplete.

Para obtener más información sobre los conjuntos de OID que se definen para su uso con NdisCoOidRequest y NdisOidRequest, consulte NDIS OIDs.

Solo los clientes y los administradores de llamadas independientes, que son controladores de protocolo, pueden llamar a NdisCoOidRequest. Los MCM llaman a la función NdisMCmOidRequest para comunicarse con sus clientes.

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Escritorio
Encabezado	ndis.h (incluya Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	Irql_Connection_Function(ndis)