Función NdisMRegisterDevice (ndis.h)
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.
La función NdisMRegisterDevice crea un objeto de dispositivo con nombre y un vínculo simbólico entre el objeto de dispositivo y un nombre visible para el usuario para ese dispositivo.
Sintaxis
NDIS_STATUS NdisMRegisterDevice(
[in] NDIS_HANDLE NdisWrapperHandle,
[in] PNDIS_STRING DeviceName,
[in] PNDIS_STRING SymbolicName,
[in] PDRIVER_DISPATCH *MajorFunctions,
[in] PDEVICE_OBJECT *pDeviceObject,
[out] NDIS_HANDLE *NdisDeviceHandle
);
Parámetros
[in] NdisWrapperHandle
Especifica el identificador devuelto por NdisMInitializeWrapper.
[in] DeviceName
Puntero a un tipo de NDIS_STRING que contiene una cadena Unicode terminada en null que asigna un nombre al objeto de dispositivo. La cadena debe ser un nombre de ruta de acceso completa; por ejemplo, \Device\DeviceName. Para Windows 2000 y versiones posteriores, NDIS define el tipo de NDIS_STRING como un tipo de UNICODE_STRING .
[in] SymbolicName
Puntero a un tipo de NDIS_STRING que contiene una cadena Unicode que es el nombre visible de Win32 del dispositivo que se está registrando. Normalmente, El nombre simbólico tiene el siguiente formato: \DosDevices\SymbolicName.
[in] MajorFunctions
Puntero a una matriz de uno o varios puntos de entrada para las rutinas de envío del controlador del dispositivo. Un controlador debe establecer tantos puntos de entrada de envío independientes como los códigos IRP_MJ_XXX que controla el controlador para el objeto de dispositivo. Cada rutina de envío se declara de la siguiente manera:
NTSTATUS
(*PDRIVER_DISPATCH) (
IN PDEVICE_OBJECT Device Object,
IN PIRP Irp
) ;
Un controlador no debe proporcionar puntos de entrada para los controladores de administración de energía o Plug and Play, ya que el objeto de dispositivo creado no es para un dispositivo físico y, por lo tanto, no recibe Plug and Play o IRP de administración de energía.
[in] pDeviceObject
Puntero al objeto de dispositivo recién creado si la llamada se realiza correctamente.
[out] NdisDeviceHandle
Puntero a una variable proporcionada por el autor de la llamada en la que esta función, si se ejecuta correctamente, devuelve un identificador al objeto de dispositivo. Este identificador es un parámetro necesario para la función NdisMDeregisterDevice a la que llama posteriormente el controlador.
Valor devuelto
NdisMRegisterDevice devuelve STATUS_SUCCESS si se realiza correctamente, NDIS_STATUS_NOT_SUPPORTED si el autor de la llamada no es un controlador de miniporte NDIS o un código de error si se produce un error.
Comentarios
Un controlador intermedio o un controlador de minipuerto pueden requerir un objeto de dispositivo independiente independiente independiente. Por ejemplo, un controlador de minipuerto intermedio puede requerir un objeto de dispositivo independiente para supervisar el estado de una NIC subyacente cuando el controlador de miniporte de la NIC no esté en funcionamiento. Para obtener el estado de la NIC en tal caso, una aplicación en modo de usuario o subsistema de entorno envía un IRP al objeto de dispositivo. El controlador intermedio procesa el IRP. Sin el objeto de dispositivo independiente, el estado de la NIC solo está disponible cuando el controlador de minipuerto de la NIC está en funcionamiento.
Un controlador intermedio o un controlador de minipuerto crea un objeto de dispositivo llamando a NdisMRegisterDevice desde su función DriverEntry después de que DriverEntry haya llamado a NdisMInitializeWrapper. NdisMRegisterDevice crea un objeto de dispositivo con nombre y también un vínculo simbólico entre el nombre del objeto de dispositivo y un nombre visible para el usuario para ese dispositivo. Si la llamada a NdisMRegisterDevice se realiza correctamente, el administrador de E/S asigna almacenamiento en un grupo no paginado para el propio objeto de dispositivo y para todas las demás estructuras de datos asociadas al objeto de dispositivo, incluida la extensión del dispositivo del controlador. La extensión de dispositivo para un objeto creado con NdisMRegisterDevice está reservado para su uso por NDIS y el controlador no puede usarlo.
Objeto de dispositivo creado con funciones NdisMRegisterDevice de la misma manera que un objeto de dispositivo y un vínculo simbólico que se crearon con IoCreateDevice e IoCreateSymbolicLink, respectivamente. El controlador de minipuerto es responsable de procesar todos los IRP que recibe para el objeto de dispositivo. (NDIS procesa todos los IRP de administración de energía y Plug and Play enviados al objeto de dispositivo). El controlador procesa los IRP enviados al objeto de dispositivo mediante rutinas de distribución que registró cuando proporcionó el puntero MajorFunctions a NdisMRegisterDevice. Para obtener más información sobre los objetos de dispositivo, los IRP y las rutinas de envío, consulte Objetos de dispositivo y Pilas de dispositivos, Control de IRP y Escritura de rutinas de envío.
Los controladores intermedios y miniport de NDIS nunca deben llamar a IoCreateDevice o IoCreateSymbolicLink. En su lugar, si un controlador NDIS debe crear un objeto de dispositivo, debe llamar a NdisMRegisterDevice. Los controladores intermedios y miniportar nunca deben intentar apilar el objeto de dispositivo sobre el objeto de dispositivo físico mediante una llamada a IoAttachDevice.
El objeto de dispositivo que se crea con NdisMRegisterDevice no es un objeto de dispositivo físico y, por lo tanto, no recibe Plug and Play o IRP de administración de energía. Por lo tanto, los autores de llamadas de NdisMRegisterDevice deben omitir los puntos de entrada para los controladores de administración de energía o Plug and Play de la matriz a la que apunta MajorFunctions.
Tenga en cuenta que, si un identificador del objeto de dispositivo que se crea con NdisMRegisterDevice está abierto, el controlador que creó el objeto de dispositivo no se puede descargar. Por lo tanto, una aplicación en modo de usuario debe realizar una de las siguientes acciones:
Cuando la aplicación se registra para la notificación de eventos de dispositivo en el dispositivo subyacente mediante una llamada a la función RegisterDeviceNotification , especifique un filtro de notificación de tipo DBT_DEVTYP_HANDLE. (Para obtener más información sobre la función RegisterDeviceNotification, consulte la documentación de Microsoft Windows SDK). Si la aplicación recibe posteriormente un evento de DBT_DEVICEQUERYREMOVE para el dispositivo, la aplicación debe cerrar el identificador abierto.
Cuando la aplicación se registra para la notificación de eventos de dispositivo en el dispositivo subyacente mediante una llamada a la función RegisterDeviceNotification , especifique un filtro de notificación de tipo DBT_DEVTYP_DEVICEINTERFACE y GUID_NDIS_LAN_CLASS como GUID de clase de interfaz. Si la aplicación recibe posteriormente un evento de DBT_DEVICEREMOVECOMPLETE para la interfaz de dispositivo a la que corresponde el identificador, la aplicación debe cerrar el identificador abierto.
Si se produce un error en la llamada de un controlador a NdisMRegisterDevice , el controlador puede seguir cargándose o no, dependiendo de lo crítico que sea el objeto de dispositivo independiente para la operación del controlador.
- Plataforma de destino: Universal
- Versión: no se admite para controladores NDIS 6.0 en Windows Vista. Use NdisRegisterDeviceExen 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 |