NdisClAddParty (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.
NdisClAddParty adds a party on the client's multipoint VC.
Syntax
NDIS_STATUS NdisClAddParty(
_In_ NDIS_HANDLE NdisVcHandle,
_In_ NDIS_HANDLE ProtocolPartyContext,
_Inout_ PCO_CALL_PARAMETERS CallParameters,
_Out_ PNDIS_HANDLE NdisPartyHandle
);
Parameters
NdisVcHandle [in]
Pointer to the VC handle returned by NdisCoCreateVc.ProtocolPartyContext [in]
Specifies the handle to a caller-allocated resident context area in which the client will maintain per-party state if its call succeeds.CallParameters [in, out]
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.NdisPartyHandle [out]
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 NIC 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. For example, traffic parameters on a multipoint VC are identical for all parties on ATM networks. When a client on an ATM network calls NdisClAddParty, the traffic parameters, such as the bandwidth, at CallParameters should match those already established for the multipoint VC originally set up by the client with NdisClMakeCall. For each party that the client subsequently adds on its multipoint VC, the ATM call manager uses the same traffic parameters, so the client need specify only new addressing information and the already established multipoint VC's traffic parameters at CallParameters for NdisClAddParty.
If the underlying network medium, like ATM, 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.
If the add-party operation succeeds, the variable at NdisPartyHandle has been set by NDIS to a valid handle shared among NDIS, the client, and the call manager. The client must treat this NDIS-supplied handle as an opaque variable to be passed, unmodified and uninterpreted, in subsequent calls to NdisCl/CoXxx functions concerning the newly added 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 NIC 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. For example, on ATM networks, there is no way for the client to send data exclusively to a particular party on a VC that represents an established multipoint connection.
Requirements
Target platform |
Universal |
Version |
See NdisClAddParty. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL |
See also
NdisAllocateFromNPagedLookasideList