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 版本和服務提供者版本。