Função NdisCoAssignInstanceName (ndis.h)
NdisCoAssignInstanceName atribui um nome de instância a um 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 do VC. O nome base pode ser qualquer cadeia de caracteres Unicode localizável que identifique exclusivamente a VC em relação aos outros VCs nomeados dentro do escopo do driver de miniporto. Para o Windows Vista e posteriores, o NDIS define o tipo de 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 ao NDIS atribuído para o VC.
Valor de retorno
NdisCoAssignInstanceName pode retornar qualquer um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
O NDIS atribuiu um nome de instância ao VC especificado e registrou um GUID para o nome da instância com WMI. |
|
Falha na tentativa de atribuir um nome de instância à VC. |
|
O NDIS não pôde alocar um buffer para o nome da instância. |
Observações
Depois de iniciar a instalação de um VC com NdisCoCreateVc, um cliente orientado a chamadas ou de conexão pode nomear o 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 OID personalizados para o VC e registrar o mapeamento GUID-to-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 nomeados podem ser enumerados e consultados por clientes WMI. VCs sem nome não são visíveis para clientes WMI.
Se o VC especificado 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 de original atribuído ao VC. Um nome de instância permanece atribuído a uma VC até que a VC seja excluída.
O chamador pode associar o nome da instância retornada ao identificador do VC nomeado 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 fazer referência à VC nas 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 retornada. Depois de excluir o VC nomeado com NdisCoDeleteVc, o chamador deve liberar o buffer com NdisFreeString.