Telephony Services for NT requires Drivers to export two functions that the Tserver will use to load and unload the Driver; tdiStartDriver() and
tdiStopDriver(). This allows the Tserver to load or map the Driver into its address space and then start the Driver. For those porting a Driver from NetWare the tdiStartDriver() function is the Driver's main() function which was run as a result of the load nlm console command. The tdiStopDriver() function is the Driver's unload function which was run as a result of the unload nlm console command.
The reason for these new functions is to allow the Tserver to map the driver into its address space and start up the driver while still being able to process other requests. The Tserver will take the driver name (including the extension, e.g., sim.dll) and call LoadLibraryEx() with this name. The operating system will map this driver into the same address space of the Tserver executable and will cause the Driver to receive a DLL_PROCESS_ATTACH message. If the Driver were to perform its complete initialization at this point the Tserver would be blocked waiting for the Driver to finish. It would also not know if the Driver initialization failed. The handling of a Driver failing to start up is discussed below. It is requested that the Driver do very little when it receives the DLL_PROCESS_ ATTACH message; perhaps just initialize some variables. If the
LoadLibraryEx() succeeds the Tserver will spawn a thread to call the Driver's tdiStartDriver() function.
The Tserver will call the tdiStopDriver() function when the administrator requests an unload of a driver or if the Tserver service is being stopped. This function tells the Tserver when the Driver is completely gone so that the Tserver can then free or unmap this library.
‘‘Coding Examples’’ on page 7-8 contains coding examples for supporting these new functions.
tdiStartDriver()
This function allows the Tserver to start the Driver automatically when the Tserver service is started or when the administrator manually loads a Driver. It should not return until the Driver has completely initialized and is ready to process requests or it should return if the Driver has encountered an error that prevents it from initializing successfully.
Syntax
Boolean tdiStartDriver( void );
Return Values
This function returns TRUE when the Driver has successfully completed its initialization. A return code of FALSE indicates that the Driver could not load properly. If the Driver fails to load properly the Tserver will call the Driver's
tdiStopDriver() function. It must do this to ensure that all of the Driver's threads are gone before it can free or unmap the driver from the address space. The Driver can cause the Tserver to abnormally terminate if it still has something running after the Tserver frees it (using FreeLibrary()).
tdiStopDriver()
This function allows the Tserver to stop the Driver when the Tserver service is stopping or when the administrator manually unloads a Driver. It should not return until the Driver has completely unloaded or it should return if the Driver has encountered an error that prevents it from stopping successfully.
Syntax
Boolean tdiStopDriver( void );
Return Values
This function returns TRUE when the Driver has successfully unloaded, meaning that all of its threads are gone and all of its resources have been deallocated. At this point the Tserver can unmap the Driver from the address space by calling
FreeLibrary(). It is very important that the Driver does not return TRUE if any of its threads are still running. If the Driver has something running after the Tserver frees it, the Tserver service will abnormally terminate.
A return code of FALSE indicates that the Driver could not unload properly. If the Driver fails to unload properly the Tserver will not free the library in case there is still something running in the Driver. The Tserver will place an error message in its Error Log indicating that the Driver failed to unload properly.
tdiDriverUnload
This function allows a Driver to request that the Tserver perform the unload procedure for the Driver. This permits the Driver to exit gracefully in situations where it has encountered a serious error and cannot function properly. Upon receipt of this request, the Tserver will call the Driver's tdiStopDriver()
function and expects it to behave as described in the tdiStopDriver()
manual page.
Syntax
#include <tdi.h>
TdiReturn_t tdiDriverUnload( const char*driver_name );
Parameters
driver_name
This string contains the name of the PBX Driver DLL. It is the same name that is used to load and unload the Driver and must include the extension; for example, "driver.dll". If the Driver installation uses the insttsdr.dll provided by the Telephony Services SDK to put its name into the Tserver's administered list of drivers, use the same name in the call to tdiDriverUnload(). Refer to the SDK for details on how to use this install feature.
Return Values
This function returns TDI_SUCCESS if the Tserver was able to start the unload process by calling the Driver's tdiStopDriver() function. It does not mean that the Driver has returned from its unload function. tdiDriverUnload() returns the following negative value on failure: