MINIPORT_ADD_DEVICE função de retorno de chamada (ndis.h)

Artigo
08/07/2023

A função MiniportAddDevice permite que um driver de miniporte estabeleça uma área de contexto para um dispositivo adicionado.

Nota Você deve declarar a função usando o tipo MINIPORT_ADD_DEVICE . Para obter mais informações, consulte a seção Exemplos a seguir.

Sintaxe

MINIPORT_ADD_DEVICE MiniportAddDevice;

NDIS_STATUS MiniportAddDevice(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext
)
{...}

Parâmetros

[in] NdisMiniportHandle

Um identificador NDIS que identifica o adaptador de miniporto que o gerenciador de Plug and Play (PnP) está adicionando. O NDIS também passa esse identificador para o Função MiniportInitializeEx .

[in] MiniportDriverContext

Um identificador para uma área de contexto alocada pelo driver em que o driver mantém informações de estado e configuração. O driver de miniporte passou essa área de contexto para o Função NdisMRegisterMiniportDriver .

Retornar valor

MiniportAddDevice retorna um dos seguintes valores:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O driver de miniporte alocou com êxito os recursos necessários para adicionar o dispositivo.
NDIS_STATUS_RESOURCES	O driver de miniporte não conseguiu alocar os recursos necessários.
NDIS_STATUS_FAILURE	O MiniportAddDevice falhou por motivos diferentes de recursos insuficientes.

Se MiniportAddDevice falhar, o NDIS não chamará a função MiniportInitializeEx para inicializar o adaptador de miniport.

Comentários

A função MiniportAddDevice é uma função opcional. Os drivers de miniport que dão suporte a MSI-X devem especificar um ponto de entrada para essa função no NDIS_MINIPORT_PNP_CHARACTERISTICS estrutura.

MiniportAddDevice pode alocar uma área de contexto para tratamento IRP_MN_FILTER_RESOURCE_REQUIREMENTS Pacotes de solicitação de E/S (IRPs) que o Identificadores de função MiniportFilterResourceRequirements . Os drivers de miniporto especificam a área de contexto inicializando um NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES estrutura e, em seguida, chamando o Função NdisMSetMiniportAttributes . Posteriormente, o NDIS fornece esse identificador de contexto para o MiniportRemoveDevice,Funções MiniportFilterResourceRequirements, MiniportStartDevice e MiniportInitializeEx. Para MiniportInitializeEx, o identificador de contexto é passado no membro MiniportAddDeviceContext do NDIS_MINIPORT_INIT_PARAMETERS estrutura para a qual o parâmetro MiniportInitParameters aponta.

Se o driver de miniporte falhar na chamada MiniportAddDevice depois de alocar a área de contexto, o driver deverá liberar a área de contexto antes de retornar de MiniportAddDevice.

Os drivers de miniport devem usar uma área de contexto diferente para o membro MiniportAddDeviceContext da estrutura NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES e o membro MiniportAdapterContext da estrutura NDIS_MINIPORT_INIT_PARAMETERS . Áreas de contexto separadas garantirão que as informações na área de contexto não sejam reinicializadas, o que pode ocorrer na função MiniportInitializeEx se o adaptador de miniporto for interrompido e reinicializado.

Quando o gerenciador PnP solicita que o NDIS remova o dispositivo, o NDIS chama a função MiniportRemoveDevice para desfazer as operações executadas pelo MiniportAddDevice .

O NDIS chama MiniportAddDevice em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função MiniportAddDevice , primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função MiniportAddDevice chamada "MyAddDevice", use o tipo MINIPORT_ADD_DEVICE conforme mostrado neste exemplo de código:

MINIPORT_ADD_DEVICE MyAddDevice;

Em seguida, implemente sua função da seguinte maneira:

_Use_decl_annotations_
NDIS_STATUS
 MyAddDevice(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext
    )
  {...}

O tipo de função MINIPORT_ADD_DEVICE é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função MINIPORT_ADD_DEVICE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL