ProtocolCoCreateVc (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.
The ProtocolCoCreateVc function is a required function that allocates resources necessary for a call manager or client to activate and maintain a virtual connection (VC).
Syntax
NDIS_STATUS ProtocolCoCreateVc(
_In_ NDIS_HANDLE ProtocolAfContext,
_In_ NDIS_HANDLE NdisVcHandle,
_Out_ PNDIS_HANDLE ProtocolVcContext
);
Parameters
ProtocolAfContext [in]
Specifies the handle to a protocol-allocated context area in which the call manager or client maintains its per-open state. The call manager supplied this handle from its ProtocolCmOpenAf function. The client supplied this handle when it called NdisClOpenAddressFamily from its ProtocolCoAfRegisterNotify function.NdisVcHandle [in]
Specifies a handle, supplied by NDIS, that uniquely identifies this virtual connection. This handle is opaque to the protocol driver and reserved for NDIS library use. However, the call manager and client must save this handle to pass in subsequent calls to NdisCo/Cl/Cm/MCmXxx functions that concern this VC.ProtocolVcContext [out]
Specifies the handle to a protocol-supplied context area in which the call manager or client maintains state about this virtual connection.
Return value
ProtocolCoCreateVc returns the status of its operation(s) as one of the following values:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | Indicates that the call manager or client successfully allocated and/or initialized any necessary resources that were needed to establish and maintain a virtual connection. |
| NDIS_STATUS_RESOURCES | Indicates that the call manager or client was unable to allocate and/or initialize its resources for establishing and maintaining a virtual connection. |
| NDIS_STATUS_XXX | Indicates that the call manager or client could not set itself into a state where it could establish a virtual connection. This can could be an error return value propagated from another NDIS library routine. |
Call managers or clients cannot return NDIS_STATUS_PENDING from their ProtocolCoCreateVc functions. Returning pending will render this virtual connection unusable and the NDIS library will call the client or call manager to delete it.
Remarks
The ProtocolCoCreateVc function of a call manager or client is called whenever the corresponding client or call manager, respectively, calls NdisCoCreateVc. Clients initiate the creation of VCs in the process of setting up their outgoing calls before they call NdisClMakeCall. A call manager initiates the creation of a VC in the process of notifying its client that the CM received an incoming call offer from a remote node that is directed to a SAP already registered with the CM by that client before the CM calls NdisCmDispatchIncomingCall.
ProtocolCoCreateVc performs any necessary allocations of dynamic resources and structures that the call manager or client requires to perform subsequent operations on a VC that will be activated. Such resources include, but are not limited to, memory buffers, data structures, events, and other such similar resources. Call managers and clients should also initialize any relevant per-VC structures that they will need when a call is established.
Connection-oriented protocols must store the handle for the VC, specified in NdisVcHandle, in their per-VC state area to be used in future operations on this virtual connection. The NdisVcHandle is as required parameter to the NdisCoXxx, NdisCmXxx, and/or NdisClXxx that such a connection-oriented protocol subsequently calls.
When a call manager or client has allocated memory for its own per-VC data and initialized its state, the address of this data structure should be set in the handle before returning control to NDIS. To do this, dereference the handle and store a pointer to the protocol-allocated data area as the value of the handle. For example:
*ProtocolVcContext = SomeBuffer;
If ProtocolCoCreateVc cannot allocate the resource it needs to carry out subsequent network I/O operations, it should free all resources that were allocated for this VC and return control with a status of NDIS_STATUS_RESOURCES.
If ProtocolCoCreateVc has completed its required operations and has made the call manager or client ready to carry out call initialization for this virtual connection, ProtocolCoCreateVc should return control as quickly as possible with a status of NDIS_STATUS_SUCCESS.
Calls to ProtocolCoCreateVc are inherently synchronous in nature. That is, ProtocolCoCreateVc cannot return NDIS_STATUS_PENDING.
After a call manager's ProtocolCoCreateVc function returns control, the call manager's ProtocolCmMakeCall function will be called to establish a connection to a remote node. Call managers should not take any action in ProtocolCmMakeCall that actually establishes a call because it is possible the VC will be destroyed before a call is established due to an error condition in another component of connection-oriented NDIS.
After a client's ProtocolCoCreateVc function returns control, the client's ProtocolClIncomingCall function will be notified when a remote-initiated request to connect on a SAP previously registered by the client comes in over the network.
Requirements
Target platform |
Desktop |
Version |
See ProtocolCoCreateVc. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also