NdisCoCreateVc function

NdisCoCreateVc sets up a connection endpoint from which a client can make outgoing calls or on which a stand-alone call manager can dispatch incoming calls.

Syntax

NDIS_STATUS NdisCoCreateVc(
  NDIS_HANDLE  NdisBindingHandle,
  NDIS_HANDLE  NdisAfHandle,
  NDIS_HANDLE  ProtocolVcContext,
  PNDIS_HANDLE NdisVcHandle
);

Parameters

NdisBindingHandle

Specifies the handle returned by NdisOpenAdapterEx that identifies the target NIC or virtual adapter of the next-lower driver to which the caller is bound.

NdisAfHandle

Specifies the handle returned by NdisClOpenAddressFamilyEx if the caller is a client. A call manager sets this parameter to NULL if it is creating a VC for itself, such as a VC to a network switch. When it creates a VC for incoming call notifications, a call manager passes the AF handle that it saved in its per-AF state designated by the CallMgrAfContext that was passed as an input parameter to its ProtocolCmRegisterSap function.

ProtocolVcContext

Specifies the handle to a caller-supplied resident context area in which the caller maintains state for this VC. NDIS passes this handle back to the VC creator in all subsequent calls concerning this endpoint if the call to NdisCoCreateVc succeeds.

NdisVcHandle

Pointer to a caller-supplied variable that must be initialized to NULL when NdisCoCreateVc is called. On return from a successful call, this points to a variable that NDIS has set to its handle for the newly created VC. The caller must save this handle for subsequent calls to connection-oriented Ndis Xxx functions.

Return Value

NdisCoCreateVc can return one of the following:

Return code Description
NDIS_STATUS_SUCCESS
NDIS created the VC successfully.
NDIS_STATUS_RESOURCES
NDIS could not allocate sufficient memory to set up the VC.
NDIS_STATUS_FAILURE
The given NdisAfHandle is invalid.
NDIS_STATUS_ XXX
The underlying miniport driver failed the creation of the VC for a miniport driver-determined reason, which NDIS has propagated to the caller.

Remarks

A client or stand-alone call manager creates a VC with NdisCoCreateVc, depending on whether the VC represents an outgoing or incoming call, respectively.

In the process of VC creation, NDIS supplies an NdisVcHandle to the client, the call manager, and the miniport driver to which both protocol drivers are bound. This handle identifies the virtual circuit for the client, call manager, and miniport driver to which subsequent requests concerning the given VC are directed. Each driver must treat this VC handle as an opaque variable, passing it unmodified and uninterpreted in subsequent calls to certain connection-oriented NDIS library functions.

Usually, callers of NdisCoCreateVc store the returned NdisVcHandle in the caller-allocated state area at ProtocolVcContext . NDIS passes this handle as an input parameter to the ProtocolCoCreateVc and MiniportCoCreateVc functions of the other two drivers involved in each creation of a VC.

To make an outgoing call, a client must call NdisCoCreateVc first. As a synchronous operation, NDIS calls the underlying miniport driver's MiniportCoCreateVc function and the call manager's ProtocolCoCreateVc function before NdisCoCreateVc returns control. If its call to NdisCoCreateVc succeeds, the client can proceed in making an outgoing call, passing the returned NdisVcHandle to NdisClMakeCall.

When its ProtocolCoReceiveNetBufferLists function processes the offer of an incoming call directed to one of its registered SAPs, a call manager must call NdisCoCreateVc first. As a synchronous operation, NDIS calls the underlying miniport driver's MiniportCoCreateVc function and the client's ProtocolCoCreateVc function before NdisCoCreateVc returns control. If its call to NdisCoCreateVc succeeds, the call manager can proceed in notifying the appropriate client, passing the returned value at NdisVcHandle to NdisCmDispatchIncomingCall.

Stand-alone call managers, which register themselves with NDIS as protocol drivers, can call NdisCoCreateVc. Connection-oriented miniport drivers that provide integrated call-management support call NdisMCmCreateVc, instead.

Requirements

   
Windows version Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisCoCreateVc (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisCoCreateVc (NDIS 5.1)) in Windows XP.
Target Platform Desktop
Header ndis.h (include Ndis.h)
Library Ndis.lib
IRQL "<= DISPATCH_LEVEL"
DDI compliance rules Irql_Connection_Function

See Also

MiniportCoCreateVc

NdisAllocateFromNPagedLookasideList

NdisClMakeCall

NdisCmDispatchIncomingCall

NdisCoDeleteVc

NdisMCmCreateVc

ProtocolCmRegisterSap

ProtocolCoCreateVc

ProtocolCoReceiveNetBufferLists