NdisClOpenAddressFamily 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.

NdisClOpenAddressFamily registers a set of client-supplied functions for connection-oriented communication through a particular NIC using an address family registered by a particular call manager.

Syntax

NDIS_STATUS NdisClOpenAddressFamily(
  _In_  NDIS_HANDLE                  NdisBindingHandle,
  _In_  PCO_ADDRESS_FAMILY           AddressFamily,
  _In_  NDIS_HANDLE                  ProtocolAfContext,
  _In_  PNDIS_CLIENT_CHARACTERISTICS ClCharacteristics,
  _In_  UINT                         SizeOfClCharacteristics,
  _Out_ PNDIS_HANDLE                 NdisAfHandle
);

Parameters

NdisBindingHandle [in]
Specifies the handle returned by NdisOpenAdapter that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound.
AddressFamily [in]
Pointer to a structure of type CO_ADDRESS_FAMILY describing the call manager and address family to be opened.

This pointer is an input parameter to the client's ProtocolCoAfRegisterNotify function, which calls NdisClOpenAddressFamily.
ProtocolAfContext [in]
Specifies the handle to a caller-supplied resident context area in which the client maintains state for this address family after it has been opened. NDIS passes this handle back to the client in all subsequent calls concerning this address family if the call to NdisClOpenAddressFamily succeeds.
ClCharacteristics [in]
Pointer to an NDIS_CLIENT_CHARACTERISTICS structure set up by the caller. The structure at ClCharacteristics is defined as follows:
```
typedef struct _NDIS_CLIENT_CHARACTERISTICS {
    UCHAR   MajorVersion;
    UCHAR   MinorVersion;
    USHORT  Filler;           // reserved for system use
    UINT    Reserved;         // reserved for system use
    CO_CREATE_VC_HANDLER  ClCreateVcHandler;
    CO_DELETE_VC_HANDLER  ClDeleteVcHandler;
    CO_REQUEST_HANDLER  ClRequestHandler;
    CO_REQUEST_COMPLETE_HANDLER  ClRequestCompleteHandler;
    CL_OPEN_AF_COMPLETE_HANDLER  ClOpenAfCompleteHandler;
    CL_CLOSE_AF_COMPLETE_HANDLER  ClCloseAfCompleteHandler;
    CL_REG_SAP_COMPLETE_HANDLER  ClRegisterSapCompleteHandler;
    CL_DEREG_SAP_COMPLETE_HANDLER  ClDeregisterSapCompleteHandler;
    CL_MAKE_CALL_COMPLETE_HANDLER  ClMakeCallCompleteHandler;
    CL_MODIFY_CALL_QOS_COMPLETE_HANDLER
                                    ClModifyCallQoSCompleteHandler;
    CL_CLOSE_CALL_COMPLETE_HANDLER  ClCloseCallCompleteHandler;
    CL_ADD_PARTY_COMPLETE_HANDLER  ClAddPartyCompleteHandler;
    CL_DROP_PARTY_COMPLETE_HANDLER  ClDropPartyCompleteHandler;
    CL_INCOMING_CALL_HANDLER  ClIncomingCallHandler;
    CL_INCOMING_CALL_QOS_CHANGE_HANDLER
                                    ClIncomingCallQoSChangeHandler;
    CL_INCOMING_CLOSE_CALL_HANDLER  ClIncomingCloseCallHandler;
    CL_INCOMING_DROP_PARTY_HANDLER  ClIncomingDropPartyHandler;
    CL_CALL_CONNECTED_HANDLER  ClCallConnectedHandler;
} NDIS_CLIENT_CHARACTERISTICS, *PNDIS_CLIENT_CHARACTERISTICS;
```
The driver should initialize this structure with zeros before setting up the following members:
- MajorVersion
  Specifies the major version of this structure that the client is using. The current value is 0x05.
- MinorVersion
  Specifies the minor version of this structure that the client is using. The current value is 0x00.
- filler and Reserved
  The caller should ignore these members after zero-initializing this structure.
- ClCreateVcHandler
  Specifies the entry point of the caller's ProtocolCoCreateVc function.
- ClDeleteVcHandler
  Specifies the entry point of the caller's ProtocolCoDeleteVc function.
- ClRequestHandler
  Specifies the entry point of the caller's ProtocolCoRequest function.
- ClRequestCompleteHandler
  Specifies the entry point of the caller's ProtocolCoRequestComplete function.
