lineHandoff 関数 (tapi.h)

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

lineHandoff 関数は、指定された呼び出しの所有権を別のアプリケーションに与えます。アプリケーションは、ファイル名で直接指定することも、指定されたメディアモードの呼び出しを処理する最も優先度の高いアプリケーションとして間接的に指定することもできます。

構文

LONG lineHandoff(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

パラメーター

hCall

渡される呼び出しを処理します。アプリケーションは、呼び出しの所有者である必要があります。 hCall の呼び出し状態には、任意の状態を指定できます。

lpszFileName

null で終わる文字列へのポインター。このポインターパラメーターが NULL 以外の場合は、ハンドオフのターゲットであるアプリケーションのファイル名が含まれます。 NULL の場合、ハンドオフターゲットは、指定されたメディアモードの所有者特権の行を開いた最も優先度の高いアプリケーションです。有効なファイル名には、ファイルのパスは含まれません。

dwMediaMode

間接ハンドオフのターゲットを識別するために使用されるメディアモード。 dwMediaMode パラメーターは、呼び出しの所有権を受け取るターゲットアプリケーションを間接的に識別します。 lpszFileName が NULL でない場合、このパラメーターは無視されます。このパラメーターは、 LINEMEDIAMODE_定数の 1 つだけを使用します。

戻り値

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

LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONFAILED、LINEERR_INVALMEDIAMODE、LINEERR_TARGETNOTFOUND、LINEERR_INVALPOINTER、LINEERR_TARGETSELF、LINEERR_NOMEM、LINEERR_UNINITIALIZED、LINEERR_NOTOWNER。

注釈

lineHandoff 関数は、呼び出し元のアプリケーションが間接ハンドオフを試みた場合 (つまり、lpszFileName パラメーターを NULL に設定した場合) にLINEERR_TARGETSELFを返し、TAPI はアプリケーション自体が特定のメディアモードの最も優先度の高いアプリケーションであると判断した場合に返します。 LINEERR_TARGETNOTFOUNDが返された場合、呼び出しハンドオフのターゲットが見つかりませんでした。これは、名前付きアプリケーションが lineOpen の dwPrivileges パラメーターのLINECALLPRIVILEGE_OWNER ビットで同じ行を開かなかった場合に発生する可能性があります。または、メディアモードハンドオフの場合、lineOpen の dwPrivileges パラメーターのLINECALLPRIVILEGE_OWNER ビットと 、lineOpen の dwMediaModes パラメーターで指定されたメディアモードを使用して、同じ行を開いたアプリケーションはありません。

呼び出しハンドオフを使用すると、アプリケーション間で呼び出しの所有権を渡すことができます。ハンドオフには 2 種類があります。最初の種類では、アプリケーションがターゲットアプリケーションのファイル名を認識している場合は、そのファイル名を指定できます。ターゲットアプリケーションのインスタンスが回線デバイスを開いた場合、呼び出しの所有権は他のアプリケーションに渡されます。それ以外の場合、ハンドオフは失敗し、エラーが返されます。この形式のハンドオフは、呼び出しハンドルがハンドオフを要求するアプリケーションと同じファイル名に渡された場合に成功します。

2 番目のハンドオフの種類は、メディアモードに基づいています。この場合、アプリケーションはメディアモードを使用してターゲットアプリケーションを間接的に指定します。現在、そのメディアモードの回線デバイスを開いている最も優先度の高いアプリケーションは、ハンドオフのターゲットです。このようなアプリケーションがない場合、ハンドオフは失敗し、エラーが返されます。

lineHandoff 関数は、呼び出しのメディアモードを変更しません。呼び出しのメディアモードを変更するには、アプリケーションが呼び出しで lineSetMediaMode を使用し、新しいメディアモードを指定する必要があります。これにより、呼び出しの LINECALLINFO 構造体に格納されている呼び出しのメディアモードが変更されます。

ハンドオフが成功すると、受信アプリケーションは呼び出しのLINE_CALLSTATE メッセージを受信します。このメッセージは、受信アプリケーションが呼び出し (dwParam3) に対する所有者特権を持っていることを示します。さらに、呼び出しの所有者やモニターの数が変更されている可能性があります。これは LINE_CALLINFO メッセージによって報告され、受信側アプリケーションは lineGetCallStatus と lineGetCallInfo を呼び出して、受信した呼び出しに関する詳細情報を取得できます。

受信側のアプリケーションは、まず LINECALLINFO でメディアモードをチェックする必要があります。 1 つのメディアモードフラグのみが設定されている場合、呼び出しはそのメディアモードの正式なものであり、アプリケーションはそれに応じて動作できます。 UNKNOWN およびその他のメディアモードフラグが設定されている場合、呼び出しのメディアモードは公式には UNKNOWN ですが、 LINECALLINFO でフラグが設定されているメディアモードのいずれかであると見なされます。アプリケーションでは、最も優先度の高いメディアモードをプローブする必要があると想定する必要があります。

プローブが成功した場合 (そのメディアモードまたは別のメディアモードの場合)、アプリケーションは LINECALLINFO のメディアモードメンバーを、認識された単一メディアモードに設定する必要があります。メディアモードフラグが LINECALLINFO メディアモードと一致する場合、アプリケーションはそれに応じて動作できます。別のメディアモードに対して決定を行う場合は、まずそのメディアモードへの呼び出しを受け渡す必要があります。

プローブが失敗した場合、アプリケーションは LINECALLINFO で対応するメディアモードフラグをクリアし、 dwMediaMode をLINEMEDIAMODE_UNKNOWNとして指定して呼び出しを渡す必要があります。また、呼び出しハンドルの割り当てを解除する (または監視に戻す) 必要があります。

どのメディア・モードも判別に成功しなかった場合は、メディア・アプリケーションが UNKNOWN の呼び出しを受け渡そうとしたときに、LINECALLINFO のメディア・モード・フィールドに UNKNOWN フラグのみが設定されたままになります。アプリケーションが呼び出しの唯一の残りの所有者である場合、最終的な lineHandoff は失敗します。これにより、呼び出しを破棄し、ハンドルの割り当てを解除する必要があることをアプリケーションに通知します。この場合、呼び出しは破棄されます。呼び出し元アプリケーションの呼び出しに対する特権は、この操作によって変更されませんが、アプリケーションは、その特権を lineSetCallPrivilege を使用した呼び出しに変更できます。