NdisCmRegisterAddressFamily function

项目
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.

NdisCmRegisterAddressFamily registers a set of call manager-supplied functions for connection-oriented communication over a CM-specified address family.

Syntax

NDIS_STATUS NdisCmRegisterAddressFamily(
  _In_ NDIS_HANDLE                        NdisBindingHandle,
  _In_ PCO_ADDRESS_FAMILY                 AddressFamily,
  _In_ PNDIS_CALL_MANAGER_CHARACTERISTICS CmCharacteristics,
  _In_ UINT                               SizeOfCmCharacteristics
);

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 identifying the call manager and the address family it supports for this binding.

The given AddressFamily becomes an input parameter to the ProtocolCoAfRegisterNotify functions of all clients bound to the same connection-oriented miniport driver.
CmCharacteristics [in]
Pointer to an NDIS_CALL_MANAGER_CHARACTERISTICS structure set up by the caller. The structure at CmCharacteristics is defined as follows:
```
typedef struct _NDIS_CALL_MANAGER_CHARACTERISTICS {
    UCHAR  MajorVersion;
    UCHAR  MinorVersion;
    USHORT  Filler;           // reserved for system use
    UINT    Reserved;         // reserved for system use
    CO_CREATE_VC_HANDLER  CmCreateVcHandler;
    CO_DELETE_VC_HANDLER  CmDeleteVcHandler;
    CM_OPEN_AF_HANDLER  CmOpenAfHandler;
    CM_CLOSE_AF_HANDLER  CmCloseAfHandler;
    CM_REG_SAP_HANDLER  CmRegisterSapHandler;
    CM_DEREG_SAP_HANDLER  CmDeregisterSapHandler;
    CM_MAKE_CALL_HANDLER  CmMakeCallHandler;
    CM_CLOSE_CALL_HANDLER  CmCloseCallHandler;
    CM_INCOMING_CALL_COMPLETE_HANDLER
                             CmIncomingCallCompleteHandler;
    CM_ADD_PARTY_HANDLER  CmAddPartyHandler;
    CM_DROP_PARTY_HANDLER  CmDropPartyHandler;
    CM_ACTIVATE_VC_COMPLETE_HANDLER  CmActivateVcCompleteHandler;
    CM_DEACTIVATE_VC_COMPLETE_HANDLER
                             CmDeactivateVcCompleteHandler; 
    CM_MODIFY_CALL_QOS_HANDLER  CmModifyCallQoSHandler;
    CO_REQUEST_HANDLER  CmRequestHandler;
    CO_REQUEST_COMPLETE_HANDLER  CmRequestCompleteHandler;
} NDIS_CALL_MANAGER_CHARACTERISTICS,
                   *PNDIS_CALL_MANAGER_CHARACTERISTICS;
```
The protocol should initialize this structure with zeros before setting up the following members:
- MajorVersion
  Specifies the major version of this structure that the call manager is using. The current value is 0x05.
- MinorVersion
  Specifies the major version of this structure that the call manager is using. The current value is 0x00.
- filler and Reserved
  The caller should ignore these members after zero-initializing this structure.
- CmCreateVcHandler
  Specifies the entry point of the caller's ProtocolCoCreateVc function.
- CmDeleteVcHandler
  Specifies the entry point of the caller's ProtocolCoDeleteVc function.
- CmOpenAfHandler
  Specifies the entry point of the caller's ProtocolCmOpenAf function.
- CmCloseAfHandler
  Specifies the entry point of the caller's ProtocolCmCloseAf function.
- CmRegisterSapHandler
  Specifies the entry point of the caller's ProtocolCmRegisterSap function.
- CmDeregisterSapHandler
  Specifies the entry point of the caller's ProtocolCmDeregisterSap function.
- CmMakeCallHandler
  Specifies the entry point of the caller's ProtocolCmMakeCall function.
- CmCloseCallHandler
  Specifies the entry point of the caller's ProtocolCmCloseCall function.
- CmIncomingCallCompleteHandler
  Specifies the entry point of the caller's ProtocolCmIncomingCallComplete function.
- CmAddPartyHandler
  Specifies the entry point of the caller's ProtocolCmAddParty function.
- CmDropPartyHandler
  Specifies the entry point of the caller's ProtocolCmDropParty function.
- CmActivateVcCompleteHandler
  Specifies the entry point of the caller's ProtocolCmActivateVcComplete function.
- CmDeactivateVcCompleteHandler
  Specifies the entry point of the caller's ProtocolCmDeactivateVcComplete function.
- CmModifyCallQoSHandler
  Specifies the entry point of the caller's ProtocolCmModifyCallQoS function.
- CmRequestHandler
  Specifies the entry point of the caller's ProtocolCoRequest function.
- CmRequestCompleteHandler
  Specifies the entry point of the caller's ProtocolCoRequestComplete function.
SizeOfCmCharacteristics [in]
Specifies the size in bytes of the structure at CmCharacteristics.

Return value

NdisCmRegisterAddressFamily can return any of the following:

Return code	Description
NDIS_STATUS_SUCCESS	The protocol has been registered with NDIS as the call manager for the given address family, so NDIS will call the ProtocolCoAfRegisterNotify functions of all clients that bind themselves to the same NIC driver.
NDIS_STATUS_RESOURCES	The requested operation failed because NDIS could not allocate sufficient memory or initialize the state it uses to track the call manager or this address family
NDIS_STATUS_FAILURE	NDIS failed this call, possibly for one of the following reasons: This caller was not registered as a connection-oriented protocol. The NIC driver to which the caller is bound was not registered as a connection-oriented miniport driver. Another call manager has already registered this address family. The caller supplied invalid or insufficient information at CmCharacteristics. The caller's binding is being closed.

NDIS_STATUS_SUCCESS

The protocol has been registered with NDIS as the call manager for the given address family, so NDIS will call the ProtocolCoAfRegisterNotify functions of all clients that bind themselves to the same NIC driver.

NDIS_STATUS_RESOURCES

The requested operation failed because NDIS could not allocate sufficient memory or initialize the state it uses to track the call manager or this address family

NDIS_STATUS_FAILURE

NDIS failed this call, possibly for one of the following reasons:

This caller was not registered as a connection-oriented protocol.
The NIC driver to which the caller is bound was not registered as a connection-oriented miniport driver.
Another call manager has already registered this address family.
The caller supplied invalid or insufficient information at CmCharacteristics.
The caller's binding is being closed.

Remarks

Only stand-alone call managers, which register themselves as NDIS protocol drivers with NdisRegisterProtocol, also call NdisCmRegisterAddressFamily. Such a driver calls NdisCmRegisterAddressFamily from its ProtocolBindAdapter function to register itself on a particular binding with NDIS.

A stand-alone call manager's ProtocolBindAdapter function first establishes the binding to the underlying miniport driver with NdisOpenAdapter before it calls NdisCmRegisterAddressFamily. Each time NDIS calls ProtocolBindAdapter with another BindContext handle, this call manager function establishes a binding and registers an address family that it supports. In other words, a stand-alone call manager eventually registers an address family and reregisters its ProtocolCm/CoXxx functions for each NIC on which it provides call-management services to connection-oriented clients. The call manager can support more than one address family across all the NIC drivers to which it is bound. The call manager can also support more than one address family on a single NIC to which it is bound. In this case, however, the call manager must register the same entry points for each address family on the binding. Only one call manager can support a particular type of address family for clients bound to any particular NIC driver.

In effect, such a protocol driver both registers itself as a stand-alone call manager and advertises its specific signaling services for all clients bound to the same miniport driver when it calls NdisCmRegisterAddressFamily. After its ProtocolBindAdapter returns control with a successful registration as a stand-alone call manager, NDIS calls the ProtocolCoAfRegisterNotify functions of all clients bound to the same miniport driver. These clients, in turn, cause NDIS to call the ProtocolCmOpenAf function that the call manager just registered for the address family.

A stand-alone call manager must set every CmXxx member in the NDIS_CALL_MANAGER_CHARACTERISTICS structure to a driver-supplied ProtocolCm/CoXxx function when it calls NdisCmRegisterAddressFamily, 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 call manager does not support, its ProtocolCmXxx functions simply return NDIS_STATUS_NOT_SUPPORTED.

After a stand-alone call manager calls NdisCmRegisterAddressFamily successfully, NDIS ignores any entry point(s) that the CM previously specified in the RequestHandler and RequestCompleteHandler members of the NDIS_PROTOCOL_CHARACTERISTICS structure that it passed to NdisRegisterProtocol.

By contrast to stand-alone call managers, a connection-oriented miniport driver that provides integrated call-management support, also called an MCM driver, would call NdisMCmRegisterAddressFamily to register its ProtocolCmXxx and ProtocolCoXxx driver functions with NDIS. Such a miniport driver never calls NdisRegisterProtocol or NdisOpenAdapter.

Callers of NdisCmRegisterAddressFamily usually run at IRQL = PASSIVE_LEVEL and in the context of a system thread. NdisCmRegisterAddressFamily must be called at IRQL < DISPATCH_LEVEL.

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisCmRegisterAddressFamilyEx 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 Remarks section)