PROTOCOL_CL_OPEN_AF_COMPLETE callback function

Article
06/19/2017

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.

The ProtocolClOpenAfComplete function is used by all connection-oriented NDIS clients. Such clients must have ProtocolClOpenAfComplete functions to complete the asynchronous operations that they initiate with NdisClOpenAddressFamily.

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

Syntax

PROTOCOL_CL_OPEN_AF_COMPLETE ProtocolClOpenAfComplete;

VOID ProtocolClOpenAfComplete(
  _In_ NDIS_STATUS Status,
  _In_ NDIS_HANDLE ProtocolAfContext,
  _In_ NDIS_HANDLE NdisAfHandle
)
{ ... }

Parameters

Status [in]
Specifies the final status of the client's call to NdisClOpenAddressFamily, which can be any of the following:
- NDIS_STATUS_SUCCESS
  The address family has been opened, so the client can initialize its state at ProtocolAfContext and use the returned NdisAfHandle in subsequent calls to NDIS functions, such as NdisCoRequest, NdisCoCreateVc, and NdisClRegisterSap.
- NDIS_STATUS_RESOURCES
  The requested operation failed because NDIS or the call manager could not allocate sufficient memory or initialize the state one of them uses to track the client's open of this address family
- NDIS_STATUS_FAILURE
  NDIS failed this call, possibly for one of the following reasons:
  - The given address family does not match any AF that was registered for the underlying miniport driver to which the caller is bound.
  - The caller supplied invalid or insufficient information at ClCharacteristics to NdisClOpenAddressFamily.
  - The caller's adapter binding is closing.
  - The call manager that registered the given address family is closing its adapter binding.
ProtocolAfContext [in]
Specifies the client-supplied handle to its per-AF context area for this address family. The client allocated this area and passed this handle to NDIS in its call to NdisClOpenAddressFamily.
NdisAfHandle [in]
If Status is NDIS_STATUS_SUCCESS, specifies an NDIS-supplied valid handle to this address family, effectively representing an association established with NDIS between the client and a particular call manager bound to the same connection-oriented NIC driver. Otherwise, this parameter is NULL. The client must save a valid handle, usually in its ProtocolAfContext area, for subsequent calls to NdisCl/CoXxx functions.

Return value

None

Remarks

A call to ProtocolClOpenAfComplete indicates that some or all of the following has occurred:

NDIS validated some of the parameters that the client's ProtocolCoAfRegisterNotify function passed to NdisClOpenAddressFamily. If all were valid, NDIS saved the client's ProtocolClXxx entry points. Then, NDIS called the ProtocolCmOpenAf function of the call manager that just registered the specified address family with NDIS.
The call manager (or MCM driver if the miniport driver controls a NIC with integrated call-management functionality) has examined the specification that the client's ProtocolCoAfRegisterNotify function passed to NdisClOpenAddressFamily at AddressFamily and returned whether it was valid for this call manager to NDIS.

If the client's attempt to open an address family fails, NDIS cleans up its saved state before calling ProtocolClOpenAfComplete, which can release the resources that the client allocated for its call to NdisClOpenAddressFamily or prepare them for reuse.

Otherwise, ProtocolClOpenAfComplete should set up whatever client-determined state the client will need for subsequent operations on the newly opened AF. In particular, the client must save the input NdisAfHandle, usually in the client's ProtocolAfContext area. For example, ProtocolClOpenAfComplete also might call NdisInitializeNPagedLookasideList one or more times in preparation for dynamic allocations and releases of per-SAP, per-VC, and/or per-party context areas that the client will need subsequently.

If it accepts incoming calls, the client might proceed to allocate a per-SAP state area and call NdisClRegisterSap. If it makes outgoing calls, the client might proceed to allocate a per-VC state area and create a VC with NdisCoCreateVc in anticipation of an incoming request from one of its own clients to make an outgoing call to a remote node.

Examples

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

PROTOCOL_CL_OPEN_AF_COMPLETE MyClOpenAfComplete;

Then, implement your function as follows:

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

The PROTOCOL_CL_OPEN_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_OPEN_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

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolClOpenAfCompleteExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL