PROTOCOL_CL_REGISTER_SAP_COMPLETE callback function (ndis.h)

Article
10/21/2021

A connection-oriented NDIS client that accepts incoming calls must have a ProtocolClRegisterSapComplete function to complete the asynchronous operations that it initiates with NdisClRegisterSap. Otherwise, such a protocol driver's registered ProtocolClRegisterSapComplete function can simply return control.

Note You must declare the function by using the PROTOCOL_CL_REGISTER_SAP_COMPLETE type. For more information, see the following Examples section.

Syntax

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

Parameters

[in] Status

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.

[in] ProtocolSapContext

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.

[in] Sap

Pointer to the client-allocated buffer containing the specification for the SAP to be opened. The client originally passed this pointer to NdisClRegisterSap.

[in] NdisSapHandle

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 ProtocolClOpenAfCompleteEx 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 proceeding 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.

Examples

To define a ProtocolClRegisterSapComplete function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a ProtocolClRegisterSapComplete function that is named "MyClRegisterSapComplete", use the PROTOCOL_CL_REGISTER_SAP_COMPLETE type as shown in this code example:

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

The PROTOCOL_CL_REGISTER_SAP_COMPLETE function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the PROTOCOL_CL_REGISTER_SAP_COMPLETE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported for NDIS 6.0 and NDIS 5.1 drivers (see ProtocolClRegisterSapComplete (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see ProtocolClRegisterSapComplete (NDIS 5.1)) in Windows XP.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL