lineInitializeExA 函数（tapi.h）

项目
11/20/2024

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

语法

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

参数

lphLineApp

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

hInstance

客户端应用程序或 DLL 的实例句柄。应用程序或 DLL 可以为此参数传递 NULL，在这种情况下，TAPI 使用进程的根可执行文件的模块句柄（用于标识呼叫接接目标和媒体模式优先级）。

lpfnCallback

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

lpszFriendlyAppName

指向仅包含可显示字符的 null终止的文本字符串的指针。如果此参数未 NULL，则它包含应用程序提供的名称。此名称在 LINECALLINFO 结构中提供，以用户友好的方式指示应用程序发起或最初接受或接听呼叫的方式。此信息可用于调用日志记录目的。如果 lpszFriendlyAppNameNULL，则改用应用程序的模块文件名（如函数 GetModuleFileName返回）。

lpdwNumDevs

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

lpdwAPIVersion

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

lpLineInitializeExParams

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

返回值

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

LINEERR_INVALAPPNAME、LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_INVALPOINTER、LINEERR_REINIT、LINEERR_NOMEM、LINEERR_INVALPARAM。

言论

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

通过在 LINEINITIALIZEEXPARAMS 结构中指定 dwOptions 成员中的LINEINITIALIZEEXOPTION_USEHIDDENWINDOW来选择隐藏窗口机制。在此机制中（这是 TAPI 版本 1 唯一可用的机制）。x 应用程序），TAPI 在 lineInitializeEx 或 lineInitialize（对于 TAPI 版本 1.3 和 1.4 应用程序）函数创建应用程序上下文中的窗口，并子类化窗口，以便发布到该应用程序的所有消息都由 TAPI 本身的 WNDPROC 处理。当 TAPI 有要传递到应用程序的消息时，TAPI 会将消息发布到隐藏窗口。收到消息时（仅当应用程序调用 Windows GetMessage 函数时才会发生），Windows 会将进程上下文切换到应用程序上下文并在 TAPI 中调用 WNDPROC。然后，TAPI 通过调用 lineCallbackProc（应用程序在其调用 lineInitializeEx（或 lineInitialize）中作为参数提供的指针）将消息传递到应用程序。此机制要求应用程序具有消息队列（这不适合服务进程），并定期为该队列提供服务，以避免延迟处理电话事件。隐藏窗口在 lineShutdown 函数期间被 TAPI 销毁。

通过在 LINEINITIALIZEEXPARAMS 结构中指定 dwOptions 成员中的LINEINITIALIZEEXOPTION_USEEVENT来选择事件句柄机制。在此机制中，TAPI 代表应用程序创建事件对象，并将句柄返回到 LINEINITIALIZEEXPARAMS中 hEvent 成员中的对象。应用程序不得以任何方式操作此事件（例如，不得调用 setEvent、ResetEvent、CloseHandle等）或未定义的行为结果;应用程序只能使用 WaitForSingleObject 或 MsgWaitForMultipleObjects等函数等待此事件。在应用程序挂起电话事件通知时，TAPI 将发出此事件信号;应用程序必须调用 lineGetMessage 才能提取消息的内容。当未挂起任何事件时，TAPI 将重置该事件。事件句柄已关闭，在 lineShutdown 函数期间由 TAPI 销毁的事件对象。应用程序不需要等待所创建的事件句柄;应用程序可以选择改为调用 lineGetMessage，并阻止等待消息排队。

通过在 LINEINITIALIZEEXPARAMS 结构中指定 dwOptions 成员中的 LINEINITIALIZEEXOPTION_USECOMPLETION PORT 来选择完成端口机制。在此机制中，每当需要将电话事件发送到应用程序时， TAPI 使用 PostQueuedCompletionStatus 将其发送到 LINEINITIALIZEEXPARAMS中 hComplet ionPort 成员中指定的应用程序的完成端口，并用 LINEINITIALIZEEXPARAMS中指定的应用程序指定的完成键进行标记。应用程序之前必须使用 CreateIoCompletionPort创建完成端口。应用程序使用 GetQueuedCompletionStatus检索事件。从 GetQueuedCompletionStatus返回时，应用程序将指定的 dwCompletionKey 写入到由 lpCompletionKey 参数指向的 DWORD，以及指向 LINEMESSAGE 结构的指针，lpOverlapped所指向的位置。应用程序处理事件后，应用程序负责调用 LocalFree 以释放用于包含 LINEMESSAGE 结构的内存。由于应用程序创建了完成端口（因此允许它出于其他目的进行共享），因此应用程序必须关闭它;在调用 lineShutdown之后，应用程序不得关闭完成端口。

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

如果返回LINEERR_REINIT并且已请求 TAPI 重新初始化，例如，由于添加或删除电话服务提供商，则拒绝 lineInitializeEx 请求，直到最后一个应用程序关闭其 API 的使用（使用 lineShutdown），此时新配置生效，应用程序再次被允许调用 lineInitializeEx。

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

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

注意

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