phoneInitialize 函数 (tapi.h)

项目
08/26/2023

phoneInitialize 函数已过时。 Tapi.dll 和 Tapi32.dll 继续导出它，以便与使用 TAPI 版本 1.3 和 1.4 的应用程序向后兼容。

使用 TAPI 版本 2.0 或更高版本的应用程序必须改用 phoneInitializeEx 。

对于 TAPI 版本 1.4 及更早版本： phoneInitialize 函数初始化应用程序对 TAPI 的使用，以便在电话 API 中后续使用电话函数。它注册应用程序的指定通知机制，并返回应用程序可用的电话设备数。

语法

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

参数

lphPhoneApp

指向用 TAPI 的应用程序使用句柄填充的位置的指针。

hInstance

客户端应用程序或 DLL 的实例句柄。

lpfnCallback

调用的回调函数的地址，用于确定电话设备上的状态和事件。

lpszAppName

指向包含可显示字符的 以 null 结尾的字符串的指针。如果此参数为非 NULL，则包含应用程序提供的应用程序名称。此名称在 PHONESTATUS 结构中提供，以用户友好的方式指示哪个应用程序是电话设备的当前所有者。此信息可用于日志记录和状态报告目的。如果 lpszAppName 为 NULL，则改用应用程序的文件名。

lpdwNumDevs

指向 DWORD 的指针。此位置将加载应用程序可用的电话设备数。

返回值

如果请求成功，则返回零;如果发生错误，则返回负错误号。可能的返回值为：

PHONEERR_INVALAPPNAME、PHONEERR_INIFILECORRUPT、PHONEERR_INVALPOINTER、PHONEERR_NOMEM、PHONEERR_OPERATIONFAILED、PHONEERR_REINIT、PHONEERR_RESOURCEUNAVAIL、PHONEERR_NODEVICE、PHONEERR_NODRIVER、PHONEERR_INVALPARAM

注解

应用程序可以使用从零到 dwNumDevs 减 1 的电话设备标识符来引用单个电话设备。如果不首先使用 phoneGetDevCaps 函数查询其设备功能，应用程序不应假定这些电话设备能够执行辅助电话子集所指定内容以外的任何功能。

应用程序不应调用 phoneInitialize 而不随后打开电话 (至少用于监视) 。如果应用程序未监视且未使用任何设备，则应调用 phoneShutdown ，以便在不需要时释放 TAPI 分配的内存资源，并且 TAPI 本身可以在不需要的情况下从内存中卸载。

执行 phoneShutdown 的另一个原因是，如果用户更改设备配置 (添加或删除线路或电话) ，TAPI 无法通知当时已打开线路或电话句柄的应用程序。重新配置导致发送PHONESTATE_REINIT消息后，所有应用程序都无法打开设备，直到所有应用程序都执行 phoneShutdown。

如果任何服务提供商无法正确初始化， phoneInitialize 函数将失败并返回服务提供商指示的错误。如果返回PHONEERR_INVALPARAM错误值，则指定的 hInstance 参数无效。