Call Line Shutdown (NDIS 5.1)
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.
A session begins when an NDIS WAN miniport driver successfully completes an OID_TAPI_PROVIDER_INITIALIZErequest. Within a session, one or more lines can be opened with an OID_TAPI_OPENrequest, and on a line, one or more calls can be established by OID_TAPI_MAKE_CALL, OID_TAPI_DIAL, or OID_TAPI_ANSWERrequests. During the time a line is up, many calls can be established and then closed or dropped. During a session, one or more lines can go through transitions from open to closed many times. How a miniport driver handles such transitions is described here.
Closing a Call (NDIS 5.1)
An in-process call can be closed either by the local node or by the remote node. The call can be closed on the local node, either because the last application with a handle to the call has closed the handle, or perhaps because the miniport driver's MiniportHaltor MiniportResethas been called. If the remote node hangs up an in-process call, the miniport driver must indicate this status change to upper layers.
If an application on the local node closes the call, MiniportSetInformationwill be called either with an OID_TAPI_DROPrequest followed by an OID_TAPI_CLOSE_CALL, or it will simply be called with an OID_TAPI_CLOSE_CALL.
If the miniport driver receives an OID_TAPI_DROP request, the driver must:
Drop the call.
Change the status of the call to LINECALLSTATE_IDLE
Report the state change by calling NdisMIndicateStatus.
The handles for the dropped call, htCalland hdCallremain valid. The miniport driver must not deallocate, reuse, or otherwise modify the state associated with the hdCallthat it created for the call instance, since the miniport driver can receive queries related to the call, for example, a request for statistics related to the call. If MiniportHaltor MiniportResetis called, the miniport driver should disconnect the call but retain the state maintained for the call instance until the miniport driver receives an OID_TAPI_CLOSE_CALL request.
MiniportSetInformationcan also receive an OID_TAPI_CLOSE_CALL request when the last application with an open handle to the call instance closes the handle. The miniport driver cannot fail this close call request. After MiniportSetInformationreturns after processing this request, htCallis no longer valid.
A miniport driver must be prepared to handle timing issues involving such occurrences as getting an OID_TAPI_CLOSE_CALL before getting an OID_TAPI_DROP. If the miniport driver gets an OID_TAPI_CLOSE_CALL without a preceding OID_TAPI_DROP, it should behave as if it had received both a drop and a close call request. If the miniport driver receives a drop after a close call request has already closed the referenced call, the call handle is no longer valid and the miniport driver should return an appropriate error message.
If the miniport driver detects that the remote node has dropped the call, the miniport driver should change the call state to LINECALLSTATE_DISCONNECTED and indicate the change by calling NdisMIndicateStatuspassing the htCallfor this call instance. After the state change is propagated to the connected application on the local node, the miniport driver will receive an OID_TAPI_DROP followed by an OID_TAPI_CLOSE_CALL, or perhaps just the OID_TAPI_CLOSE_CALL request. The miniport driver should handle the drop and close call requests as described earlier.
Closing a Line (NDIS 5.1)
A line is closed when the last application with an open handle to the line has closed the handle. When the miniport driver subsequently receives an OID_TAPI_CLOSE, it should tear down the line instance, that is, any state related to the line maintained by the miniport driver can be reused or deallocated because the information is no longer valid.
An OID_TAPI_CLOSE call must succeed if the line handle, htLine, passed in the call exists and is still valid. A miniport driver will never receive an OID_TAPI_CLOSE request for a line if there are calls on the line. All existing calls on a line will be closed with an OID_TAPI_CLOSE_CALLrequest before the line-close request is made.
Existing calls must be closed when a line is closed; the miniport driver should drop those calls and clean up their state. The miniport driver should also change the state of the line to idle. Any handle that the miniport driver has for the line is no longer valid. If the miniport driver receives any requests which pass the htLinehandle or any htCallafter the close request is received, such request(s) must be failed with an appropriate status.
Closing a Session (NDIS 5.1)
Session termination can be initiated by either the upper layers or a WAN miniport driver. When the last client process has detached from the higher-level Telephony module, the NDISTAPI driver will be informed that it needs to terminate its session with each of the registered adapters. The NDISTAPI driver does this by calling NdisRequestspecifying OID_TAPI_PROVIDER_SHUTDOWN. Upon receiving this request, NDISWAN will call the miniport driver's MiniportSetInformationfunction, which should terminate any related activities it has in progress on the specified adapter and release any relevant resources.
Driver-initiated session termination can occur when the miniport driver is being unloaded in its MiniportHaltfunction. Typically, the miniport driver would complete any outstanding NDISTAPI driver requests and notify the NDISWAN that its line devices are going off-line by calling NdisMIndicateStatus. NDISWAN would, in turn, call the NDISTAPI driver to deregister the adapter. If the miniport driver were reloaded again later, it would go through the same initialization process described previously.
The NDIS WAN miniport driver might also initiate session termination if it underwent some dynamic reconfiguration that necessitated a complete reinitialization of all clients and drivers. For example, if an adapter's line-device modeling (for example, the number of line devices supported) was changed on the fly, the miniport driver would call NdisMIndicateStatuswith a LINE_LINEDEVSTATE event and the LINEDEVSTATE_REINIT flag set.