PROTOCOL_CL_NOTIFY_CLOSE_AF callback function (ndis.h)

Article
11/25/2021

The ProtocolClNotifyCloseAf function notifies a CoNDIS client that the client should close the associated address family (AF).

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

Syntax

PROTOCOL_CL_NOTIFY_CLOSE_AF ProtocolClNotifyCloseAf;

NDIS_STATUS ProtocolClNotifyCloseAf(
  [in] NDIS_HANDLE ClientAfContext
)
{...}

Parameters

[in] ClientAfContext

A client-supplied handle to its context area for the associated AF. The client allocated this context area and passed this handle to NDIS in its call to the NdisClOpenAddressFamilyEx function.

Return value

ProtocolClNotifyCloseAf can return one of the following:

Return code	Description
NDIS_STATUS_SUCCESS	The client successfully closed the address family.
NDIS_STATUS_PENDING	The client is handling this request asynchronously, and it will call the NdisClNotifyCloseAddressFamilyComplete function when the close operation is complete.
NDIS_STATUS_XXX	The client failed the request for some driver-determined reason.

Remarks

The ProtocolClNotifyCloseAf function is required for CoNDIS clients. NDIS calls ProtocolClNotifyCloseAf when a call manager notifies NDIS that the address family (AF) that the ProtocolAfContext parameter specifies should be closed. In response, the client should:

Call the NdisClDropParty function as many times as necessary until only a single party remains active on each multipoint virtual connection (VC), if the client has any active multipoint connections.
Call the NdisClCloseCall function as many times as necessary to close all of the calls that are still open and are associated with the AF.
Call the NdisClDeregisterSap function as many times as necessary to deregister all service access points (SAPs) that the client has registered with the call manager.
Call the NdisClCloseAddressFamily function to close the AF.

The client can complete these actions asynchronously by returning NDIS_STATUS_PENDING. If the client completes the call asynchronously, it must subsequently call the NdisClNotifyCloseAddressFamilyComplete function when the close operation is complete. If the client does not return NDIS_STATUS_PENDING, the close operation is complete when ProtocolClNotifyCloseAf returns.

NDIS calls ProtocolClNotifyCloseAf at IRQL <= DISPATCH_LEVEL.

The client may use the NdisAfHandle while the AF is open or while a ProtocolClNotifyCloseAf operation is pending. If the ProtocolClNotifyCloseAf function returns NDIS_STATUS_PENDING, use the handle in the NdisClNotifyCloseAddressFamilyComplete call after the close operation completes.

Examples

To define a ProtocolClNotifyCloseAf 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 ProtocolClNotifyCloseAf function that is named "MyClNotifyCloseAf", use the PROTOCOL_CL_NOTIFY_CLOSE_AF type as shown in this code example:

PROTOCOL_CL_NOTIFY_CLOSE_AF MyClNotifyCloseAf;

Then, implement your function as follows:

_Use_decl_annotations_
NDIS_STATUS
 MyClNotifyCloseAf(
    NDIS_HANDLE  ProtocolAfContext
    )
  {...}

The PROTOCOL_CL_NOTIFY_CLOSE_AF 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_NOTIFY_CLOSE_AF 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 in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL