NdisClMakeCall (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.
NdisClMakeCall sets up an outgoing call on a client-created VC.
Syntax
NDIS_STATUS NdisClMakeCall(
_In_ NDIS_HANDLE NdisVcHandle,
_Inout_ PCO_CALL_PARAMETERS CallParameters,
_In_opt_ NDIS_HANDLE ProtocolPartyContext,
_Out_opt_ PNDIS_HANDLE NdisPartyHandle
);
Parameters
NdisVcHandle [in]
Specifies the handle returned by a preceding call to NdisCoCreateVc.CallParameters [in, out]
Pointer to a structure of type CO_CALL_PARAMETERS in which the caller has specified the attributes for this connection, such as the address of the target for the call, latency, bandwidth, and quality of service if the network medium and address family supported by the call manager permits QoS specifications.ProtocolPartyContext [in, optional]
Optionally specifies a caller-supplied handle to a resident context area in which the client will maintain per-party state for the initial party on its multipoint VC. This parameter is NULL if the given VC does not represent a multipoint connection. For a multipoint VC, NDIS passes this handle back to the client's ProtocolClXxx functions in all subsequent calls that affect this particular party.NdisPartyHandle [out, optional]
Pointer to a caller-supplied variable, usually in the caller-allocated party context area, in which NDIS returns a handle representing the initial party to the multipoint connection if the request to set up an outgoing call is successful. If ProtocolPartyContext is NULL, this variable, usually in the client's VC context area, also is set to NULL on completion of outgoing-call setup.
Return value
When NdisClMakeCall returns anything other than NDIS_STATUS_PENDING, the client should make an internal call to its ProtocolClMakeCallComplete function. Otherwise, NDIS calls the client's ProtocolClMakeCallComplete function when this operation is completed.
Remarks
NdisClMakeCall sets up the attributes of a client-created VC for a client-initiated outgoing call. The client must set up the VC with NdisCoCreateVc before it attempts to make an outgoing call.
A call to NdisClMakeCall causes NDIS to forward this request to the ProtocolCmMakeCall function of the call manager with which the client shares the given NdisVcHandle. The CM is responsible for validating the given data at CallParameters. It can modify this client-supplied data while negotiating with relevant network components and can return different traffic parameters than the client originally gave to NdisClMakeCall. The client's ProtocolClMakeCallComplete function is responsible for accepting the modified call parameters if this occurs or for tearing down the call if the CM's proposed call parameters are unacceptable.
Consequently, the data at CallParameters must remain available to the call manager at least for the duration of call setup. The client cannot free this buffer when NdisClMakeCall returns NDIS_STATUS_PENDING. It must defer releasing this client-allocated resource until its ProtocolClMakeCallComplete function is called.
If NdisClMakeCall sets up a multipoint connection, the client is establishing the traffic parameters globally for the given VC, unless the underlying network medium supports per-party traffic parameters. For example, no matter how many parties a client subsequently adds on an ATM multipoint VC with NdisClAddParty, these parties will all share the same traffic parameters on their multipoint connection. A client on an ATM network cannot specify bandwidth, QoS, and so forth, as CallParameters on a per-party basis. In addition, if a client on an ATM network changes the QoS on an established multipoint VC with NdisClModifyCallQoS, its change affects all parties on the multipoint VC.
The client's ProtocolClMakeCallComplete function should check the input Status for NDIS_STATUS_SUCCESS before it uses any returned handle at NdisPartyHandle. If the call manager fails the request to set up a call on a multipoint connection, the value of this client-supplied variable is invalid.
Requirements
Target platform |
Universal |
Version |
See NdisClMakeCall. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL |
See also
NdisAllocateFromNPagedLookasideList