NdisClRegisterSap function (ndis.h)

NdisClRegisterSap registers a SAP on which the client can receive incoming calls from a remote node.

Syntax

NDIS_STATUS NdisClRegisterSap(
  [in]  NDIS_HANDLE  NdisAfHandle,
  [in]  NDIS_HANDLE  ProtocolSapContext,
  [in]  PCO_SAP      Sap,
  [out] PNDIS_HANDLE NdisSapHandle
);

Parameters

[in] NdisAfHandle

Specifies the handle returned by NdisClOpenAddressFamilyEx, which implicitly identifies the call manager with which to register the SAP.

[in] ProtocolSapContext

Specifies the handle to a caller-supplied resident context area in which the client maintains state for this SAP after it has been opened. NDIS passes this handle back to the client in all subsequent calls concerning this SAP if the call to NdisClRegisterSap succeeds.

[in] Sap

Pointer to a client-supplied specification for the SAP to be opened, formatted as a structure of type CO_SAP.

[out] NdisSapHandle

Pointer to a variable in which a handle to the newly registered SAP is returned if this call succeeds.

Return value

When NdisClRegisterSap returns anything other than NDIS_STATUS_PENDING, the client should make an internal call to its ProtocolClRegisterSapComplete function. Otherwise, NDIS calls the client's ProtocolClRegisterSapComplete function when this operation is completed.

Remarks

With a call to NdisClRegisterSap, a client requests notifications of incoming calls on a particular SAP. NDIS forwards the given SAP information to the call manager's ProtocolCmRegisterSap function for validation. If the given SAP is already in use or if the call manager does not recognize the client-supplied specification at Sap, the call manager fails this request.

SAP format is medium-dependent and specific to the address family supported by the call manager, which uses registered SAPs subsequently to route incoming calls to the appropriate client. A call manager can register SAPs for established PVCs without contacting other network components, depending on the underlying medium.

If its call to NdisClRegisterSap succeeds, the client must save the handle returned at NdisSapHandle because it is a required parameter to NdisClDeregisterSap. Callers of NdisClRegisterSap usually pass a pointer to a variable in the client-allocated state area at ProtocolSapContext so that NDIS can set it to the NdisSapHandle if this call succeeds. NDIS passes the given ProtocolSapContext to the client's registered ProtocolCl/CoXxx functions in all subsequent calls concerning this SAP until the client calls NdisClDeregisterSap.

Usually, a client calls NdisClRegisterSap from its ProtocolAfRegisterNotify function following its successful call to NdisClOpenAddressFamilyEx. Registering one or more SAPs allows the client to receive its incoming call(s) as soon as the call manager receives them over the network.

By contrast with client-initiated outgoing calls, a client does not call NdisCoCreateVc before it calls NdisClRegisterSap. For incoming calls, the call manager initiates the creation of the VC, as follows:

• On receipt of an incoming call on a registered SAP, the call manager first calls NdisCoCreateVc, causing NDIS to call the client's ProtocolCoCreateVc function.
• When the VC has been set up and activated, the call manager calls NdisCmDispatchIncomingCall, causing NDIS to call the client's ProtocolClIncomingCall function.

Requirements

See also

CO_SAP

NdisClDeregisterSap

NdisClMakeCall

NdisCmDispatchIncomingCall

NdisCoCreateVc

ProtocolClIncomingCall

ProtocolCmRegisterSap

ProtocolCoAfRegisterNotify

ProtocolCoCreateVc