NdisClAddParty function (ndis.h)
NdisClAddParty adds a party on the client's multipoint VC.
Syntax
NDIS_STATUS NdisClAddParty(
[in] NDIS_HANDLE NdisVcHandle,
[in] NDIS_HANDLE ProtocolPartyContext,
[in, out] PCO_CALL_PARAMETERS CallParameters,
[out] PNDIS_HANDLE NdisPartyHandle
);
Parameters
[in] NdisVcHandle
Pointer to the VC handle returned by NdisCoCreateVc.
[in] ProtocolPartyContext
Specifies the handle to a caller-allocated resident context area in which the client will maintain per-party state if its call succeeds.
[in, out] CallParameters
Pointer to a structure of type CO_CALL_PARAMETERS in which the caller has specified the addressing information for the party to be added on its multipoint VC.
[out] NdisPartyHandle
Pointer to a variable to be set by NDIS if the add-party operation succeeds.
Return value
When NdisClAddParty returns anything other than NDIS_STATUS_PENDING, the client should make an internal call to its ProtocolClAddPartyComplete function. Otherwise, NDIS calls the client's ProtocolClAddPartyComplete function when this operation is completed.
Remarks
Before it calls NdisClAddParty, a client must set up a multipoint connection on its VC with NdisClMakeCall, as well as allocating and initializing its context area for the party to be added. Clients commonly pass a pointer to such a context area as the ProtocolPartyContext and a pointer to a variable within that context area as the NdisPartyHandle parameters when they call NdisClAddParty.
A call to NdisClAddParty causes NDIS to forward this request to the ProtocolCmAddParty function of the call manager with which the client shares the given NdisVcHandle . The call manager either returns an error status immediately or, more commonly, NDIS_STATUS_PENDING if it attempts to satisfy this request. If its attempt is rejected on the remote endpoint or by the underlying miniport driver, the call manager returns a final error status, such as NDIS_STATUS_FAILURE, when it calls NdisCmAddPartyComplete or NdisMCmAddPartyComplete. The client's ProtocolClAddPartyComplete function should check the input Status argument for NDIS_STATUS_SUCCESS before proceeding further.
The underlying network medium determines whether a client can specify per-party traffic parameters on a multipoint VC.
If the underlying network medium does not support per-party traffic parameters on multipoint VCs, a call manager can do one of the following whenever a client attempts to add a party with a specification at CallParameters that does not match the already established traffic parameters for that VC:
- Reject the request to add a new party.
- Reset the traffic parameters to those already established for the multipoint VC when it successfully adds the party on that VC.
- Change the traffic parameters for every party already on the VC when it successfully adds the new party.
In turn, NDIS passes the client-supplied ProtocolPartyContext handle in subsequent calls to the client's ProtocolClXxx functions that concern this newly added party, including the call to ProtocolClAddPartyComplete.
Whether a multipoint call permits transfers in both directions and/or per-party transfers with per-party traffic parameters depends on the medium of the underlying miniport driver to which the client is bound. The NdisPartyHandle represents only the specific party added by a successful call to NdisClAddParty, rather than the multipoint VC. Consequently, the client can use its ProtocolPartyContext area only for subsequent party-specific call-management requests. For data transfers over network media that do not support per-party transfers or traffic parameters, the client must use the NdisVcHandle instead.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisClAddParty (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisClAddParty (NDIS 5.1)) in Windows XP. |
| Target Platform | Desktop |
| Header | ndis.h (include Ndis.h) |
| Library | Ndis.lib |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | Irql_Protocol_Driver_Function(ndis) |