Adding a Party to a Multipoint Call (NDIS 5.1)
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.
A client requests to add a party to a multipoint call with NdisClAddParty. A client can add a party only to an existing multipoint call--that is, a call for which the client supplied a ProtocolPartyContextto NdisClMakeCall(see Making a Call).
The following figure shows a client of a call manager requesting to add a party to multipoint call.
.png)
The following figure shows a client of an MCM driver requesting to add a party to multipoint call.
.png)
Before it calls NdisClAddParty, a client must allocate and initialize its context area for the party to be added. Clients commonly pass a pointer to such a context area as the ProtocolPartyContextand a pointer to a variable within that context area as the NdisPartyHandleparameters when they call NdisClAddParty.
In addition to an NdisVcHandleand a ProtocolPartyContext, the client passes call parameters (a buffered CO_CALL_PARAMETERSstructure) to NdisClAddParty. The underlying network medium determines whether a client can specify per-party traffic parameters on a multipoint VC. For example, traffic parameters on a multipoint VC are identical for all parties on ATM networks.
The call to NdisClAddPartycauses NDIS to forward this request to the ProtocolCmAddPartyfunction of the call manager or MCM driver with which the client shares the given NdisVcHandle. NDIS passes the following to the ProtocolCmAddParty function:
A CallMgrVcContext that indicates the VC for the call
A pointer to a CO_CALL_PARAMETERS structure that contains the call parameters passed by the client to NdisClAddParty
An NdisPartyHandle that identifies the party to be added
ProtocolCmAddParty allocates and initializes any dynamic resources needed for the party being added to the call. From ProtocolCmAddParty, a call manager or MCM driver communicates with network control devices or other media-specific agents, as necessary, to add the specified party to the multipoint call.
If the client passed in call parameters that did not match those already established for the multipoint VC, the call manager or MCM driver can, for example:
Set up the per-party traffic parameters if the underlying network medium supports this feature on multipoint VCs
Reset the client-supplied traffic parameters to those originally established for the VC
Change the call parameters for the VC and for every party currently connected on it
Fail the client's attempt to add a party
ProtocolCmAddParty can complete synchronously or, more probably, asynchronously with NdisCmAddPartyComplete, in the case of a call manager, or NdisMCmAddPartyComplete, in the case of an MCM driver. Whether the call manager or MCM driver completes the operation synchronously or asynchronously, it passes the buffered call parameters to NDIS.
The call to Ndis(M)CmAddPartyComplete causes NDIS to call the client's ProtocolClAddPartyCompletefunction. If the client's request to add the party succeeded and if the signaling protocol allows the call manager or MCM driver to modify the call parameters, ProtocolClAddPartyComplete should test the CALL_PARAMETERS_CHANGED flag in the buffered CO_CALL_PARAMETERS structure to determine whether the call parameters were modified. The signaling protocol determines what the client can do if it finds the modifications to CO_CALL_PARAMETERS unacceptable. Usually, a client calls NdisClDropPartyin this case (see Dropping a Party from a Multipoint Call).