PROTOCOL_CL_DROP_PARTY_COMPLETE callback function (ndis.h)

Article
10/21/2021

The ProtocolClDropPartyComplete function is used by connection-oriented NDIS clients that set up multipoint connections. Such clients must have ProtocolClDropPartyComplete functions to complete the asynchronous operations that they initiate with

NdisClDropParty. Otherwise, such a protocol driver's registered ProtocolClDropPartyComplete function can simply return control.

Note You must declare the function by using the PROTOCOL_CL_DROP_PARTY_COMPLETE type. For more information, see the following Examples section.

Syntax

PROTOCOL_CL_DROP_PARTY_COMPLETE ProtocolClDropPartyComplete;

void ProtocolClDropPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext
)
{...}

Parameters

[in] Status

Specifies the final status of the client-initiated drop-party operation, which can be one of the following:

NDIS_STATUS_SUCCESS

The party has been dropped. The NdisPartyHandle that represented this party, which the client stored in its ProtocolPartyContext area, is now invalid.

NDIS_STATUS_FAILURE

The given party was the last remaining on the client's multipoint VC. Therefore, the client should call NdisClCloseCall to drop this party.

[in] ProtocolPartyContext

Specifies the handle to the client's per-party context area, which the client originally supplied to NDIS either when it called NdisClAddParty or NdisClMakeCall.

Return value

None

Remarks

A call to ProtocolClDropPartyComplete indicates that the call manager has completed processing of the request initiated by the client's previous call to NdisClDropParty. ProtocolClDropPartyComplete can either release the client-allocated per-party context area or prepare it for reuse in a subsequent call to NdisClAddParty.

If the client is in the process of tearing down a multipoint VC that it created, ProtocolClDropPartyComplete can call NdisClDropParty with any valid NdisPartyHandle to one of the remaining parties on the client's active multipoint VC. If only one more party remains on its multipoint VC, the client should drop that party by passing its NdisPartyHandle to NdisClCloseCall.

Examples

To define a ProtocolClDropPartyComplete function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a ProtocolClDropPartyComplete function that is named "MyClDropPartyComplete", use the PROTOCOL_CL_DROP_PARTY_COMPLETE type as shown in this code example:

PROTOCOL_CL_DROP_PARTY_COMPLETE MyClDropPartyComplete;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyClDropPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext
    )
  {...}

The PROTOCOL_CL_DROP_PARTY_COMPLETE function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the PROTOCOL_CL_DROP_PARTY_COMPLETE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported for NDIS 6.0 and NDIS 5.1 drivers (see ProtocolClDropPartyComplete (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see ProtocolClDropPartyComplete (NDIS 5.1)) in Windows XP.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL