NdisClOpenAddressFamily function
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. |
See also
NdisAllocateFromNPagedLookasideList
ProtocolClDeregisterSapComplete
ProtocolClIncomingCallQoSChange
ProtocolClModifyCallQoSComplete