TSPI_providerRemove 函数 (tspi.h)

项目
08/26/2023

TSPI_providerRemove 函数已过时。 TAPI 版本 1.4 或更早版本的服务提供商可以实现此 TSPI 函数。 TAPI 版本 2.0 或更高版本的 TSP 实现 TUISPI_providerRemove。

TSPI_providerRemove函数要求用户确认取消服务提供商。服务提供商负责删除服务提供商在 addProvider 时间添加的任何注册表项，以及不再需要的任何其他模块和文件。

语法

LONG TSPIAPI TSPI_providerRemove(
  HWND  hwndOwner,
  DWORD dwPermanentProviderID
);

参数

hwndOwner

父窗口的句柄，函数可在其中创建删除期间所需的任何对话框窗口。

dwPermanentProviderID

服务提供商的永久提供程序标识符。

返回值

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

LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_NOMEM、LINEERR_INVALPARAM。

注解

此函数必须保证如果服务提供程序返回成功，则会从注册表中删除服务提供商的节和针对服务提供商的专用定义信息。具体而言，必须删除其 PPID> 与 dwPermanentProviderID 匹配的 <[Provider<PPID>] 部分，包括其 NumLines 和 NumPhones 条目。如果函数返回成功，则调用方负责从 [Providers] 节中删除匹配的 ProviderIDx 和 ProviderFilenamex 条目，并相应地对 [Providers] 节中的剩余条目重新编号。

此过程必须使系统保持一致状态。它应运行到完成状态，不允许用户在部分完成删除时中止删除。如果删除失败，提供商有责任“收回”已完成的工作并返回错误。这可能意味着在删除开始之前进行预扫描以验证是否可以完全删除。

当服务提供程序正在使用 (时，可以在 TSPI_providerInit 和 TSPI_providerShutdown) 之间调用此函数。如果发生这种情况，服务提供商应适当地组合显示用户对话框来宣布任何冲突并确认删除，将删除选项限制为可以透明执行的选项，或者发出 LINE_CLOSE 和 PHONE_CLOSE 消息，以通知 TAPI 和应用程序受影响的设备已被强行关闭以便删除。在任何情况下，影响通过 TSPI 可见的行为的任何更改都应仅在服务提供程序在下一 TSPI_providerShutdown关闭时才生效。

此函数不应返回由于应用程序正在使用提供程序而可能发生LINEERR_INUSE或其他错误;相反，提供程序应直接与用户讨论此问题，然后返回LINEERR_OPERATIONFAILED如果用户决定中止操作。

在删除服务提供程序时，此过程只调用一次，直到调用 TSPI_providerInstall。调用方负责确保这一点。

在版本 1.4 及更早版本中，随 Windows Telephony 提供的 Telephony 控制面板实用工具调用此函数 (满足外部序列要求，如此处所述，在调用“remove”命令时) 。

TAPI 级别没有相应的函数。在该级别，应用程序预期已安装服务提供商;否则，它们的线路和电话不会显示在可用的设备标识符序列中。正在运行的应用程序通过LINE_LINEDEVSTATE或PHONE_STATE消息中的LINEDEVSTATE_REINIT或PHONESTATE_REINIT值来通知动态重新配置（包括删除服务提供商）。