NdisCoAssignInstanceName-Funktion (ndis.h)

Artikel
03/01/2024

NdisCoAssignInstanceName weist einem VC einen instance Namen zu und bewirkt, dass NDIS eine GUID (globally unique identifier) für den zugewiesenen Namen mit Windows-Verwaltungsinstrumentation (WMI) registriert.

Syntax

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

Parameter

[in] NdisVcHandle

Gibt das Handle für die VC an, die benannt wird. Dieses Handle wurde von NDIS bereitgestellt, als die VC ursprünglich mit NdisCoCreateVc erstellt wurde, sei es vom Client zur Vorbereitung für einen ausgehenden Anruf oder vom Anruf-Manager zur Vorbereitung auf das Senden eines eingehenden Anrufs an den Client.

[in] BaseInstanceName

Zeiger auf einen NDIS_STRING-Typ, der eine vom Aufrufer bereitgestellte Unicode-Zeichenfolge beschreibt, die den Basisnamen der VC angibt. Der Basisname kann eine beliebige lokalisierbare Unicode-Zeichenfolge sein, die die VC in Bezug auf die anderen benannten VCs innerhalb des Bereichs des Miniporttreibers eindeutig identifiziert. Für Windows Vista und höher definiert NDIS den NDIS_STRING-Typ als UNICODE_STRING Typ.

[out, optional] VcInstanceName

Zeiger auf einen vom Aufrufer zugewiesenen NDIS_STRING Typ, in dem diese Routine eine Unicode-Zeichenfolge zurückgibt, die den von NDIS zugewiesenen instance Namen angibt, der der VC zugewiesen ist.

Rückgabewert

NdisCoAssignInstanceName kann folgendes zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	NDIS hat der angegebenen VC einen instance Namen zugewiesen und eine GUID für den instance Namen bei WMI registriert.
NDIS_STATUS_FAILURE	Der Versuch, der VC einen instance Namen zuzuweisen, ist fehlgeschlagen.
NDIS_STATUS_RESOURCES	NDIS konnte keinen Puffer für den instance Namen zuordnen.

Hinweise

Nach dem Initiieren des Setups einer VC mit NdisCoCreateVc kann ein Anruf-Manager oder verbindungsorientierter Client die VC mit NdisCoAssignInstanceName benennen. Durch Aufrufen von NdisCoAssignInstanceName weist NDIS der VC einen instance Namen zu und registriert den instance Namen bei WMI. WMI-Clients können dann die VC aufzählen und OIDs relativ zur VC abfragen oder festlegen.

Ein integrierter MCM-Treiber (Miniport Call Manager) kann NdisCoAssignInstanceName nicht verwenden, um seine VCs zu benennen. Stattdessen sollte ein MCM-Treiber eine benutzerdefinierte GUID und OID für die VC erstellen und die GUID-zu-OID-Zuordnung bei NDIS registrieren.

NDIS erstellt einen instance Namen für die angegebene VC, indem ein Index an den Basisnamen angefügt wird, auf den der Aufrufer verweist. NDIS gibt den vollständigen instance Namen (Basisname + Index) an den Aufrufer zurück und registriert dann eine GUID für den instance Namen bei WMI. Nur benannte VCs können von WMI-Clients aufgelistet und abgefragt werden. Unbenannte VCs sind für WMI-Clients nicht sichtbar.

Wenn die angegebene VC bereits über einen instance Namen verfügt (der in einem vorherigen Aufruf von NdisCoAssignInstanceName zugewiesen wurde), gibt NDIS NDIS_STATUS_SUCCESS und den ursprünglichen instance Namen zurück, der der VC zugewiesen ist. Ein instance Name bleibt einer VC zugewiesen, bis diese VC gelöscht wird.

Der Aufrufer kann den zurückgegebenen instance Namen dem Handle für den benannten VC zuordnen, den NDIS dem Aufrufer zuvor von NdisCoCreateVc zurückgegeben hat. NDIS verwendet jedoch weiterhin das VC-Handle und nicht den instance Namen, um in nachfolgenden Aufrufen auf die VC zu verweisen. Der Aufrufer von NdisCoAssignInstanceName muss möglicherweise den instance Namen an eine andere Verwaltungsentität zurückgeben.

Der Aufrufer ist für das Freigeben des Puffers verantwortlich, der den zurückgegebenen instance Namen enthält. Nach dem Löschen des benannten VC mit NdisCoDeleteVc muss der Aufrufer den Puffer mit NdisFreeString freigeben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt für NDIS 6.0- und NDIS 5.1-Treiber (siehe NdisCoAssignInstanceName (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe NdisCoAssignInstanceName (NDIS 5.1)) in Windows XP.
Zielplattform	Desktop
Kopfzeile	ndis.h (einschließlich Ndis.h)
Bibliothek	Ndis.lib
IRQL	DISPATCH_LEVEL
DDI-Complianceregeln	Irql_Connection_Function(ndis)