NdisCoCreateVc function (ndis.h)
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(
[in] NDIS_HANDLE NdisBindingHandle,
[in, optional] NDIS_HANDLE NdisAfHandle,
[in] NDIS_HANDLE ProtocolVcContext,
[in, out] PNDIS_HANDLE NdisVcHandle
);
Parameters
[in] 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.
[in, optional] 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.
[in] 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.
[in, out] 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 created the VC successfully. |
|
NDIS could not allocate sufficient memory to set up the VC. |
|
The given NdisAfHandle is invalid. |
|
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
| Requirement | Value |
|---|---|
| Minimum supported client | 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(ndis) |