ProtocolClRegisterSapComplete (NDIS 5.1) 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.

Connection-oriented NDIS clients that accept incoming calls must have ProtocolClRegisterSapComplete functions to complete the asynchronous operations that they initiate with NdisClRegisterSap. Otherwise, such a protocol driver's registered ProtocolClRegisterSapComplete function can simply return control.

Syntax

VOID ProtocolClRegisterSapComplete(
  _In_ NDIS_STATUS Status,
  _In_ NDIS_HANDLE ProtocolSapContext,
  _In_ PCO_SAP     Sap,
  _In_ NDIS_HANDLE NdisSapHandle
);

Parameters

Status [in]
Specifies the final status of the client's call to NdisClRegisterSap, which can be one of the following:
- NDIS_STATUS_SUCCESS
  The SAP has been registered both with NDIS and the call manager, which will subsequently call NdisCmDispatchIncomingCall whenever it receives an incoming call offer directed to the given SAP, thereby causing NDIS to call the client's ProtocolClIncomingCall function.
- NDIS_STATUS_RESOURCES
  NDIS or the call manager could not allocate and/or initialize necessary resources to register and maintain the SAP.
- NDIS_STATUS_INVALID_DATA
  The client supplied an invalid specification at Sap to NDIS, which it forwarded to the call manager's ProtocolCmRegisterSap function for validation.
- NDIS_STATUS_XXX
  The call manager encountered an error in attempting to register the given SAP and NDIS propagated this CM-determined failure status to the client.
ProtocolSapContext [in]
Specifies the handle to the client's per-SAP context area, which the client originally supplied to NDIS when it called NdisClRegisterSap. If the registration is successful, NDIS retains this context handle and uses it subsequently in calls to the client's ProtocolClIncomingCall function pertaining to this SAP.
Sap [in]
Pointer to the client-allocated buffer containing the specification for the SAP to be opened. The client originally passed this pointer to NdisClRegisterSap.
NdisSapHandle [in]
If Status is NDIS_STATUS_SUCCESS, specifies an NDIS-supplied valid handle to this registered SAP, effectively an association established with NDIS between the client and a particular call manager for the client-specified SAP. Otherwise, this parameter is NULL. The client must save a valid handle, preferably in its ProtocolSapContext area, for an eventual call to NdisClDeregisterSap.

Return value

None

Remarks

NDIS calls ProtocolClRegisterSapComplete to indicate that the client's previous call to NdisClRegisterSap has been processed by NDIS and, if NDIS did not fail the call, by the call manager with which the client shares the NdisAfHandle that it passed to NdisClRegisterSap.

To receive incoming calls through a connection-oriented NIC, a client's ProtocolCoAfRegisterNotify or ProtocolClOpenAfComplete function usually registers one or more SAPs with the call manager.

To register each SAP, the client calls NdisClRegisterSap, passing in the NdisAfHandle that identifies the call manager from which the client wants to receive notifications of incoming calls, and NDIS returns the client an NdisSapHandle to the registered SAP if the client's call to NdisClRegisterSap succeeds. ProtocolClRegisterSapComplete must save each valid NdisSapHandle, usually in the client's per-SAP ProtocolSapContext area so it can release the SAP later with NdisClDeregisterSap.

The format of a SAP is specific to the call manager. If the call manager does not recognize the SAP that the client is attempting to register or if the specified SAP is already in use, the call manager can fail the SAP registration. ProtocolClRegisterSapComplete should check the input Status for NDIS_STATUS_SUCCESS before proceding further. If the attempt to register the SAP failed, ProtocolClRegisterSapComplete can either release the per-SAP context area and buffer at Sap that the client allocated or prepare them for reuse in another call to NdisClRegisterSap.

A client can receive incoming calls on a SAP even while SAP registration is still pending, that is, before its ProtocolClRegisterSapComplete function is called.

Requirements

Target platform	Desktop
Version	See ProtocolClRegisterSapComplete.
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL

Share via