Função NdisIMInitializeDeviceInstanceEx (ndis.h)
A função NdisIMInitializeDeviceInstanceEx inicia a operação de inicialização de um miniporto virtual e, opcionalmente, configura informações de estado sobre o miniporto virtual para drivers de protocolo associados posteriormente.
Sintaxe
NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
[in] NDIS_HANDLE DriverHandle,
[in] PNDIS_STRING DriverInstance,
[in, optional] NDIS_HANDLE DeviceContext
);
Parâmetros
[in] DriverHandle
O identificador do driver de miniporto que o função NdisMRegisterMiniportDriver retorna em NdisMiniportDriverHandle .
[in] DriverInstance
Um ponteiro para um tipo de NDIS_STRING que descreve uma cadeia de caracteres contada inicializada pelo chamador no conjunto de caracteres padrão do sistema. A cadeia de caracteres contém o nome da chave do Registro na qual o driver armazena informações sobre um miniporto virtual e, possivelmente, informações específicas da associação. Para drivers do Microsoft Windows 2000 e posteriores, essa cadeia de caracteres contém caracteres Unicode. Ou seja, para o Windows 2000 e posterior, o NDIS define o tipo de NDIS_STRING como um tipo de UNICODE_STRING.
[in, optional] DeviceContext
Um ponteiro para a memória fornecida pelo chamador a ser configurada com informações de contexto de dispositivo definidas pelo driver sobre o miniporto virtual, que drivers de protocolo de nível ainda mais alto que posteriormente se associam a esse miniporto virtual podem usar. Esse parâmetro poderá ser NULL se o driver intermediário não tiver essa área de contexto do dispositivo.
Valor de retorno
NdisIMInitializeDeviceInstanceEx pode retornar um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
O NDIS iniciou a operação de inicialização para o miniporto virtual do driver intermediário. |
|
falha no NdisIMInitializeDeviceInstanceEx porque o dispositivo especificado por driverHandle já foi inicializado. |
Observações
Um driver intermediário do NDIS deve chamar NdisIMInitializeDeviceInstanceEx de sua função de ProtocolBindAdapterEx. Uma falha ao chamar NdisIMInitializeDeviceInstanceEx de um driver intermediário do NDIS efetivamente impede que esse driver carregue com êxito.
Antes de chamar NdisIMInitializeDeviceInstanceEx, a função ProtocolBindAdapterEx do driver intermediário deve ser associada a quaisquer drivers de miniporto subjacentes necessários para que o driver intermediário funcione. A função ProtocolBindAdapterEx pode alocar uma área no DeviceContext também, possivelmente configurando-a com informações intermediárias determinadas pelo driver sobre os recursos do adaptador de miniporto subjacente e que foi coletada pelo ProtocolBindAdapterEx. A função MiniportInitializeEx do driver intermediário pode usar essas informações posteriormente para configurar essa área de contexto com informações sobre o miniporto virtual do driver.
A chamada do driver intermediário para NdisIMInitializeDeviceInstanceEx faz com que o NDIS chame a função MiniportInitializeEx do driver intermediário, se o NDIS receber uma IRP_MN_START_DEVICE IRP para iniciar o dispositivo. Se o NDIS não receber um IRP desse tipo, o NDIS não chamará a função MiniportInitializeEx do driver intermediário.
A chamada para MiniportInitializeEx pode ocorrer posteriormente e, portanto, não está necessariamente dentro do contexto da chamada para NdisIMInitializeDeviceInstanceEx. Se o NDIS nunca chamar MiniportInitializeEx para o miniporto virtual referenciado em uma chamada para NdisIMInitializeDeviceInstanceEx e o driver intermediário não exigir mais o miniporto virtual, o driver intermediário deverá chamar o função NdisIMCancelInitializeDeviceInstance para cancelar a inicialização do miniporto virtual. Por exemplo, suponha que um driver intermediário crie um miniporto virtual em resposta a uma associação bem-sucedida a um adaptador de miniporto subjacente. Se essa associação for removida antes que o NDIS chame MiniportInitializeEx, o driver intermediário deverá chamar NdisIMCancelInitializeDeviceInstance para cancelar a inicialização do miniporto virtual.
MiniportInitializeEx aloca todos os recursos necessários para o driver realizar operações de E/S de rede, como chamar o função NdisMSetMiniportAttributes e inicializar o miniporto virtual do driver para um estado operacional. Em seguida, os drivers de protocolo de nível superior podem se associar ao miniporto virtual quando a inicialização do driver intermediário for concluída com êxito.
Após MiniportInitializeEx retornar o controle, a área de contexto do dispositivo do driver intermediário, se houver, poderá conter quaisquer dados definidos pelo driver intermediário que posteriormente habilita todos os drivers de protocolo de nível superior associados ao mesmo miniporto virtual para acessar informações nessa área de contexto. Esse driver de protocolo de nível superior pode consultar o contexto do dispositivo fornecido pelo driver intermediário com o função de NdisIMGetBindingContext.
Antes que o NDIS chame uma função MiniportInitializeEx de um driver intermediário, o driver pode chamar NdisIMCancelInitializeDeviceInstance para cancelar a operação de inicialização.
Depois que o NDIS chamar a função MiniportInitializeEx de um driver intermediário, o driver deverá chamar NdisIMDeInitializeDeviceInstance para reverter a operação de inicialização.