phoneInitializeExA 函数 (tapi.h)

项目
08/26/2023

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 结构中提供了此名称，以用户友好的方式指示哪个应用程序拥有电话设备的所有权。如果 lpszFriendlyAppName 为 NULL，则改用应用程序的模块文件名 (GetModuleFileName) 函数返回。

lpdwNumDevs

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

lpdwAPIVersion

指向 DWORD 的指针。在调用此函数之前，应用程序必须将此 DWORD 初始化为它设计为支持 (的最高 API 版本，例如，它传递到 phoneNegotiateAPIVersion 的 dwAPIHighVersion 参数的值) 相同。不得使用人为的高值：必须准确设置值。 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 成员中指定的完成端口，并使用应用程序在 PHONEINITIALIZEEXPARAMS 的 dwCompletionKey 成员中指定的完成键标记。应用程序之前必须使用 CreateIoCompletionPort 创建完成端口。应用程序使用 GetQueuedCompletionStatus 检索事件。从 GetQueuedCompletionStatus 返回时，应用程序具有写入 lpCompletionKey 参数所指向的 DWORD 的指定 dwCompletionKey ，以及一个指向 PHONEMESSAGE 结构的指针，该结构返回到 lpOverlapped 指向的位置。应用程序处理事件后，应用程序必须调用 LocalFree 以释放用于包含 PHONEMESSAGE 结构的内存。由于应用程序创建了完成端口 (因此允许将其共享用于其他目的) ，因此应用程序必须关闭它;在调用 phoneShutdown 之后，应用程序不得关闭完成端口。

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

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

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

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

注意

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