phoneOpen 関数 (tapi.h)

[アーティクル]
08/26/2023

phoneOpen 関数は、指定された電話デバイスを開きます。電話デバイスは、所有者特権または監視特権を使用して開くことができます。所有者特権で電話を開くアプリケーションは、電話のランプ、ディスプレイ、呼び出し音、フックスイッチまたはフックスイッチを制御できます。モニター特権で電話デバイスを開くアプリケーションには、フックスイッチの変更やボタンの押しなど、電話で発生したイベントについてのみ通知されます。

電話デバイスの所有権は排他的です。つまり、一度に所有者特権で電話デバイスを開くことができるアプリケーションは 1 つだけです。ただし、電話デバイスは、モニター特権で複数回開くことができます。

構文

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

アプリケーションとサービスプロバイダーが動作することに同意する拡張機能のバージョン番号。アプリケーションで拡張機能が使用されていない場合、この数値は 0 です。この番号は phoneNegotiateExtVersion から取得されます。

dwCallbackInstance

各メッセージを使用してアプリケーションに返されるユーザーインスタンスデータ。このパラメーターはテレフォニー API では解釈されません。

dwPrivilege

特権が要求されました。このパラメーターは、 PHONEPRIVILEGE_定数の 1 つだけを使用します。

戻り値

要求が成功した場合は 0 を返し、エラーが発生した場合は負のエラー番号を返します。可能な戻り値は次のとおりです。

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 のバージョンとサービスプロバイダーのバージョンが異なる異なるアプリケーションバージョンを混在させ、一致させることができます。