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

NdisMCmRegisterAddressFamily registers a set of call manager functions for connection-oriented communication over an MCM-driver-specified address family.

Syntax

NDIS_STATUS NdisMCmRegisterAddressFamily(
  _In_ NDIS_HANDLE                        MiniportAdapterHandle,
  _In_ PCO_ADDRESS_FAMILY                 AddressFamily,
  _In_ PNDIS_CALL_MANAGER_CHARACTERISTICS CmCharacteristics,
  _In_ UINT                               SizeOfCmCharacteristics
);

Parameters

MiniportAdapterHandle [in]
Specifies an NDIS-supplied handle identifying the miniport driver's NIC. This handle is an input parameter to the NIC driver' s MiniportInitialize function, which calls NdisMCmRegisterAddressFamily.
AddressFamily [in]
Pointer to a structure of type CO_ADDRESS_FAMILY identifying the address family the MCM driver supports.

The given AddressFamily becomes an input parameter to the ProtocolCoAfRegisterNotify functions of all clients bound to this MCM 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 MCM driver should initialize this structure with zeros before setting up the following members:
- MajorVersion
  Specifies the major version of this structure. The current version is 0x05.
- MinorVersion
  Specifies the minor version of this structure. The current version 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

NdisMCmRegisterAddressFamily can return any of the following:

Return code	Description
NDIS_STATUS_SUCCESS	The miniport driver 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 this MCM driver.
NDIS_STATUS_RESOURCES	The requested operation failed because NDIS could not allocate sufficient memory or initialize the state it uses to track the MCM driver as a call manager of this address family.
NDIS_STATUS_FAILURE	NDIS failed this call, possibly for one of the following reasons: The caller was not registered as a connection-oriented miniport driver. The caller-supplied invalid or insufficient information at CmCharacteristics.

NDIS_STATUS_SUCCESS

The miniport driver 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 this MCM driver.

NDIS_STATUS_RESOURCES

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

NDIS_STATUS_FAILURE

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

The caller was not registered as a connection-oriented miniport driver.
The caller-supplied invalid or insufficient information at CmCharacteristics.

Remarks

Drivers that control a connection-oriented NIC for which there is no medium-type-specific stand-alone call manager in the system also call NdisMCmRegisterAddressFamily after calling NdisMRegisterMiniport. The driver of any NIC that has on-board connection-oriented signaling support can register itself as an MCM driver for better performance in managing calls. Registering as an MCM driver displaces any stand-alone call manager with the NIC driver's own call-management support.

For example, because the system provides a stand-alone call manager for all ATM NIC drivers, a NIC driver that reports its medium as NdisMediumAtm is unlikely to call NdisMCmRegisterAddressFamily. However, such an ATM NIC driver might call NdisMCmRegisterAddressFamily if its adapter had on-board connection-oriented signaling support.

An MCM driver calls NdisMCmRegisterAddressFamily from its MiniportInitialize function to register itself as a call manager with NDIS, after it has determined that its NIC is fully operational so the driver can carry out network I/O operations. In effect, such an MCM driver registers itself as a call manager and advertises its specific signaling services for all clients that subsequently bind themselves to the same NIC when MiniportInitialize calls NdisMCmRegisterAddressFamily.

After MiniportInitialize returns control with a successful registration as a call manager, NDIS calls the ProtocolBindAdapter functions of potential clients and, then, the ProtocolCoAfRegisterNotify functions of all clients that bind themselves to the MCM driver's NIC. These clients, in turn, cause NDIS to call the ProtocolCmOpenAf function that the MCM driver just registered for its address family.

The MCM driver must set every CmXxx member in the NDIS_CALL_MANAGER_CHARACTERISTICS structure to a caller-supplied ProtocolCm/CoXxx function when it calls NdisMCmRegisterAddressFamily, even if it does not support incoming calls, outgoing calls, or point-to-multipoint connections. For whatever subset of connection-oriented functionality that such an MCM driver does not support, its ProtocolCmXxx functions simply return NDIS_STATUS_NOT_SUPPORTED. For example, NDIS never calls an MCM driver's registered ProtocolCmActivateVcComplete or ProtocolCmDeactivateVcComplete function, so these can just return NDIS_STATUS_NOT_SUPPORTED but be placeholders in the characteristics structure.

An MCM driver must have ProtocolCoCreateVc and ProtocolCoDeleteVc functions and set their entry points in the NDIS_CALL_MANAGER_CHARACTERISTICS structure passed to NdisMCmRegisterAddressFamily. If the driver previously registered a MiniportCoCreateVc or MiniportCoDeleteVc function when it called NdisMRegisterMiniport, NDIS ignores these entry points after the MCM driver's call to NdisMCmRegisterAddressFamily. Whenever NDIS calls the MCM driver to create or delete a VC subsequently, NDIS passes in an NdisAfHandle as the initial parameter to the miniport driver-supplied ProtocolCoCreateVc or MiniportCoDeleteVc function, rather than the MiniportAdapterContext handle passed in to the MiniportCoCreateVc or MiniportCoDeleteVc function of a stand-alone miniport driver.

An MCM driver cannot set the CmRequestHandler member to its MiniportCoRequest function but must provide a separate ProtocolCoRequest function when it calls NdisMCmRegisterAddressFamily. Even if such a driver already supplied entry points for its MiniportCoRequest, MiniportQueryInformation, and MiniportSetInformation functions when it called NdisMRegisterMiniport, an MCM driver must have a discrete ProtocolCoRequest function to handle CM-specific requests from clients. For MCM drivers, NDIS calls such a set of driver-supplied request handler(s) according to the following policies:

When a bound protocol driver calls NdisRequest, NDIS calls the NIC driver's MiniportQueryInformation or MiniportSetInformation function, depending on the given RequestType value, if the NIC driver registered these functions with NdisMRegisterMiniport. Otherwise, NDIS calls the NIC driver's registered MiniportCoRequest function.
When a bound protocol driver calls NdisCoRequest with a NULLNdisAfHandle, NDIS calls the NIC driver's registered MiniportCoRequest function. Otherwise, NDIS calls the driver-supplied ProtocolCoRequest function that was set in the CmRequestHandler member when the MCM driver called NdisMCmRegisterAddressFamily.

An MCM driver also must have a ProtocolCoRequestComplete function to handle asynchronous completions of its subsequent calls to NdisMCmRequest.

An MCM driver can support more than one address family on a single NIC to which it is bound. The MCM driver must call NdisCmRegisterAddressFamily once for each address family that it registers on the binding and register the same entry points for each address family on the binding. Only one MCM driver can support a particular type of address family for clients bound to any particular NIC driver.

By contrast to MCM drivers, a stand-alone call manager, which usually provides call-management support to clients that depend on several NIC drivers, would call NdisCmRegisterAddressFamily to register its ProtocolCmXxx and ProtocolCoXxx driver functions with NDIS.

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

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMCmRegisterAddressFamilyExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL (See Remarks section)