PROTOCOL_CL_CLOSE_AF_COMPLETE callback function (ndis.h)

Article
10/21/2021

The ProtocolClCloseAfComplete function is used by connection-oriented NDIS clients. All connection-oriented NDIS clients must have ProtocolClCloseAfComplete functions to complete the asynchronous operations that they initiate with NdisClCloseAddressFamily.

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

Syntax

PROTOCOL_CL_CLOSE_AF_COMPLETE ProtocolClCloseAfComplete;

void ProtocolClCloseAfComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolAfContext
)
{...}

Parameters

[in] Status

Specifies the final status of the client-initiated request to close the address family, which can be one of the following:

NDIS_STATUS_SUCCESS

The address family was closed. The NdisAfHandle that represented the open address family, which the client stored in its ProtocolAfContext area, is now invalid.

NDIS_STATUS_FAILURE

Either the AF has associated VC(s) and/or registered SAP(s) that the client must release before attempting to close the AF, or the client called NdisClCloseAddressFamily twice because NDIS discovered that the AF state was marked as "closing."

[in] ProtocolAfContext

Specifies the client-supplied handle to its per-AF context area. The client originally set up this context area and passed this handle to NDIS with NdisClOpenAddressFamilyEx.

Return value

None

Remarks

After ensuring that it has no outstanding VCs and/or registered SAPs on its open address family, a client calls NdisClCloseAddressFamily to delete the association between itself, a call manager, and a particular underlying NIC. NDIS calls the ProtocolCmCloseAf function for the call manager that this client originally used to open the address family as an asynchronous operation. After calling NdisClCloseAddressFamily, the client should consider the NdisAfHandle invalid.

Consequently, the client must have a ProtocolClCloseAfComplete function, which NDIS calls when the asynchronous close-AF operation is done. If the input Status is NDIS_STATUS_SUCCESS, the client can release its per-AF context area.

Examples

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

PROTOCOL_CL_CLOSE_AF_COMPLETE MyClCloseAfComplete;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyClCloseAfComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolAfContext
    )
  {...}

The PROTOCOL_CL_CLOSE_AF_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_CLOSE_AF_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 ProtocolClCloseAfComplete (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see ProtocolClCloseAfComplete (NDIS 5.1)) in Windows XP.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL