Función NdisRegisterProtocol (ndis.h)

Artículo
08/07/2023

Nota NDIS 5. x está en desuso y se sustituye por NDIS 6. x. Para el nuevo desarrollo de controladores NDIS, consulte Controladores de red a partir de Windows Vista. Para obtener información sobre cómo migrar NDIS 5. Controladores x a NDIS 6. x, consulte Migración de controladores NDIS 5.x a NDIS 6.0.

NdisRegisterProtocol registra los puntos de entrada ProtocolXxx del controlador NDIS y el nombre con la biblioteca NDIS cuando se inicializa el controlador.

Sintaxis

void NdisRegisterProtocol(
  [out] PNDIS_STATUS                   Status,
  [out] PNDIS_HANDLE                   NdisProtocolHandle,
  [in]  PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
  [in]  UINT                           CharacteristicsLength
);

Parámetros

[out] Status

Puntero a una variable proporcionada por el autor de la llamada que puede ser uno de los siguientes valores devueltos de esta función:

NDIS_STATUS_SUCCESS
La biblioteca NDIS registró el autor de la llamada como controlador de protocolo.
NDIS_STATUS_BAD_CHARACTERISTICS
CharacteristicsLength es demasiado pequeño para majorNdisVersion especificado en el búfer en ProtocolCharacteristics.
NDIS_STATUS_BAD_VERSION
MajorNdisVersion especificado en el búfer en ProtocolCharacteristics no es válido.
NDIS_STATUS_RESOURCES
Una escasez de recursos, posiblemente memoria, impidió que la biblioteca NDIS registrara el autor de la llamada.

[out] NdisProtocolHandle

Puntero a una variable proporcionada por el autor de la llamada en la que esta función devuelve un identificador que representa el controlador registrado.

[in] ProtocolCharacteristics

Puntero a una estructura de NDIS_PROTOCOL_CHARACTERISTICS configurada por el autor de la llamada. La estructura de ProtocolCharacteristics se define de la siguiente manera:

        typedef struct _NDIS_PROTOCOL_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            OPEN_ADAPTER_COMPLETE_HANDLER OpenAdapterCompleteHandler;
            CLOSE_ADAPTER_COMPLETE_HANDLER CloseAdapterCompleteHandler;
            SEND_COMPLETE_HANDLER SendCompleteHandler;
            TRANSFER_DATA_COMPLETE_HANDLER TransferDataCompleteHandler;
            RESET_COMPLETE_HANDLER ResetCompleteHandler;
            REQUEST_COMPLETE_HANDLER RequestCompleteHandler;
            RECEIVE_HANDLER ReceiveHandler;
            RECEIVE_COMPLETE_HANDLER ReceiveCompleteHandler;
            STATUS_HANDLER StatusHandler;
            STATUS_COMPLETE_HANDLER StatusCompleteHandler;
            NDIS_STRING Name;
        //
        // MajorNdisVersion must be set to 0x04 or 0x05
        // with any of the following members.
        //
            RECEIVE_PACKET_HANDLER ReceivePacketHandler;
            BIND_HANDLER BindAdapterHandler;
            UNBIND_HANDLER UnbindAdapterHandler;
            PNP_EVENT_HANDLER PnPEventHandler;
            UNLOAD_PROTOCOL_HANDLER UnloadHandler;
        //
        // MajorNdisVersion must be set to 0x05 
        // with any of the following members.
        //
            CO_SEND_COMPLETE_HANDLER CoSendCompleteHandler;
            CO_STATUS_HANDLER CoStatusHandler;
            CO_RECEIVE_PACKET_HANDLER CoReceivePacketHandler;
            CO_AF_REGISTER_NOTIFY_HANDLER CoAfRegisterNotifyHandler;
        } NDIS_PROTOCOL_CHARACTERISTICS, *PNDIS_PROTOCOL_CHARACTERISTICS;

El controlador debe inicializar esta estructura con ceros antes de configurar los siguientes miembros:

MajorNdisVersion
Especifica la versión principal de la biblioteca NDIS que usa el controlador. El valor actual es 0x05, aunque la biblioteca NDIS sigue admitiendo los controladores existentes desarrollados para NDIS V4.0. NDIS ya no admite protocolos V3.0.
MinorNdisVersion
Especifica la versión secundaria de NDIS. El valor actual es 0x00.
Reserved
Este miembro está reservado para uso del sistema.
OpenAdapterCompleteHandler
Especifica el punto de entrada de la función ProtocolOpenAdapterComplete del autor de la llamada.
CloseAdapterCompleteHandler
Especifica el punto de entrada de la función ProtocolCloseAdapterComplete del autor de la llamada.
SendCompleteHandler
Especifica el punto de entrada de la función ProtocolSendComplete del autor de la llamada, si existe.
TransferDataCompleteHandler
Especifica el punto de entrada de la función ProtocolTransferDataComplete del autor de la llamada, si existe.
ResetCompleteHandler
Especifica el punto de entrada de la función ProtocolResetComplete del autor de la llamada.
RequestCompleteHandler
Especifica el punto de entrada de la función ProtocolRequestComplete del autor de la llamada.
ReceiveHandler
Especifica el punto de entrada de la función ProtocolReceive del autor de la llamada, si existe.
ReceiveCompleteHandler
Especifica el punto de entrada de la función ProtocolReceiveComplete del autor de la llamada.
StatusHandler
Especifica el punto de entrada de la función ProtocolStatus del autor de la llamada, si existe.
StatusCompleteHandler
Especifica el punto de entrada de la función ProtocolStatusComplete del autor de la llamada.
Nombre
Tipo de NDIS_STRING que contiene una cadena con recuento inicializado por el autor de la llamada, en el juego de caracteres predeterminado del sistema, asigna un nombre al controlador. Para los controladores de Windows 2000 y versiones posteriores, esta cadena contiene caracteres Unicode. Es decir, para Windows 2000 y versiones posteriores, NDIS define el tipo NDIS_STRING como un tipo de UNICODE_STRING . Esta cadena debe coincidir con la especificada en el Registro (en Servicios) cuando se instaló el protocolo.

NdisRegisterProtocol convierte la cadena proporcionada en mayúsculas, por lo que un escritor de controladores de protocolo no puede suponer que el cambio de mayúsculas y minúsculas de un nombre de protocolo ya registrado crea un nombre único para el controlador.
ReceivePacketHandler
Especifica el punto de entrada de la función ProtocolReceivePacket del autor de la llamada, si existe, o NULL. Los protocolos que se enlazan a cualquier controlador NIC que admita indicaciones de recepción de varios paquetes deben proporcionar una función ProtocolReceivePacket para mejorar su rendimiento. Sin embargo, un protocolo que se enlaza exclusivamente a miniportes orientados a conexiones también puede establecer este miembro en NULL.
BindAdapterHandler
Especifica el punto de entrada de la función ProtocolBindAdapter del autor de la llamada. Los autores de llamadas que establecen el valor del miembro MajorNdisVersion en 0x05 o 0x04 deben proporcionar una función ProtocolBindAdapter y admitir Plug and Play. Los controladores intermedios NDIS también deben proporcionar una función ProtocolBindAdapter , lo que permite a esos controladores intermedios llamar a NdisIMRegisterLayeredMiniport y aplazar la inicialización completa del controlador hasta que se hayan inicializado los controladores NIC subyacentes.
UnbindAdapterHandler
Especifica el punto de entrada de la función ProtocolUnbindAdapter del autor de la llamada. Los controladores NDIS que proporcionan una función ProtocolBindAdapter también deben proporcionar una función ProtocolUnbindAdapter .
PnPEventHandler
Especifica el punto de entrada de la función ProtocolPnPEvent del autor de la llamada, si existe.
UnloadHandler
Especifica el punto de entrada de la función ProtocolUnbind del autor de la llamada, si existe, o NULL.
CoSendCompleteHandler
Especifica el punto de entrada de la función ProtocolCoSendComplete del autor de la llamada, que debe proporcionar un cliente o administrador de llamadas orientado a la conexión. Un cliente orientado a la conexión proporciona una función ProtocolSendComplete si también se enlaza a miniportes sin conexión.
CoStatusHandlerCoStatusHandler
Especifica el punto de entrada de la función ProtocolCoStatus del autor de la llamada, que debe proporcionar un cliente o administrador de llamadas orientado a la conexión. Un cliente orientado a la conexión proporciona una función ProtocolStatus si también se enlaza a miniportes sin conexión.
CoReceivePacketHandler
Especifica el punto de entrada de la función ProtocolCoReceivePacket del autor de la llamada, que debe proporcionar un cliente o administrador de llamadas orientado a la conexión. Un cliente orientado a la conexión proporciona una función ProtocolReceivePacket o funciones ProtocolReceive y ProtocolTransferDataComplete si también se enlaza a miniportes sin conexión.
CoAfRegisterNotifyHandler
Especifica el punto de entrada de la función ProtocolAfRegisterNotify del autor de la llamada, que debe proporcionar un cliente orientado a la conexión.

