Функция NdisCoAssignInstanceName (ndis.h)

Статья
08/07/2023

NdisCoAssignInstanceName назначает имя экземпляра VC и заставляет NDIS регистрировать GUID (глобальный уникальный идентификатор) для назначенного имени с помощью инструментария управления Windows (WMI).

Синтаксис

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

Параметры

[in] NdisVcHandle

Указывает дескриптор именованного проверяемого удостоверения. Этот дескриптор был предоставлен NDIS при первоначальном создании VC с помощью NdisCoCreateVc, будь то клиентом при подготовке к исходящему вызову или диспетчером вызовов при подготовке к отправке входящего вызова клиенту.

[in] BaseInstanceName

Указатель на тип NDIS_STRING, описывающий предоставленную вызывающим элементом строку Юникода, указывающую базовое имя VC. Базовым именем может быть любая локализуемая строка Юникода, которая однозначно идентифицирует VC по отношению к другим именованным виртуальным машинам в область драйвера мини-порта. Для Windows Vista и более поздних версий NDIS определяет тип NDIS_STRING как тип UNICODE_STRING .

[out, optional] VcInstanceName

Указатель на тип, выделенный вызывающим NDIS_STRING, в котором эта подпрограмма возвращает строку Юникода, указывающую имя экземпляра, назначаемое NDIS, назначенное для VC.

Возвращаемое значение

NdisCoAssignInstanceName может возвращать любое из следующих элементов:

Код возврата	Описание
NDIS_STATUS_SUCCESS	NDIS назначил имя экземпляра указанному проверяемому экземпляру и зарегистрировал GUID для имени экземпляра с помощью WMI.
NDIS_STATUS_FAILURE	Попытка назначить имя экземпляра VC завершилась сбоем.
NDIS_STATUS_RESOURCES	NDIS не удалось выделить буфер для имени экземпляра.

После запуска настройки виртуальной машины с помощью NdisCoCreateVc диспетчер вызовов или клиент, ориентированный на подключение, может присвоить VC имя NdisCoAssignInstanceName. Вызов NdisCoAssignInstanceName приводит к тому, что NDIS назначает VC имя экземпляра и регистрирует имя экземпляра с помощью WMI. Затем клиенты WMI могут перечислить VC и запрашивать или задавать идентификаторы OID относительно VC.

Интегрированный драйвер диспетчера вызовов мини-порта (MCM) не может использовать NdisCoAssignInstanceName для именования своих виртуальных компьютеров. Вместо этого драйвер MCM должен создать пользовательский GUID и OID для VC и зарегистрировать сопоставление GUID-OID с помощью NDIS.

NDIS создает имя экземпляра для указанного VC, добавляя индекс к базовому имени, на который указывает вызывающий объект. NDIS возвращает полное имя экземпляра (базовое имя + индекс) вызывающей объекту, а затем регистрирует GUID для имени экземпляра с помощью WMI. Клиенты WMI могут перечислять и запрашивать только именованные виртуальные машины. Неименованные виртуальные машины не видны клиентам WMI.

Если у указанного VC уже есть имя экземпляра (назначенное в предыдущем вызове NdisCoAssignInstanceName), NDIS возвращает NDIS_STATUS_SUCCESS и исходное имя экземпляра, назначенное VC. Имя экземпляра остается назначенным проверяемому экземпляру до тех пор, пока он не будет удален.

Вызывающий объект может связать возвращенное имя экземпляра с дескриптором именованного VC, который NDIS ранее вернул вызывающей объекту из NdisCoCreateVc. Однако NDIS будет по-прежнему использовать дескриптор VC, а не имя экземпляра, для ссылки на VC в последующих вызовах. Вызывающий объект NdisCoAssignInstanceName может обнаружить необходимость возврата имени экземпляра другому объекту управления.

Вызывающий объект отвечает за освобождение буфера, содержащего возвращенное имя экземпляра. После удаления именованного VC с помощью NdisCoDeleteVc вызывающий объект должен освободить буфер с помощью NdisFreeString.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается для драйверов NDIS 6.0 и NDIS 5.1 (см. раздел NdisCoAssignInstanceName (NDIS 5.1)) в Windows Vista. Поддерживается для драйверов NDIS 5.1 (см. раздел NdisCoAssignInstanceName (NDIS 5.1)) в Windows XP.
Целевая платформа	Персональный компьютер
Верхняя часть	ndis.h (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	DISPATCH_LEVEL
Правила соответствия DDI	Irql_Connection_Function(ndis)