lineOpen 関数 (tapi.h)

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

lineOpen 関数は、デバイス識別子で指定された回線デバイスを開き、対応する開いている回線デバイスの行ハンドルを返します。このラインハンドルは、ラインデバイスでの後続の操作で使用されます。

構文

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

パラメーター

hLineApp

TAPI を使用してアプリケーションの登録を処理します。

dwDeviceID

開く回線デバイスを識別します。有効なデバイス識別子または値を指定できます。

値	意味
LINEMAPPER	この値は、 lpCallParams で指定されたプロパティをサポートするシステム内の回線デバイスを開くために使用されます。アプリケーションでは、 lineGetID を使用して、開かれた回線デバイスの識別子を決定できます。

lphLine

開かれた回線デバイスを表すハンドルと共に読み込まれる HLINE ハンドルへのポインター。このハンドルを使用して、オープンラインデバイスで他の関数を呼び出すときにデバイスを識別します。

dwAPIVersion

アプリケーションとテレフォニー API が動作することに同意した API バージョン番号。この数値は lineNegotiateAPIVersion で取得されます。

dwExtVersion

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

dwCallbackInstance

この行に関連付けられた各メッセージ、またはこの行のアドレスまたは呼び出しを使用して、アプリケーションに返されるユーザーインスタンスデータ。このパラメーターはテレフォニー API では解釈されません。

dwPrivileges

呼び出しの通知を受けた場合にアプリケーションが必要とする特権このパラメーターには、1 つ以上の LINECALLPRIVILEGE_定数が含まれています。 TAPI バージョン 2.0 以降を使用するアプリケーションの場合、このパラメーターの値を 1 つ以上の LINEOPENOPTION_定数と組み合わせることもできます。

LINEOPENOPTION_SINGLEADDRESS オプションが指定されている場合、アプリケーションは、lpCallParams パラメーターによって指される LINECALLPARAMS 構造体の dwAddressID メンバーによって指定されたアドレスに表示される新しい呼び出しにのみ関心があります (指定する必要があります)。

LINEOPENOPTION_SINGLEADDRESSが指定されていても 、lpCallParams が無効であるか、含まれている dwAddressID が行に存在しない場合、開くはLINERR_INVALADDRESSIDで失敗します。

LINECALLPARAMS 構造体の dwAddressID メンバーを目的のアドレスに設定するだけでなく、アプリケーションで LINECALLPARAMS の dwAddressMode を LINEADDRESSMODE_ADDRESSIDに設定する必要もあります。

LINEOPENOPTION_SINGLEADDRESS オプションは、 LINE_NEWCALL メッセージを使用してサービスプロバイダーによって作成された呼び出しの初期呼び出し所有権の TAPI の割り当てにのみ影響します。 LINECALLPRIVILEGE_MONITORで行を開くアプリケーションは、その行で作成されたすべての呼び出しに対する監視ハンドルを引き続き受け取ります。さらに、アプリケーションは、呼び出しを行ったり、開かれた回線上の他のアドレスに影響を与える他の操作を実行したりしても制限されません。

LINEOPENOPTION_PROXY オプションが指定されている場合 (TAPI 2.0 以降のみ)、アプリケーションは、処理する準備ができている特定のプロキシ要求も示す必要があります。これを行うために、lpCallParams パラメーターに、dwDevSpecificSize メンバーと dwDevSpecificOffset メンバーが DWORDs の配列を区切るように設定されている LINECALLPARAMS 構造体へのポインターを渡します。この配列の各要素には、LINEPROXYREQUEST_定数のいずれかを含める必要があります。たとえば、エージェント関連の 5 つの関数をすべてサポートするプロキシハンドラーアプリケーションは、5 つの定義された LINEPROXYREQUEST_値を含む 5 つの DWORDs (dwDevSpecificSize は 10 進数 20) の配列を渡します。

プロキシ要求ハンドラーアプリケーションは、回線デバイスを制御するための承認を持つ任意のコンピューターで実行できます。ただし、要求は、実際に回線デバイスを制御するサービスプロバイダーが実行しているサーバーを介して常にルーティングされます。したがって、プロキシ要求 (ACD エージェント制御など) を処理するアプリケーションが、サービスプロバイダーと共にサーバー上で直接実行される場合に最も効率的です。

