lineInitialize 函数 (tapi.h)

项目
08/26/2023

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

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

对于 TAPI 版本 1.4 及更早版本： lineInitialize 函数初始化应用程序对 Tapi.dll 的使用，以便后续使用行抽象。函数注册应用程序的指定通知机制，并返回应用程序可用的线路设备数。行设备是在 TAPI 中为行前缀函数提供实现的任何设备。

语法

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

参数

lphLineApp

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

hInstance

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

lpfnCallback

调用的回调函数的地址，用于确定线路设备、地址或呼叫的状态和事件。有关详细信息，请参阅 lineCallbackFunc。

lpszAppName

指向仅包含可显示字符的 以 null 结尾的文本字符串的指针。如果此参数不为 NULL，则它包含应用程序提供的名称。此名称在 LINECALLINFO 结构中提供，以用户友好的方式指示应用程序发起、最初接受或接听呼叫的应用程序。此信息可用于呼叫日志记录。如果 lpszAppName 为 NULL，则改用应用程序的文件名。

lpdwNumDevs

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

返回值

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

LINEERR_INVALAPPNAME、LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPOINTER、LINEERR_REINIT、LINEERR_NODRIVER、LINEERR_NODEVICE、LINEERR_NOMEM、LINEERR_NOMULTIPLEINSTANCE。

注解

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

应用程序可以使用从零到 dwNumDevs 减 1 的行设备标识符来引用单个线路设备。在不首先使用 lineGetDevCaps 和 lineGetAddressCaps 查询其设备功能之前，应用程序不应假定这些线路设备能够执行基本电话子集所指定范围以外的任何功能。

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

执行 lineShutdown 的另一个原因是，如果用户更改设备配置 (添加或删除线路或电话) ，TAPI 无法通知当时已打开线路或电话句柄的应用程序。重新配置导致发送LINEDEVSTATE_REINIT消息后，在所有应用程序都执行 lineShutdown 之前，任何应用程序都无法打开设备。如果任何服务提供商未能正确初始化，此函数将失败并返回服务提供商指示的错误。

在所有 TAPI 平台上， lineInitialize 使用 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW 选项等效于 lineInitializeEx 。