lineInitializeExA 函数 (tapi.h)

项目
03/05/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 结构中提供，以用户友好的方式指示应用程序发起、最初接受或接听呼叫的应用程序。此信息可用于调用日志记录。如果 lpszFriendlyAppName 为 NULL，则改用应用程序的模块文件名 (GetModuleFileName) 函数返回。

lpdwNumDevs

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

lpdwAPIVersion

指向 DWORD 大小位置的指针。在调用此函数之前，应用程序必须将此 DWORD 初始化为支持 (的最高 API 版本，例如，它传递到 lineNegotiateAPIVersion) 的 dwAPIHighVersion 参数的值相同。不得使用人为的高值：必须准确设置值。 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 在 TAPI 版本 1.3 和 1.4 应用程序的 lineInitializeEx 或 lineInitialize (期间在应用程序的上下文中创建一个窗口) 函数，并将窗口子类化，以便发布到它的所有消息都由 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 的 hCompletionPort 成员中指定的完成端口，并使用 LINEINITIALIZEEXPARAMS 中的 dwCompletionKey 成员中指定的完成键标记应用程序。应用程序之前必须使用 CreateIoCompletionPort 创建完成端口。应用程序使用 GetQueuedCompletionStatus 检索事件。从 GetQueuedCompletionStatus 返回时，应用程序具有将指定的 dwCompletionKey 写入到由 lpCompletionKey 参数指向的 DWORD，以及一个指向 LINEMESSAGE 结构的指针，该结构返回到由 lpOverlapped 指向的位置。应用程序处理事件后，应用程序负责调用 LocalFree 以释放用于包含 LINEMESSAGE 结构的内存。由于应用程序创建了完成端口 (因此允许将其共享用于其他目的) ，因此应用程序必须关闭它;在调用 lineShutdown 之后，应用程序不得关闭完成端口。

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

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

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

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

注意

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