- ClOpenAfCompleteHandler
  Specifies the entry point of the caller's ProtocolClOpenAfComplete function.
- ClCloseAfCompleteHandler
  Specifies the entry point of the caller's ProtocolClCloseAfComplete function.
- ClRegisterSapCompleteHandler
  Specifies the entry point of the caller's ProtocolClRegisterSapComplete function. A client uses this function to accept incoming calls from remote machines.
- ClDeregisterSapCompleteHandler
  Specifies the entry point of the caller's ProtocolClDeregisterSapComplete function.
- ClMakeCallCompleteHandler
  Specifies the entry point of the caller's ProtocolClMakeCallComplete function. A client uses this function to make outgoing calls to remote machines.
- ClModifyCallQoSCompleteHandler
  Specifies the entry point of the caller's ProtocolClModifyCallQoSComplete function. A client uses this function to make changes in the quality of service on an established VC dynamically or to negotiate with the call manager to establish the QoS when setting up an incoming call.
- ClCloseCallCompleteHandler
  Specifies the entry point of the caller's ProtocolClCloseCallComplete function.
- ClAddPartyCompleteHandler
  Specifies the entry point of the caller's ProtocolClAddPartyComplete function. A client uses this function to establish point-to-multipoint VCs for outgoing calls to remote machines.
- ClDropPartyCompleteHandler
  Specifies the entry point of the caller's ProtocolClDropPartyComplete function.
- ClIncomingCallHandler
  Specifies the entry point of the caller's ProtocolClIncomingCall function. A client uses this function to accept incoming calls from remote machines.
- ClIncomingCallQoSChangeHandler
  Specifies the entry point of the caller's ProtocolClIncomingCallQoSChange function. A client uses this function to accept incoming calls from remote machines on which the sending client can change the QoS dynamically.
- ClIncomingCloseCallHandler
  Specifies the entry point of the caller's ProtocolClIncomingCloseCall function.
- ClIncomingDropPartyHandler
  Specifies the entry point of the caller's ProtocolClIncomingDropParty function.
- ClCallConnectedHandler
  Specifies the entry point of the caller's ProtocolClCallConnected function. A client uses this function to accept incoming calls from remote machines.
SizeOfClCharacteristics [in]
Specifies the size in bytes of the structure at ClCharacteristics.
NdisAfHandle [out]
Pointer to a caller-supplied variable in which this function returns a handle representing the newly opened address family.

Return value

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

Remarks

A connection-oriented client calls NdisClOpenAddressFamily from its ProtocolCoAfRegisterNotify function, after checking the input buffer at AddressFamily to determine whether the client recognizes the call manager and registered addresses. NDIS forwards the client's call of NdisClOpenAddressFamily to the call manager's ProtocolCmOpenAf function, which ensures that the client has passed in a valid address family structure.

The client must set every ClXxx member in the NDIS_CLIENT_CHARACTERISTICS structure to a caller-supplied ProtocolCl/CoXxx function when it calls NdisClOpenAddressFamily, even if it does not support incoming calls, outgoing calls, or point-to-multipoint connections. For whatever subset of connection-oriented functionality that such a client does not support, its ProtocolCl/CoXxx functions simply return NDIS_STATUS_NOT_SUPPORTED.

A successful call to NdisClOpenAddressFamily sets up communication from the client either to a connection-oriented NIC driver through a particular call manager that is bound to the same NIC or to an integrated MCM driver for the NIC to which the client is bound. The client can then make itself ready to receive incoming calls with NdisClRegisterSap or can set up a virtual connection with NdisCoCreateVc in order to make an outgoing call with NdisClMakeCall.

If its call to NdisClOpenAddressFamily fails, the client should call NdisCloseAdapter to release its binding to the underlying NIC driver.

Otherwise, the client must save the handle returned at NdisAfHandle. 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 calls to certain NDIS library functions. Usually, callers of NdisClOpenAddressFamily pass an NdisAfHandle pointer to a variable stored in the client-allocated state area at ProtocolAfContext.

NDIS passes the ProtocolAfContext pointer to the client's registered ProtocolClXxx functions in all subsequent calls concerning this address family until the client calls NdisClCloseAddressFamily with the same NdisAfHandle. After the address family is closed, the client can release or reuse the storage it allocated at ProtocolAfContext.

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisClOpenAddressFamilyEx instead. Not applicable for NDIS 5.1 drivers in Windows Vista, but supported for NDIS 5.1 drivers in Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	< DISPATCH_LEVEL.

Partager via