PROTOCOL_CO_CREATE_VC callback function (ndis.h)

Article
10/21/2021

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).

Note You must declare the function by using the PROTOCOL_CO_CREATE_VC type. For more information, see the following Examples section.

Syntax

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

Parameters

[in] ProtocolAfContext

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 NdisClOpenAddressFamilyEx from its ProtocolCoAfRegisterNotify function.

[in] NdisVcHandle

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.

[out] ProtocolVcContext

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. Note 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 protocol drivers 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, ProtocolCoCreateVccannot 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.

Examples

To define a ProtocolCoCreateVc function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a ProtocolCoCreateVc function that is named "MyCoCreateVc", use the PROTOCOL_CO_CREATE_VC type as shown in this code example:

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

Then, implement your function as follows:

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

The PROTOCOL_CO_CREATE_VC function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the PROTOCOL_CO_CREATE_VC function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported for NDIS 6.0 and NDIS 5.1 drivers (see ProtocolCoCreateVc (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see ProtocolCoCreateVc (NDIS 5.1)) in Windows XP.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL