NdisClOpenAddressFamilyEx function (ndis.h)

Article
04/18/2022

The NdisClOpenAddressFamilyEx function registers an address family (AF) that is associated with a call manager for a connection-oriented client.

Syntax

NDIS_STATUS NdisClOpenAddressFamilyEx(
  [in]  NDIS_HANDLE        NdisBindingHandle,
  [in]  PCO_ADDRESS_FAMILY AddressFamily,
  [in]  NDIS_HANDLE        ClientAfContext,
  [out] PNDIS_HANDLE       NdisAfHandle
);

Parameters

[in] NdisBindingHandle

The handle that NdisOpenAdapterEx returns and that identifies the target network interface card (NIC) or the virtual adapter of the next-lower driver that the caller is bound to.

[in] AddressFamily

A pointer to a CO_ADDRESS_FAMILY structure that describes the call manager and AF to be opened.

This pointer is an input parameter to the client's ProtocolCoAfRegisterNotify function, which calls NdisClOpenAddressFamilyEx.

[in] ClientAfContext

The handle to a caller-supplied resident context area in which the client maintains state for this AF after the AF has been opened. NDIS passes this handle back to the client in all subsequent calls concerning this AF if the call to NdisClOpenAddressFamilyEx succeeds.

[out] NdisAfHandle

A pointer to a caller-supplied variable in which NdisClOpenAddressFamilyEx returns a handle that represents the newly opened address family.

Return value

When NdisClOpenAddressFamilyEx returns anything other than NDIS_STATUS_PENDING, the client should make an internal call to its ProtocolClOpenAfCompleteEx function. Otherwise, NDIS calls the client's ProtocolClOpenAfCompleteEx function when this operation is completed.

Remarks

A CoNDIS client calls NdisClOpenAddressFamilyEx from its ProtocolCoAfRegisterNotify function, after the client checks the input buffer that is pointed to by the AddressFamily parameter to determine whether the client recognizes the call manager and registered addresses. NDIS forwards the client's call of NdisClOpenAddressFamilyEx to the call manager's ProtocolCmOpenAf function, which ensures that the client has passed in a valid AF structure.

A successful call to NdisClOpenAddressFamilyEx sets up communication from the client to a call manager. The client can then prepare to receive incoming calls by calling the NdisClRegisterSap function. The client can also set up a virtual connection (VC) by calling the NdisCoCreateVc function so it can make an outgoing call by calling the NdisClMakeCall function.

If the client's call to NdisClOpenAddressFamilyEx fails, the client should call the NdisUnbindAdapter function to request NDIS to release its binding to the underlying miniport adapter. Otherwise, the client must save the handle that is returned at the NdisAfHandle parameter. This handle identifies the call manager to which subsequent requests concerning the given address family are directed. The client must treat this returned handle as an opaque variable, passing it unmodified and uninterpreted in subsequent NdisXxx function calls.

NDIS passes the pointer from the ClientAfContext parameter to the client's registered ProtocolClXxx functions in all subsequent calls that concern the AF until the client calls NdisClCloseAddressFamily with the same NdisAfHandle . After the AF is closed, the client can release or reuse the storage that it allocated at ClientAfContext .

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Desktop
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI compliance rules	Irql_Protocol_Driver_Function(ndis)