Função NdisCoAssignInstanceName (ndis.h)

Artigo
08/07/2023

NdisCoAssignInstanceName atribui um nome de instância a uma VC e faz com que o NDIS registre um GUID (identificador global exclusivo) para o nome atribuído com a Instrumentação de Gerenciamento do Windows (WMI).

Sintaxe

NDIS_STATUS NdisCoAssignInstanceName(
  [in]            NDIS_HANDLE  NdisVcHandle,
  [in]            PNDIS_STRING BaseInstanceName,
  [out, optional] PNDIS_STRING VcInstanceName
);

Parâmetros

[in] NdisVcHandle

Especifica o identificador para a VC que está sendo nomeada. Esse identificador foi fornecido pelo NDIS quando a VC foi originalmente criada com NdisCoCreateVc, seja pelo cliente em preparação para fazer uma chamada de saída ou pelo gerenciador de chamadas em preparação para expedir uma chamada de entrada para o cliente.

[in] BaseInstanceName

Ponteiro para um tipo de NDIS_STRING que descreve uma cadeia de caracteres Unicode fornecida pelo chamador que especifica o nome base da VC. O nome base pode ser qualquer cadeia de caracteres Unicode localizável que identifique exclusivamente a VC em relação às outras VCs nomeadas dentro do escopo do driver de miniporto. Para o Windows Vista e versões posteriores, o NDIS define o tipo NDIS_STRING como um tipo de UNICODE_STRING .

[out, optional] VcInstanceName

Ponteiro para um tipo de NDIS_STRING alocado pelo chamador no qual essa rotina retorna uma cadeia de caracteres Unicode que especifica o nome da instância atribuída pelo NDIS atribuído para a VC.

Retornar valor

NdisCoAssignInstanceName pode retornar qualquer um dos seguintes:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O NDIS atribuiu um nome de instância à VC especificada e registrou um GUID para o nome da instância com WMI.
NDIS_STATUS_FAILURE	Falha na tentativa de atribuir um nome de instância à VC.
NDIS_STATUS_RESOURCES	O NDIS não pôde alocar um buffer para o nome da instância.

Comentários

Depois de iniciar a configuração de uma VC com NdisCoCreateVc, um gerenciador de chamadas ou cliente orientado para conexão pode nomear a VC com NdisCoAssignInstanceName. Chamar NdisCoAssignInstanceName faz com que o NDIS atribua ao VC um nome de instância e registre o nome da instância com WMI. Os clientes WMI podem enumerar a VC e consultar ou definir OIDs em relação à VC.

Um driver MCM (gerenciador de chamadas de miniporto) integrado não pode usar NdisCoAssignInstanceName para nomear seus VCs. Em vez disso, um driver MCM deve criar um GUID e um OID personalizados para a VC e registrar o mapeamento GUID para OID com o NDIS.

O NDIS cria um nome de instância para a VC especificada acrescentando um índice ao nome base apontado pelo chamador. O NDIS retorna o nome completo da instância (nome base + índice) para o chamador e, em seguida, registra um GUID para o nome da instância com WMI. Somente VCs nomeadas podem ser enumeradas e consultadas por clientes WMI. VCs sem nome não estão visíveis para clientes WMI.

Se a VC especificada já tiver um nome de instância (atribuído em uma chamada anterior para NdisCoAssignInstanceName), o NDIS retornará NDIS_STATUS_SUCCESS e o nome da instância original atribuído à VC. Um nome de instância permanece atribuído a uma VC até que essa VC seja excluída.

O chamador pode associar o nome da instância retornada ao identificador da VC nomeada que o NDIS retornou anteriormente ao chamador de NdisCoCreateVc. O NDIS, no entanto, continuará a usar o identificador de VC, não o nome da instância, para se referir à VC em chamadas subsequentes. O chamador de NdisCoAssignInstanceName pode encontrar a necessidade de retornar o nome da instância para alguma outra entidade de gerenciamento.

O chamador é responsável por liberar o buffer que contém o nome da instância retornado. Depois de excluir a VC nomeada com NdisCoDeleteVc, o chamador deve liberar o buffer com NdisFreeString.

Requisitos

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