TSPI_providerInit

The TSPI_providerInit function initializes the service provider and gives it parameters required for subsequent operation.

LONG TSPIAPI TSPI_providerInit(
  DWORD dwTSPIVersion,                  
  DWORD dwPermanentProviderID,          
  DWORD dwLineDeviceIDBase,             
  DWORD dwPhoneDeviceIDBase,            
  DWORD_PTR dwNumLines,                     
  DWORD_PTR dwNumPhones,                    
  ASYNC_COMPLETION lpfnCompletionProc,  
  LPDWORD lpdwTSPIOptions               
);

Parameters

dwTSPIVersion

The version of the TSPI definition under which this function must operate. The caller can use TSPI_lineNegotiateTSPIVersion with the special dwDeviceID INITIALIZE_NEGOTIATION to negotiate a version that is guaranteed to be acceptible to the service provider.

dwPermanentProviderID

The permanent identifier, unique within the service providers on this system, of the service provider being initialized.

dwLineDeviceIDBase

The lowest device identifier for the line devices supported by this service provider.

dwPhoneDeviceIDBase

The lowest device identifier for the phone devices supported by this service provider.

dwNumLines

The number of line devices this service provider supports. The value returned is the number of line devices reported in TSPI_providerEnumDevices.

dwNumPhones

The number of phone devices this service provider supports. The value returned is the number of phone devices reported in TSPI_providerEnumDevices.

lpfnCompletionProc

The procedure the service provider calls to report completion of all asynchronously operating procedures on line and phone devices.

lpdwTSPIOptions

A pointer to a DWORD-sized memory location, into which the service provider can write a value specifying LINETSPIOPTIONS_ values. This parameter allows the service provider to return bits indicating optional behaviors desired of TAPI. TAPI sets the options DWORD to 0 before calling TSPI_providerInit, so if the service provider doesn't want any of these options, it can just leave the DWORD set to 0.

At this time, only one bit is defined to be returned through this pointer: LINETSPIOPTION_NONREENTRANT. The service provider sets this bit if it is not designed for fully pre-emptive, multithreaded, multitasking, multiprocessor operation (for example, updating of global data protected by mutexes). When this bit is set, TAPI only makes one call at a time to the service provider; it does not call any other entry point, nor that entry point again, until the service provider returns from the original function call. Without this bit set, TAPI may call into multiple service provider entry points, including multiple times to the same entry point, simultaneously (actually simultaneously in a multiprocessor system).

Important Note It must be emphasized that setting this bit degrades performance. It is strongly recommended that this be used only for development but not a shipped production service provider.

TAPI does not serialize access to TSPI functions that display a dialog box (TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove) so that they do not block other TSPI functions from being called; the service provider must include internal protection on these functions.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Remarks

This function is guaranteed to be called before any of the other functions prefixed with TSPI_line or TSPI_phone except TSPI_lineNegotiateTSPIVersion. It is strictly paired with a subsequent call to TSPI_providerShutdown These pairs may overlap, for example, when the Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier is used while telephony operations are in progress. The call to this function must be ignored (returning success) if there is already an outstanding pair.

A service provider should perform as many consistency checks as is practical at the time. TSPI_providerInit is called to ensure that it is ready to run. Some consistency or installation errors, however, cannot be detected until the operation is attempted. The error LINEERR_NODRIVER can be used to report such nonspecific errors at the time they are detected.

There is no directly corresponding function at the TAPI level. At that level, multiple different usage instances can be outstanding, with an "application handle" returned to identify the instance in subsequent operations. At TSPI level, the interface architecture supports only a single usage instance for each distinct service provider.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later.
  Version: Requires TAPI 2.0 or later.
  Header: Declared in Tspi.h.

See Also

TSPI_lineNegotiateTSPIVersion, TSPI_providerShutdown, TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove