Setting Up Handles (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.
After the NDISTAPI driver has initialized an NDIS WAN miniport driver as a provider, the miniport driver can expect a request to open a line device at its MiniportQueryInformationfunction specifying OID_TAPI_OPENand the appropriate parameters. Upon receiving an open request the miniport driver would typically do the following:
Mark the line device as open in the miniport driver's internal data structures.
Save the NDISTAPI driver's handle to the line device (passed in the htLine member), which is to be used in subsequent event notifications.
Return its own handle to the line device (passed back in the hdLine member).
Once again, the impetus for this request would be a client process calling lineOpen.
After a client process has successfully opened a line, it can place a call on that line by calling lineMakeCall. This will result in the NDISTAPI driver's calling NdisRequest with an OID_TAPI_MAKE_CALL, specifying the NDISTAPI-supplied handle to the line in the htLine member, and the NDISTAPI-supplied handle to the call in the htCallmember. This request is passed to the miniport driver's MiniportQueryInformationfunction, specifying OID_TAPI_MAKE_CALL. If the NIC driver can successfully create the call, it passes back its own handle to the call in the hdCall member.
The two-stage htXxx/hdXxx ("handle of TAPI object Xxx/handle of Driver object Xxx") handle scheme provides both the NDISTAPI driver and the NDIS WAN miniport driver the flexibility of defining their own means of reference for the same logical object. Requests made to NIC drivers specify driver handles ( hdLine and hdCall), while notifications made to the NDISTAPI driver contain TAPI handles ( htLines and htCalls). In the already mentioned cases where the miniport driver is defining its driver handle to some object (for example, hdLine, hdCall), it is typically to the advantage of the NIC driver to specify a pointer to the appropriate driver-internal data structure that represents the object.
When the client process has finished with the call it will call lineDrop to drop the call, and then lineDeallocateCall to free the call instance. This will result in the NDISTAPI driver sending two more requests, OID_TAPI_DROPand OID_TAPI_CLOSE_CALL, respectively, through NDISWAN to the NDIS WAN miniport driver to drop the call and deallocate the call instance. It is also possible that the miniport driver will get an OID_TAPI_CLOSE_CALL request without a preceding OID_TAPI_DROP, in which case the miniport driver should drop the call and deallocate the call instance as if it had received both OIDs.
Finally, when the last TAPI client has called lineClose, the NDISTAPI driver will call NdisRequestto send the miniport driver an OID_TAPI_CLOSErequest at its MiniportSetInformationfunction. An OID_TAPI_CLOSE can also be received on an active line. In this case, the miniport driver must complete or abort all outstanding calls and asynchronous requests on the device and close the line. An OID_TAPI_CLOSE request with a valid hdLine cannot be failed.