phoneOpen 函数 (tapi.h)

项目
03/05/2024

phoneOpen 函数将打开指定的电话设备。可以使用所有者特权或监视特权打开电话设备。使用所有者权限打开手机的应用程序可以控制手机的灯、显示器、响铃以及挂钩开关或挂钩开关。使用监视权限打开手机设备的应用程序仅会收到有关电话上发生的事件（例如挂钩开关更改或按下按钮）的通知。

手机设备的所有权是独占的。换句话说，一次只能有一个应用程序使用所有者权限打开手机设备。但是，手机设备可以使用监视权限多次打开。

语法

LONG phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD     dwDeviceID,
  LPHPHONE  lphPhone,
  DWORD     dwAPIVersion,
  DWORD     dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD     dwPrivilege
);

参数

hPhoneApp

使用 TAPI 注册应用程序的句柄。

dwDeviceID

要打开的电话设备的标识符。

lphPhone

指向 HPHONE 句柄的指针，该句柄标识打开的手机设备。调用其他手机控制功能时，使用此句柄标识设备。

dwAPIVersion

应用程序和电话 API 同意运行的 API 版本号。此号码是从 phoneNegotiateAPIVersion 获取的。

dwExtVersion

应用程序和服务提供商同意运行的扩展版本号。如果应用程序不使用任何扩展，则此数字为零。此号码是从 phoneNegotiateExtVersion 获取的。

dwCallbackInstance

用户实例数据通过每条消息传递回应用程序。电话服务 API 不解释此参数。

dwPrivilege

请求的权限。此参数只使用一个 PHONEPRIVILEGE_常量。

返回值

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

PHONEERR_ALLOCATED、PHONEERR_NODRIVER、PHONEERR_BADDEVICEID、PHONEERR_NOMEM、PHONEERR_INCOMPATIBLEAPIVERSION、PHONEERR_OPERATIONFAILED、PHONEERR_INCOMPATIBLEEXTVERSION、PHONEERR_OPERATIONUNAVAIL、PHONEERR_INVALAPPHANDLE、PHONEERR_RESOURCEUNAVAIL、PHONEERR_INVALPOINTER、PHONEERR_UNINITIALIZED、PHONEERR_INVALPRIVILEGE、PHONEERR_REINIT、PHONEERR_INUSE、PHONEERR_NODEVICE、PHONEERR_INIFILECORRUPT。

注解

使用监视权限打开电话设备时，当发生更改手机状态的事件时，应用程序会收到消息。发送到应用程序的消息包括 PHONE_BUTTON 和 PHONE_STATE。后者提供已更改的手机状态项的指示。

使用所有者权限打开电话时，可以通过影响手机设备状态的方式操作电话设备。如果应用程序主动想要操作电话设备，则仅应使用所有者特权打开手机，并且应在完成后关闭电话设备，以允许其他应用程序控制手机。

当应用程序打开电话设备时，它必须指定协商的 API 版本，如果它要使用手机的分机，则必须指定电话的设备特定扩展版本。此版本号应是使用 phoneNegotiateAPIVersion 和 phoneNegotiateExtVersion 函数获取的。版本编号允许将不同的应用程序版本与不同的 API 版本和服务提供程序版本混合和匹配。