TSPI_providerInit函数 (tspi.h)

项目
08/26/2023

TSPI_providerInit 函数初始化服务提供程序，并为其提供后续操作所需的参数。

语法

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

参数

dwTSPIVersion

此函数必须在其下运行的 TSPI 定义的版本。调用方可以将 TSPI_lineNegotiateTSPIVersion 与特殊的 dwDeviceIDINITIALIZE_NEGOTIATION 一起使用，以协商保证服务提供商可接受的版本。

dwPermanentProviderID

正在初始化的服务提供商的永久标识符，在此系统上的服务提供程序中是唯一的。

dwLineDeviceIDBase

此服务提供商支持的线路设备的最低设备标识符。

dwPhoneDeviceIDBase

此服务提供商支持的电话设备的最低设备标识符。

dwNumLines

此服务提供商支持的线路设备数。返回的值是 TSPI_providerEnumDevices中报告的线路设备数。

dwNumPhones

此服务提供商支持的电话设备数。返回的值是 TSPI_providerEnumDevices中报告的电话设备数。

lpfnCompletionProc

服务提供商调用的过程，以报告线路和电话设备上所有异步操作过程的完成情况。

lpdwTSPIOptions

指向 DWORD 大小的内存位置的指针，服务提供商可以在其中写入指定LINETSPIOPTIONS_值的值。此参数允许服务提供商返回指示 TAPI 所需可选行为的位。 TAPI 在调用TSPI_providerInit之前将选项 DWORD 设置为 0，因此如果服务提供商不需要这些选项中的任何一个，则只需将 DWORD 设置为 0 即可。

目前，仅定义一个要通过此指针返回的位：LINETSPIOPTION_NONREENTRANT。如果服务提供程序不设计用于完全抢占式、多线程、多任务、多处理器操作 (例如，更新受互斥) 保护的全局数据，则服务提供程序会设置此位。设置此位后，TAPI 一次只向服务提供商发出一次调用;在服务提供商从原始函数调用返回之前，它不会再次调用任何其他入口点，也不会再次调用该入口点。如果不设置此位，TAPI 可能会调用多个服务提供商入口点，包括多次调用同一入口点，同时 (实际上同时在多处理器系统中) 。

注意重要提示： 必须强调，设置此位会降低性能。强烈建议将其仅用于开发，而不用于已交付的生产服务提供商。

TAPI 不会序列化对显示对话框的 TSPI 函数的访问，这些函数 ( TUISPI_lineConfigDialog、TUISPI_lineConfigDialogEdit、TUISPI_phoneConfigDialog、TUISPI_providerConfig、TUISPI_providerInstall 、TUISPI_providerRemove) ，这样它们就不会阻止调用其他 TSPI 函数;服务提供商必须包括对这些函数的内部保护。

返回值

如果函数成功，则返回零;如果发生错误，则返回错误号。可能的返回值如下所示：

LINEERR_INCOMPATIBLEAPIVERSION、LINEERR_OPERATIONFAILED、LINEERR_NOMEM、LINEERR_RESOURCEUNAVAIL、LINEERR_INIFILECORRUPT、LINEERR_NOMULTIPLEINSTANCE。

注解

保证在除TSPI_lineNegotiateTSPIVersion以外的任何以 TSPI_line 或 TSPI_phone 为前缀的其他函数之前调用此函数。它与后续调用TSPI_providerShutdown这些对可能会重叠，例如，在进行电话服务操作时，使用 1.4 及更早版本中 Windows 电话提供的电话控制面板实用工具。如果已有未完成的对，则必须忽略对此函数的调用， (返回成功) 。

服务提供商应执行与当时实际次数相同的一致性检查。 调用TSPI_providerInit 以确保它已准备好运行。但是，在尝试操作之前，无法检测到某些一致性或安装错误。错误LINEERR_NODRIVER可用于在检测到此类非特定错误时报告这些错误。

TAPI 级别没有直接对应的函数。在该级别，多个不同的使用情况实例可能未完成，并返回“应用程序句柄”以在后续操作中标识该实例。在 TSPI 级别，接口体系结构仅支持每个不同服务提供商的单个使用实例。