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 A 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 de 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 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 ainda são drivers de protocolo de nível 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.

Retornar valor

NdisIMInitializeDeviceInstanceEx pode retornar um dos seguintes:

Código de retorno Descrição
NDIS_STATUS_SUCCESS
O NDIS iniciou a operação de inicialização para o miniporto virtual do driver intermediário.
NDIS_STATUS_NOT_ACCEPTED
Falha em NdisIMInitializeDeviceInstanceEx porque o dispositivo especificado por DriverHandle já foi inicializado.

Comentários

Um driver intermediário do NDIS deve chamar NdisIMInitializeDeviceInstanceEx de sua função ProtocolBindAdapterEx . Uma falha ao chamar NdisIMInitializeDeviceInstanceEx de um driver intermediário do NDIS efetivamente impede que esse driver seja carregado com êxito.

Antes de chamar NdisIMInitializeDeviceInstanceEx, a função ProtocolBindAdapterEx do driver intermediário deve ser associada a todos os drivers de miniporte subjacentes necessários para que o driver intermediário funcione. A função ProtocolBindAdapterEx também pode alocar uma área em DeviceContext , possivelmente configurando-a com informações intermediárias determinadas pelo driver sobre os recursos do adaptador de miniporto subjacente e que foi coletada por 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 esse IRP, 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 miniporte 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 ao driver para realizar operações de E/S de rede, como chamar o Função NdisMSetMiniportAttributes e para 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.

Depois que 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 habilitam 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 de dispositivo fornecido pelo driver intermediário com o Função NdisIMGetBindingContext .

Antes que o NDIS chame a 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 chama a função MiniportInitializeEx de um driver intermediário, o driver deve chamar NdisIMDeInitializeDeviceInstance para reverter a operação de inicialização.

Requisitos

Requisito Valor
Cliente mínimo com suporte Com suporte para drivers NDIS 6.0 e NDIS 5.1 (consulte NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) no Windows Vista. Com suporte para drivers NDIS 5.1 (consulte NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) no Windows XP.
Plataforma de Destino Área de Trabalho
Cabeçalho ndis.h (inclua Ndis.h)
Biblioteca Ndis.lib
IRQL PASSIVE_LEVEL
Regras de conformidade de DDI Irql_IM_Function(ndis)

Confira também

IRP_MN_START_DEVICE

MiniportInitializeEx

NdisAllocateMemoryWithTagPriority NdisIMCancelInitializeDeviceInstance NdisIMDeInitializeDeviceInstance

NdisIMGetBindingContext

NdisIMInitializeDeviceInstanceEx

NdisInitializeString

NdisMRegisterMiniportDriver

NdisMSetMiniportAttributes

NdisOpenAdapterEx

ProtocolBindAdapterEx

UNICODE_STRING