Função NdisMRegisterDevice (ndis.h)
Nota NDIS 5. x foi preterido e substituído pelo NDIS 6. x. Para obter um novo desenvolvimento de driver NDIS, consulte Drivers de rede começando com o Windows Vista. Para obter informações sobre como portar o NDIS 5. x drivers para NDIS 6. x, consulte Portabilidade de drivers NDIS 5.x para NDIS 6.0.
A função NdisMRegisterDevice cria um objeto de dispositivo nomeado e um link simbólico entre o objeto do dispositivo e um nome visível pelo usuário para esse dispositivo.
Sintaxe
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 o identificador retornado por NdisMInitializeWrapper.
[in] DeviceName
Ponteiro para um tipo de NDIS_STRING que contém uma cadeia de caracteres Unicode terminada em nulo que nomeia o objeto do dispositivo. A cadeia de caracteres deve ser um nome de caminho completo, por exemplo, \Device\DeviceName. Para o Windows 2000 e posterior, o NDIS define o tipo NDIS_STRING como um tipo de UNICODE_STRING .
[in] SymbolicName
Ponteiro para um tipo de NDIS_STRING que contém uma cadeia de caracteres Unicode que é o nome visível do Win32 do dispositivo que está sendo registrado. Normalmente, o SymbolicName tem o seguinte formato: \DosDevices\SymbolicName.
[in] MajorFunctions
Ponteiro para uma matriz de um ou mais pontos de entrada para as rotinas de expedição do driver de dispositivo. Um driver deve definir tantos pontos de entrada de expedição separados quanto os códigos IRP_MJ_XXX que o driver manipula para o objeto do dispositivo. Cada rotina de expedição é declarada da seguinte maneira:
NTSTATUS
(*PDRIVER_DISPATCH) (
IN PDEVICE_OBJECT Device Object,
IN PIRP Irp
) ;
Um driver não deve fornecer pontos de entrada para Plug and Play ou manipuladores de Gerenciamento de Energia, pois o objeto de dispositivo criado não é para um dispositivo físico e, portanto, não recebe Plug and Play ou IRPs de Gerenciamento de Energia.
[in] pDeviceObject
Ponteiro para o objeto de dispositivo recém-criado se a chamada for bem-sucedida.
[out] NdisDeviceHandle
Ponteiro para uma variável fornecida pelo chamador na qual essa função, se for bem-sucedida, retornará um identificador para o objeto do dispositivo. Esse identificador é um parâmetro necessário para a função NdisMDeregisterDevice que o driver chama posteriormente.
Retornar valor
NdisMRegisterDevice retornará STATUS_SUCCESS se for bem-sucedido, NDIS_STATUS_NOT_SUPPORTED se o chamador não for um driver de miniporto NDIS ou um código de falha se falhar.
Comentários
Um driver intermediário ou um driver de miniporta pode exigir um objeto de dispositivo autônomo separado. Por exemplo, um driver de miniporto intermediário pode exigir um objeto de dispositivo autônomo para monitorar a status de uma NIC subjacente quando o driver de miniporto da NIC não estiver em execução. Para obter o status da NIC nesse caso, um aplicativo de modo de usuário ou subsistema ambiental envia um IRP para o objeto do dispositivo. O IRP é processado pelo driver intermediário. Sem o objeto de dispositivo autônomo, o status da NIC só estará disponível quando o driver de miniporto da NIC estiver em execução.
Um driver intermediário ou um driver de miniporto cria um objeto de dispositivo chamando NdisMRegisterDevice de sua função DriverEntry depois que DriverEntry tiver chamado NdisMInitializeWrapper. NdisMRegisterDevice cria um objeto de dispositivo nomeado e também um link simbólico entre o nome do objeto do dispositivo e um nome visível pelo usuário para esse dispositivo. Se a chamada para NdisMRegisterDevice for bem-sucedida, o gerenciador de E/S alocará armazenamento em pool nãopagado para o próprio objeto de dispositivo e para todas as outras estruturas de dados associadas ao objeto de dispositivo, incluindo a extensão de dispositivo do driver. A extensão de dispositivo para um objeto criado com NdisMRegisterDevice é reservada para uso pelo NDIS e não pode ser usada pelo driver.
Um objeto de dispositivo criado com funções NdisMRegisterDevice da mesma forma que um objeto de dispositivo e um link simbólico que foram criados com IoCreateDevice e IoCreateSymbolicLink, respectivamente. O driver de miniporta é responsável por processar todos os IRPs recebidos pelo objeto do dispositivo. (O NDIS processa todos os IRPs de gerenciamento de energia e Plug and Play enviados ao objeto do dispositivo.) O driver processa IRPs enviados ao objeto de dispositivo usando rotinas de expedição que ele registrou quando forneceu o ponteiro MajorFunctions para NdisMRegisterDevice. Para obter mais informações sobre objetos de dispositivo, IRPs e rotinas de expedição, consulte Objetos de Dispositivo e Pilhas de Dispositivos, Manipulação de IRPs e Gravação de Rotinas de Expedição.
O miniporto NDIS e os drivers intermediários nunca devem chamar IoCreateDevice ou IoCreateSymbolicLink. Em vez disso, se um driver NDIS precisar criar um objeto de dispositivo, ele deverá chamar NdisMRegisterDevice. Os drivers miniport e intermediários nunca devem tentar empilhar o objeto de dispositivo sobre o objeto de dispositivo físico chamando IoAttachDevice.
O objeto de dispositivo criado com NdisMRegisterDevice não é um objeto de dispositivo físico e, portanto, não recebe Plug and Play ou IRPs de Gerenciamento de Energia. Os chamadores de NdisMRegisterDevice devem, portanto, omitir pontos de entrada para Plug and Play ou manipuladores de Gerenciamento de Energia na matriz apontada por MajorFunctions.
Observe que, se um identificador para o objeto de dispositivo criado com NdisMRegisterDevice estiver aberto, o driver que criou o objeto de dispositivo não poderá ser descarregado. Portanto, um aplicativo de modo de usuário deve fazer o seguinte:
Quando o aplicativo se registra para a notificação de evento do dispositivo no dispositivo subjacente chamando a função RegisterDeviceNotification , especifique um filtro de notificação de tipo DBT_DEVTYP_HANDLE. (Para obter mais informações sobre a função RegisterDeviceNotification, consulte a documentação do SDK do Microsoft Windows.) Se o aplicativo receber posteriormente um evento DBT_DEVICEQUERYREMOVE para o dispositivo, o aplicativo deverá fechar o identificador aberto.
Quando o aplicativo se registra para notificação de evento de dispositivo no dispositivo subjacente chamando a função RegisterDeviceNotification , especifique um filtro de notificação de tipo DBT_DEVTYP_DEVICEINTERFACE e GUID_NDIS_LAN_CLASS como o GUID da classe de interface. Se o aplicativo receber posteriormente um evento DBT_DEVICEREMOVECOMPLETE para a interface do dispositivo à qual o identificador corresponde, o aplicativo deverá fechar o identificador aberto.
Se a chamada de um driver para NdisMRegisterDevice falhar, o driver poderá continuar carregando ou não, dependendo da importância do objeto de dispositivo autônomo para a operação do driver.
- Plataforma de destino: Universal
- Versão: não há suporte para drivers NDIS 6.0 no Windows Vista. Em vez disso, use NdisRegisterDeviceEx. Com suporte para drivers NDIS 5.1 no Windows Vista e no Windows XP.
Requisitos
| Requisito | Valor |
|---|---|
| Cabeçalho | ndis.h (inclua Ndis.h) |
| Biblioteca | Ndis.lib |
| IRQL | PASSIVE_LEVEL |