同じアプリケーションまたは他のアプリケーションによる後続の試行で、回線デバイスを開き、既に登録されているアプリケーションと同じプロキシ要求を処理するように登録しようとすると、LINEERR_NOTREGISTEREDで失敗します。

行での要求の処理を停止するために、アプリケーションは lineClose を呼び出すだけです。

その他のフラグの組み合わせでは、LINEERR_INVALPRIVSELECT エラーが返されます。

dwMediaModes

アプリケーションの対象となるメディアの種類またはモード。このパラメーターは、指定されたメディアの種類の着信および通話ハンドオフの潜在的なターゲットとしてアプリケーションを登録するために使用されます。このパラメーターは、 dwPrivileges のビット LINECALLPRIVILEGE_OWNERが設定されている場合にのみ意味があります (それ以外の場合は無視されます)。このパラメーターは、1 つ以上の LINEMEDIAMODE_定数を使用します。

lpCallParams

LINECALLPARAMS 型の構造体へのポインター。このポインターは、LINEMAPPER または LINEOPENOPTION_PROXY が使用されている場合にのみ使用されます。それ以外の場合 、lpCallParams は無視されます。回線デバイスで提供できる必要がある呼び出しパラメーターについて説明します。

戻り値

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

LINEERR_ALLOCATED、LINEERR_LINEMAPPERFAILED、LINEERR_BADDEVICEID、LINEERR_NODRIVER、LINEERR_INCOMPATIBLEAPIVERSION、LINEERR_NOMEM、LINEERR_INCOMPATIBLEEXTVERSION、LINEERR_OPERATIONFAILED、LINEERR_INVALAPPHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALMEDIAMODE、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED、LINEERR_INVALPRIVSELECT、LINEERR_REINIT、LINEERR_NODEVICE、LINEERR_OPERATIONUNAVAIL。

注釈

LINEERR_ALLOCATEDが返された場合、シリアルポートが別のプロセスによって排他的に開かれているなど、"永続的" な条件が原因で行を開くことができません。 LINEERR_RESOURCEUNAVAILが返された場合、DSP プロセッササイクルやメモリ内などの動的リソースのオーバーコミットにより、行を開くことができません。このオーバーコミットは、メディアの種類やトーンの監視によって引き起こされる一時的な可能性があり、他のアプリケーションによるこれらのアクティビティの変更により、短時間でラインを再び開くことができます。 LINEERR_REINITが返され、TAPI の再初期化が要求された場合 (たとえば、テレフォニーサービスプロバイダーを追加または削除した結果)、最後のアプリケーションが API の使用をシャットダウンするまで、 lineOpen 要求はこのエラーで拒否されます ( lineShutdown を使用)。その時点で、新しい構成が有効になり、アプリケーションは再び lineInitializeEx を呼び出す許可を受けます。

行を開くと、アプリケーションは常に、その回線で使用可能な任意のアドレスで呼び出しを行うことができます。着信呼び出しを処理する、または回線上の呼び出しハンドオフのターゲットにするアプリケーションの機能は、 dwMediaModes パラメーターによって決定されます。 lineOpen 関数は、呼び出しの監視や、指定されたメディアの種類の呼び出しの所有権の受信に関心を持つアプリケーションを登録します。アプリケーションが呼び出しを監視するだけの場合は、LINECALLPRIVILEGE_MONITORを指定できます。アプリケーションが発信呼び出しを行うだけの場合は、LINECALLPRIVILEGE_NONEを指定できます。アプリケーションが未分類の呼び出し (不明なメディアの種類の呼び出し) を制御する場合は、LINECALLPRIVILEGE_OWNERとLINEMEDIAMODE_UNKNOWNを指定できます。それ以外の場合、アプリケーションは処理対象のメディアの種類を指定する必要があります。アプリケーションは lineSetCallPrivilege 関数を呼び出して、LINECALLPRIVILEGES_Constantsで指定された呼び出し特権を変更できます。

