TSPI_lineMakeCall関数 (tspi.h)

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

TSPI_lineMakeCall関数は、指定した行の呼び出しを指定した宛先アドレスに配置します。必要に応じて、既定の呼び出しセットアップパラメーター以外のパラメーターを要求する場合は、呼び出しパラメーターを指定できます。

構文

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

パラメーター

dwRequestID

非同期要求の識別子。

hdLine

新しい呼び出しの発信先の行へのハンドル。

htCall

新しい呼び出しへの TAPI ハンドル。サービスプロバイダーはこれを保存し、呼び出しのイベントを報告する LINEEVENT プロシージャへの後続のすべての呼び出しで使用する必要があります。

lphdCall

呼び出しハンドルへのポインター。サービスプロバイダーは、このプロシージャが戻る前に、呼び出しのハンドルをこの場所に入力する必要があります。関数でエラーが発生した場合、このハンドルは TAPI によって無視されます。

lpszDestAddress

宛先アドレスを指定する null で終わる Unicode 文字列へのポインター。これは、標準のダイヤル可能な番号形式に従います。このポインターは、ダイヤルされていないアドレス (ホットフォンの場合と同様に、定義済みの番号に常に自動的に接続する) またはすべてのダイヤルが TSPI_lineDialを使用して実行される場合に NULL として指定できます。後者の場合、 TSPI_lineMakeCall は、ダイヤルが開始されるまでダイヤル トーン 状態のままになる使用可能なコールアピアランスを割り当てます。逆多重機能を持つサービスプロバイダーでは、アプリケーションで一度に複数のアドレスを指定できます。

dwCountryCode

呼び出されたパーティの国または地域コード。値 0 を指定した場合、実装では既定値が使用されます。

lpCallParams

LINECALLPARAMS 構造体へのポインター。この構造体を使用すると、TAPI は呼び出しを設定する方法を指定できます。 NULL を指定すると、既定の 3.1kHz 音声呼び出しが確立され、回線上の任意の配信元アドレスが選択されます。この構造体は、呼び出しのベアラーモード、データレート、予想されるメディアの種類、配信元アドレス、呼び出し元 ID 情報のブロック、ダイヤルパラメーターなどの要素を選択します。

戻り値

dwRequestID を返します。エラーが発生した場合はエラー番号を返します。関数が成功した場合は対応するASYNC_COMPLETIONの実際のパラメーター lResult は 0、エラーが発生した場合はエラー番号です。可能な戻り値は次のとおりです。

LINEERR_ADDRESSBLOCKED、LINEERR_INVALLINESTATE、LINEERR_BEARERMODEUNAVAIL、LINEERR_INVALRATE、LINEERR_CALLUNAVAIL、LINEERR_INVALLINEHANDLE、LINEERR_DIALBILLING、LINEERR_INVALADDRESS、LINEERR_DIALQUIET、LINEERR_INVALADDRESSID、LINEERR_DIALDIALTONE、LINEERR_INVALCALLPARAMS、LINEERR_DIALPROMPT、LINEERR_NOMEM、LINEERR_INUSE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESSMODE、LINEERR_OPERATIONFAILED、LINEERR_INVALBEARERMODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALCOUNTRYCODE、LINEERR_RATEUNAVAIL、LINEERR_INVALMEDIAMODE、LINEERR_USERUSERINFOTOOBIG。

注釈

サービスプロバイダーは、行が現在この操作を実行できる状態でない場合は、LINEERR_INVALLINESTATEを返します。現在有効な操作の一覧は、LINEDEVSTATUS 構造体の dwLineFeatures メンバー (LINEFEATURE 型) にあります。 ( TSPI_lineGetLineDevStatus を呼び出すと、 LINEDEVSTATUS の情報が更新されます。

サービスプロバイダーがLINEERR_DIALBILLING、LINEERR_DIALQUIET、LINEERR_DIALDIALTONE、またはLINEERR_DIALPROMPTを返す場合、 TSPI_lineMakeCallによって実行されるアクションは実行されません。たとえば、部分ダイヤルは行われず、オフフックは行われません。これは、サービスプロバイダーがサポートされていない文字の番号を最初に事前にスキャンする必要があるためです。

TSPI_lineMakeCallがアプリケーションに SUCCESS 応答コールバックメッセージを返した後、サービスプロバイダーは、呼び出しの進行状況について TAPI に通知するために、TSPI_lineOpenで渡された lpfnEventProc にLINE_CALLSTATEメッセージを送信する必要があります。一般的に報告されるシーケンスは、ダイヤルトーン、ダイヤル、進行、リングバック、接続などです。報告される最初の状態は、必ずしもLINECALLSTATE_DIALTONEとは限りません。サービスプロバイダーは、報告されるこれらの状態の数を選択します。アプリケーションが適切なアクションを実行できるように、できるだけ多くを送信することをお勧めします。

サービスプロバイダーは、最初に、新しい呼び出しで、少なくとも回線上で監視されたメディアの種類のセットに対してメディア監視を行います。

ダイヤル文字列が NULL の場合、サービスプロバイダーは回線を ダイヤルトーン 状態にし (Comm ベースのサービスプロバイダーの場合は ATD が含まれます)、LINECALLSTATE_DIALTONEを示す呼び出し状態メッセージを送信します。

ダイヤル文字列が ';' で終わる場合(セミコロン)、サービスプロバイダーは部分番号をダイヤルし、LINECALLSTATE_DIALING メッセージを送信します。この呼び出しは、 TSPI_lineDialの呼び出しによって完了します。

サービスプロバイダーでサポートされていない文字 (W、@、$、?) がダイヤル文字列に含まれている場合、サービスプロバイダーはダイヤル文字列をスキャンし、最初の無効な文字に対応するエラーを (同期的に) 返す必要があります。

LINECALLPARAMFLAGS_IDLE フラグが設定されている場合、サービスプロバイダーは現在の回線の状態をチェックする必要があります (オフフックとダイヤルトーンの検出に相当します)。この IDLE フラグが設定され、ダイヤルトーンがない場合、この機能はエラー LINEERR_CALLUNAVAILで失敗します。 IDLE フラグが設定されていない場合、またはダイヤルトーンがある場合は、ダイヤルを続行できます。

この関数は、呼び出しの有効期間を開始するために TSPI モデルに従うという点で、対応する TAPI 関数とは異なります。 TAPI とサービスプロバイダーは、呼び出しを表す不透明なハンドルを相互に交換します。さらに、サービスプロバイダーは、このプロシージャから戻る前に、新しい呼び出しのコールバックを実行できます。いずれの場合も、サービスプロバイダーは、一致する ASYNC_COMPLETION メッセージが成功を報告するまで、返されたハンドルを "まだ有効ではありません" として扱う必要があります。新しい呼び出しに LINEEVENT メッセージを発行したり、その行のメッセージまたは状態データ構造の呼び出し数に含めたりすることはできません。