ProtocolCmMakeCall (NDIS 5.1) function

Article
06/19/2017

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 ProtocolCmMakeCall function is a required function that sets up media specific parameters for a virtual connection (VC) and activates the virtual connection.

Syntax

NDIS_STATUS ProtocolCmMakeCall(
  _In_      NDIS_HANDLE         CallMgrVcContext,
  _Inout_   PCO_CALL_PARAMETERS CallParameters,
  _In_opt_  NDIS_HANDLE         NdisPartyHandle,
  _Out_opt_ PNDIS_HANDLE        CallMgrPartyContext
);

Parameters

CallMgrVcContext [in]
Specifies the handle to a call manager-allocated context area in which the call managers maintains its per-VC state. The call manager supplied this handle to NDIS from its ProtocolCoCreateVc function.
CallParameters [in, out]
Pointer to a CO_CALL_PARAMETERS structure that contains the parameters, specified by a connection-oriented client, for this outgoing call.
NdisPartyHandle [in, optional]
Specifies a handle, supplied by NDIS, that uniquely identifies the initial party on the multipoint virtual connection. This handle is opaque to the call manager and reserved for NDIS library use. This handle is NULL if the client is not setting up an outgoing multipoint call.
CallMgrPartyContext [out, optional]
On return, specifies a handle to a call manager-supplied context area in which the call manager maintains state about the initial party on the multipoint call. If NdisPartyHandle is NULL, this handle must be set to NULL.

Return value

ProtocolCmMakeCall returns the status of its operation(s) as one of the following values:

Return code	Description
NDIS_STATUS_SUCCESS	Indicates that the call manager successfully allocated the necessary resources to make the call and was able to activate the virtual connection with the miniport driver.
NDIS_STATUS_PENDING	Indicates that the call manager will complete the request to make a call asynchronously. When the call manager has completed all operations for making a call, it must call NdisCmMakeCallComplete to signal NDIS that this call has been completed.
NDIS_STATUS_RESOURCES	Indicates that the call manager was unable to allocate and/or initialize its resources for activating the virtual connection as requested by the client.
NDIS_STATUS_NOT_SUPPORTED	Indicates that the call manager was unable to activate a virtual connection because the caller requested invalid or unavailable features in the call parameters specified at CallParameters.

Remarks

If ProtocolCmMakeCall is given an explicit NdisPartyHandle, this VC was created by the client for a multipoint call. The call manager must allocate and initialize any necessary resources required to maintain state information and control a multipoint call. Such resources include, but are not limited to, memory buffers, data structures, events, and other similar resources. If the call manager cannot allocate or initialize the needed resources for its state area(s), it should return control to NDIS with NDIS_STATUS_RESOURCES.

ProtocolCmMakeCall communicates with network control devices or other media-specific actors, as necessary, to make a connection between the local node and a remote node based on the call parameters specified at CallParameters. Such actions could include, but are not limited to, communication with switching hardware, communications with a network control station, or other actions as appropriate to the network medium.

If a call manager is required to communication with networking hardware (such as a networking switch) it should use a virtual connection to the network control device that it established in its ProtocolBindAdapter function. Call managers communicate with their network hardware through the miniport driver by calling NdisCoSendPackets. Miniport drivers with integrated call-management support will not call NdisCoSendPackets, but rather will transmit the data themselves.

After a call manager has done all necessary communication with its networking hardware as required by its medium, call managers must call NdisCmActivateVc.

If this call was a multipoint call, after the call manager has communicated with the networking hardware, verified call parameters, and allocated and initialized its per-party state data, the address of its state block should be set in the handle CallMgrPartyContext before returning control to NDIS. The handle is set by dereferencing the handle and storing a pointer to the state block as the value of the handle. For example:

*CallMgrPartyContext = SomeBuffer ;

If ProtocolCmMakeCall has completed the required operations for its network and the VC has been successfully activated through NdisCmActivateVc, ProtocolCmMakeCall should return control as quickly as possible with a status of STATUS_SUCCESS.

After ProtocolCmMakeCall returns control to NDIS, the call manager should expect to take no further actions on this call to set it up. ProtocolCmMakeCall is responsible for establishing the connection so that the client can make data transfers over the network on this VC. However, the call manager can be called subsequently to modify the call's quality of service, to add or drop parties if this is a multipoint VC, and eventually to terminate this call.

Requirements

Target platform	Desktop
Version	See ProtocolCmMakeCall.
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL

Share via