phoneInitializeExA 函数（tapi.h）

项目
11/20/2024

phoneInitializeEx 函数初始化应用程序对 TAPI 的使用，以便后续使用手机抽象。它注册应用程序的指定通知机制，并返回应用程序可用的电话设备数。电话设备是提供电话 API 中电话前缀功能的实现的任何设备。

语法

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

参数

lphPhoneApp

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

hInstance

客户端应用程序或 DLL 的实例句柄。应用程序或 DLL 可以为此参数传递 NULL，在这种情况下，TAPI 使用进程的根可执行文件的模块句柄。

lpfnCallback

当应用程序使用事件通知的“隐藏窗口”方法（有关详细信息，请参阅 phoneCallbackFunc）时调用的回调函数的地址，用于确定线路设备、地址或调用上的状态和事件。忽略此参数，当应用程序选择使用“事件句柄”或“完成端口”事件通知机制时，应设置为 NULL。

lpszFriendlyAppName

指向仅包含可显示字符的 null终止字符串的指针。如果此参数未 NULL，则它包含应用程序提供的名称。此名称在 PHONESTATUS 结构中提供，以用户友好的方式指示应用程序拥有电话设备的所有权。如果 lpszFriendlyAppNameNULL，则改用应用程序的模块文件名（如函数 GetModuleFileName返回）。

lpdwNumDevs

指向 DWORD的指针。成功完成此请求后，此位置将填充应用程序可用的电话设备数。

lpdwAPIVersion

指向 DWORD的指针。应用程序必须在调用此函数之前将此 DWORD初始化为它所支持的最高 API 版本（例如，它将传入 dwAPIHighVersion 参数的 phoneNegotiateAPIVersion）。不得使用人工高值;必须准确设置值。 TAPI 将任何较新的消息或结构转换为应用程序版本支持的值或格式。成功完成此请求后，此位置将填充 TAPI 支持的最高 API 版本，从而允许应用程序检测并适应已在具有较旧版本的 TAPI 的系统上安装。

lpPhoneInitializeExParams

指向 PHONEINITIALIZEEXPARAMS 类型的结构的指针包含用于在应用程序和 TAPI 之间建立关联的其他参数（特别是应用程序的所选事件通知机制和相关参数）。

返回值

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

PHONEERR_INVALAPPNAME、PHONEERR_OPERATIONFAILED、PHONEERR_INIFILECORRUPT、PHONEERR_INVALPOINTER、PHONEERR_REINIT、PHONEERR_NOMEM、PHONEERR_INVALPARAM。

言论

应用程序必须选择以下三种机制之一：TAPI 通知电话事件的应用程序：隐藏窗口、事件句柄或完成端口。

通过在 PHONEINITIALIZEEXPARAMS 结构中指定 dwOptions 成员中的 PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW 隐藏窗口 机制来选择该机制。在此机制（这是 TAPI 版本 1 中唯一可用的机制）。x 应用程序），TAPI 会在应用程序上下文中创建一个窗口，在 phoneInitializeEx 函数期间创建一个窗口，并子类化窗口，以便发布给它的所有消息都由 TAPI 中的 WNDPROC 本身处理。当 TAPI 有要传递到应用程序的消息时，TAPI 会将消息发布到隐藏窗口。收到消息时（仅当应用程序调用 Windows GetMessage 函数时才会发生），Windows 会将进程上下文切换到应用程序上下文并在 TAPI 中调用 WNDPROC。然后，TAPI 通过调用 phoneCallbackFunc将消息传递到应用程序，这是应用程序在调用 phoneInitializeEx（或 phoneInitialize）中作为参数提供的指针，用于 TAPI 版本 1.3 和 1.4 应用程序。此机制要求应用程序具有消息队列（这不适合服务进程），并定期为该队列提供服务，以避免延迟处理电话事件。隐藏窗口在 phoneShutdown 函数期间被 TAPI 销毁。
通过在 PHONEINITIALIZEEXPARAMS 结构中的 dwOptions 成员中指定PHONEINITIALIZEEXOPTION_USEEVENT来选择事件句柄机制。在此机制中，TAPI 代表应用程序创建事件对象，并将句柄返回到 PHONEINITIALIZEEXPARAMS中 hEvent 成员中的对象。应用程序不得以任何方式操作此事件（例如，不得调用 setEvent、ResetEvent、CloseHandle等）或未定义的行为结果;应用程序只能使用 WaitForSingleObject 或 MsgWaitForMultipleObjects等函数等待此事件。在应用程序挂起电话事件通知时，TAPI 将发出此事件信号;应用程序必须调用 phoneGetMessage 才能提取消息的内容。当未挂起任何事件时，TAPI 将重置该事件。事件句柄已关闭，在 phoneShutdown 函数期间由 TAPI 销毁的事件对象。应用程序不需要等待所创建的事件句柄;应用程序可以选择改为调用 phoneGetMessage，并阻止等待消息排队。
通过在 PHONEINITIALIZEEXPARAMS 结构中的 dwOptions 成员中指定 PHONEINITIALIZEEXOPTION_USECOMPLETION PORT 来选择 完成端口 机制。在此机制中，每当需要将电话事件发送到应用程序时， TAPI 使用 PostQueuedCompletionStatus 将其发送到 PHONEINITIALIZEEXPARAMS中 hCompletionPort 成员中指定的应用程序 dwCompletionKey成员的完成密钥标记的应用程序。应用程序之前必须使用 CreateIoCompletionPort创建完成端口。应用程序使用 GetQueuedCompletionStatus检索事件。从 GetQueuedCompletionStatus返回后，应用程序将指定的 dwCompletionKey 写入到由 lpCompletionKey 参数指向的 DWORD，指向 PHONEMESSAGE 结构的指针返回到由 lpOverlapped指向的位置。应用程序处理事件后，应用程序必须调用 LocalFree，以释放用于包含 PHONEMESSAGE 结构的内存。由于应用程序创建了完成端口（因此允许它出于其他目的进行共享），因此应用程序必须关闭它;在调用 phoneShutdown之后，应用程序不得关闭完成端口。

当多线程应用程序使用事件句柄机制，并且多个线程正在等待句柄，或者完成端口通知机制和多个线程正在等待端口时，可以按顺序处理电话事件。这不是由于从 TAPI 传递事件的顺序，而是由线程的时间切片或在单独的处理器上执行线程引起的。

如果返回PHONEERR_REINIT并请求了 TAPI 重新初始化（例如，由于添加或删除电话服务提供商），则 phoneInitializeEx 请求被拒绝，并出现此错误，直到最后一个应用程序关闭其 API 的使用（使用 phoneShutdown）。此时，新配置变得有效，应用程序再次被允许呼叫 phoneInitializeEx。

如果返回PHONEERR_INVALPARAM错误值，则指定的 hInstance 参数无效。

应用程序可以使用从零到 dwNumDevs 减 1 的手机设备标识符来引用单个电话设备。应用程序不应假定这些手机设备能够使用任何特定的 TAPI 功能，而无需先通过 phoneGetDevCaps查询其设备功能。

注意

tapi.h 标头将 phoneInitializeEx 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。