NdisCoAssignInstanceName (NDIS 5.1) function

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisCoAssignInstanceName assigns an instance name to a VC and causes NDIS to register a GUID (globally unique identifier) for the assigned name with Windows Management Instrumentation (WMI).

Syntax

NDIS_STATUS NdisCoAssignInstanceName(
  _In_      NDIS_HANDLE  NdisVcHandle,
  _In_      PNDIS_STRING BaseInstanceName,
  _Out_opt_ PNDIS_STRING VcInstanceName
);

Parameters

• NdisVcHandle [in]
  Specifies the handle to the VC being named. This handle was supplied by NDIS when the VC was originally created with NdisCoCreateVc, whether by the client in preparation for making an outgoing call or by the call manager in preparation for dispatching an incoming call to the client.

• BaseInstanceName [in]
  Pointer to an NDIS_STRING type that describes a caller-supplied Unicode string that specifies the base name of the VC. The base name can be any localizable Unicode string that uniquely identifies the VC with respect to the other named VCs within the scope of the miniport driver. For Windows 2000 and later, NDIS defines the NDIS_STRING type as a UNICODE_STRING type.

• VcInstanceName [out, optional]
  Pointer to a caller-allocated NDIS_STRING type in which this routine returns a Unicode string that specifies the NDIS-assigned instance name assigned for the VC.

Return value

NdisCoAssignInstanceName can return any of the following:

Remarks

After initiating the setup of a VC with NdisCoCreateVc, a call manager or connection-oriented client can name the VC with NdisCoAssignInstanceName. Calling NdisCoAssignInstanceName, causes NDIS to assign the VC an instance name and register the instance name with WMI. WMI clients can then enumerate the VC and query or set OIDs relative to the VC.

An integrated miniport call manager (MCM) driver cannot use NdisCoAssignInstanceName to name its VCs. Instead, an MCM driver should create a custom GUID and OID for the VC and register the GUID-to-OID mapping with NDIS.

NDIS creates an instance name for the specified VC by appending an index to the base name pointed to by the caller. NDIS returns the complete instance name (base name + index) to the caller and then registers a GUID for the instance name with WMI. Only named VCs can be enumerated and queried by WMI clients. Unnamed VCs are not visible to WMI clients.

If the specified VC already has an instance name (assigned in a previous call to NdisCoAssignInstanceName), NDIS returns NDIS_STATUS_SUCCESS and the original instance name assigned to the VC. An instance name remains assigned to a VC until that VC is deleted.

The caller can associate the returned instance name with the handle for the named VC that NDIS previously returned to the caller from NdisCoCreateVc. NDIS, however, will continue to use the VC handle--not the instance name--to refer to the VC in subsequent calls. The caller of NdisCoAssignInstanceName might find the need to return the instance name to some other management entity.

The caller is responsible for freeing the buffer containing the returned instance name. After deleting the named VC with NdisCoDeleteVc, the caller must free the buffer with NdisFreeString.

Requirements

See also

MiniportCoRequest

MiniportQueryInformation

NdisCoCreateVc

NdisCoDeleteVC

NdisFreeString

UNICODE_STRING

Send comments about this topic to Microsoft