lineOpen で指定されたメディアの種類は、初期着信呼び出しの種類の決定のためのプロバイダーのメディアの種類の監視の既定値に追加されます。 lineMonitorMedia 関数は、メッセージを制御するマスクLINE_MONITORMEDIA変更します。回線デバイスが所有者特権で開き、拡張メディアの種類が登録されていない場合は、エラー LINEERR_INVALMEDIAMODEが返されます。

回線デバイスを正常に開いたアプリケーションは、常に lineMakeCall、 lineUnpark、 linePickup、 lineSetupConference ( NULLhCall を使用) を使用して呼び出しを開始し、 lineForward を使用できます (これを行うことがデバイスの機能、回線状態などによって許可されていると仮定)。

1 つのアプリケーションで複数のフラグを同時に指定して、複数のメディアの種類を処理できます。複数のアプリケーションが同じメディアタイプに対して同じ回線デバイスを開くと、競合が発生する可能性があります。これらの競合は、ユーザーがアプリケーションに相対的な優先順位を割り当てる優先順位スキームによって解決されます。ユーザーは、 lineSetAppPriority 関数を呼び出すことによって、アプリケーションの優先順位を設定できます。特定のメディアタイプの最も優先度の高いアプリケーションのみが、そのメディアタイプの呼び出しの所有権(未承諾)を受け取ります。所有権は、着信呼び出しが最初に到着したとき、または通話が引き渡されたときに受信できます。 lineHandoff 関数は、呼び出しの所有権を別のアプリケーションに渡すために呼び出されます。ユーザーがアプリケーションに優先順位を割り当てず、複数のアプリケーションが同じ回線デバイスを開いている場合、既定では、 lineOpen を最初に呼び出したアプリケーションの優先度が最も高くなります。

すべてのアプリケーション (優先度の低いアプリケーションを含む) は、常に lineGetNewCalls または lineGetConfRelatedCalls を使用して所有権を取得できます。呼び出しが行に存在する時点で監視用の行をアプリケーションが開いた場合、それらの既存の呼び出しのメッセージ LINE_CALLSTATE は、新しい監視アプリケーションに対して自動的に生成されません。アプリケーションは、行の現在の呼び出しの数に対してクエリを実行して、存在する呼び出しの数を確認できます。必要に応じて 、lineGetNewCalls を呼び出してこれらの呼び出しのハンドルを取得できます。

自動音声を処理するアプリケーションでは、対話型音声オープンモードも選択し、対話型音声の最も低い優先度を割り当てる必要があります。その理由は、サービスプロバイダーがすべての音声メディアの種類を対話型音声として報告する場合です。 UNKNOWN メディアタイプのアプリケーションでメディアタイプの決定が実行されず、対話型音声アプリケーションが回線デバイスを開いていなかった場合、音声通話は自動音声アプリケーションに到達できず、破棄されます。

同じアプリケーション、または同じアプリケーションの異なるインスタンス化によって、同じパラメーターまたは異なるパラメーターで同じ行を複数回開くことができます。

アプリケーションが回線デバイスを開くときは、ネゴシエートされた API バージョンを指定する必要があり、その行の拡張機能を使用する場合は、回線のデバイス固有の拡張バージョンを指定する必要があります。これらのバージョン番号は、 lineNegotiateAPIVersion と lineNegotiateExtVersion で取得する必要があります。バージョン番号付けでは、API のバージョンとサービスプロバイダーのバージョンが異なる異なるアプリケーションバージョンの混在と照合が可能になります。

LINEMAPPER を使用すると、アプリケーションは、必要なサービスを使用して、間接的に行を選択できます。 LINEMAPPER を使用して回線デバイスを開くときは、次のようになります。 LINECALLPARAMS データ構造の先頭から dwAddressMode までのすべてのメンバーが関連します。 dwAddressMode がLINEADDRESSMODE_ADDRESSID場合は、回線上の任意のアドレスが許容されることを意味します。それ以外の場合は、dwAddressMode がLINEADDRESSMODE_DIALABLEADDRされている場合、特定の発信元アドレス (電話番号) が検索されることを示す場合、またはプロバイダー固有の拡張機能である場合は、dwOrigAddressSize/Offset と、それらが参照する変数部分の部分も関連します。 dwAddressMode がプロバイダー固有の拡張機能である場合は、dwDeviceSpecific 可変サイズのメンバーに追加情報を含めることができます。