[in] CharacteristicsLength

Especifica el tamaño en bytes de la estructura en ProtocolCharacteristics. Si la directiva de compilación -DNDIS50=1 o -DNDIS40=1 se especifica en el archivo de orígenes delante de #includeNdis.h , el valor sizeof(NDIS_PROTOCOL_CHARACTERISTICS) se establece automáticamente en el valor adecuado. Si no se especifica ninguna directiva, NDIS supone que se usa la estructura de características V3.0.

Los valores establecidos en los miembros MajorNdisVersion y MinorNdisVersion de la estructura de características deben ser coherentes con la directiva de compilación, o deben ser 0x03 y 0x00, respectivamente.

Valor devuelto

None

Observaciones

Un controlador de protocolo debe especificar majorNdisVersion de 0x05 (la versión actual) o 0x04. NDIS ya no admite protocolos V.30 y, por lo tanto, no carga un protocolo que especifica majorNdisVersion de 0x03.

Todos los protocolos deben ser Plug and Play (PnP). Por lo tanto, un protocolo debe especificar puntos de entrada para BindAdapterHandler y UnbindAdapterHandler. NDIS no carga un protocolo que especifica NULL para estos controladores.

Para obtener el mejor rendimiento posible, cualquier protocolo que supere por encima de un controlador NIC sin conexión que admita las recepciones multipaquete debe proporcionar una función ProtocolReceivePacket . Este controlador de protocolo también debe proporcionar una función ProtocolReceive . Cualquier controlador NIC sin conexión que admita envíos multipaquete también es probable que indique que recibe varios paquetes.

Todos los protocolos orientados a la conexión, ya sean clientes o administradores de llamadas, deben registrar una función ProtocolCoReceivePacket . Los protocolos de cliente que también se enlazan a los controladores de NIC sin conexión también proporcionan funciones ProtocolReceivePacket y ProtocolReceive . Los protocolos orientados a la conexión deben registrar puntos de entrada adicionales orientados a la conexión con NDIS mediante una llamada a NdisClOpenAddressFamily para clientes o NdisCmRegisterAddressFamily para administradores de llamadas desde sus funciones ProtocolBindAdapter .

Después de una llamada correcta a NdisRegisterProtocol, un controlador no puede modificar el conjunto de funciones ProtocolXxx proporcionadas.

Un controlador registrado correctamente debe guardar el identificador devuelto en NdisProtocolHandle. Es un parámetro necesario para otras funciones de NdisXxx a las que llama el controlador posteriormente.

Después de una llamada correcta a NdisRegisterProtocol, la función DriverEntry de un protocolo orientado a la conexión o compatible con PnP devuelve el control porque dicha función ProtocolBindAdapter del controlador se llamará posteriormente una o varias veces para configurar enlaces a NIC subyacentes. De lo contrario, el controlador de protocolo puede llamar a NdisOpenAdapter para configurar un enlace al controlador NIC subyacente o para superponer por encima de cualquier controlador NDIS que registró un conjunto de funciones NDIS MiniportXxx .

Plataforma de destino: Universal
Versión: no se admite para controladores NDIS 6.0 en Windows Vista. Use NdisRegisterProtocolDriveren su lugar. Compatible con controladores NDIS 5.1 en Windows Vista y Windows XP.

Requisitos

Requisito	Valor
Header	ndis.h (incluya Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL