lineConfigDialogEdit 関数 (tapi.h)

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

lineConfigDialogEdit 関数を使用すると、指定した回線デバイスのプロバイダーにダイアログボックス (アプリケーションの hwndOwner にアタッチ) が表示され、ユーザーは回線デバイスに関連するパラメーターを構成できます。

構文

LONG lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

パラメーター

dwDeviceID

構成する回線デバイスの識別子。

hwndOwner

ダイアログボックスがアタッチされるウィンドウへのハンドル。関数の間に作成されたウィンドウに所有者ウィンドウがないことを示すには 、NULL を 指定できます。

lpszDeviceClass

デバイスクラス名を識別する null で終わる文字列へのポインター。このデバイスクラスを使用すると、アプリケーションは、そのデバイスクラスに適用できる構成情報の特定のサブ画面を選択できます。このパラメーターは省略可能であり、 NULL または空のままにできます。この場合、最上位レベルの構成が選択されます。

lpDeviceConfigIn

VARSTRING 構造体の変数部分の lineGetDevConfig (または lineConfigDialogEdit の以前の呼び出し) によって返された不透明な構成データ構造へのポインター。

dwSize

lpDeviceConfigIn が指す構造体内のバイト数。この値は、lineGetDevConfig または lineConfigDialogEdit の以前の呼び出しによって返される VARSTRING 構造体の dwStringSize メンバーで返されます。

lpDeviceConfigOut

デバイス構成構造体が返される VARSTRING 型のメモリ位置へのポインター。要求が正常に完了すると、この場所にデバイス構成が入力されます。 VARSTRING 構造体の dwStringFormat メンバーは、STRINGFORMAT_BINARYに設定されます。 lineGetDevConfig (または lineConfigDialogEdit の今後の呼び出し) を呼び出す前に、アプリケーションは、この構造体の dwTotalSize メンバーを設定して、情報を返すために TAPI が使用できるメモリの量を示す必要があります。

戻り値

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

LINEERR_BADDEVICEID、LINEERR_OPERATIONFAILED、LINEERR_INVALDEVICECLASS、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPARAM、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED、LINEERR_NODRIVER、LINEERR_OPERATIONUNAVAIL、LINEERR_NOMEM、LINEERR_NODEVICE。

注釈

LINEERR_STRUCTURETOOSMALLが返された場合、lpDeviceConfigOut が指す VARSTRING 構造体の dwTotalSize メンバーは、構成構造全体を格納するのに十分なメモリを指定しません。 dwNeededSize メンバーは、必要な量に設定されています。領域が不足しているために返されなかった情報にユーザーエントリが反映された範囲では、それらの編集は失われます。そのため、アプリケーションは、デバイスクラスが構成構造を返すために必要になる可能性がある最大領域を割り当てる必要があります (詳細については、「 TAPI デバイスクラス」を参照してください)。

lineConfigDialogEdit 関数を使用すると、サービスプロバイダーはモーダルダイアログボックス (アプリケーションの hwndOwner にアタッチ) を表示して、dwDeviceID で指定された行に関連するパラメーターをユーザーが構成できるようにします。

lpszDeviceClass パラメーターを使用すると、アプリケーションは、ユーザーが関心のあるデバイスクラスに適用できる構成情報の特定のサブ画面を選択できます。許可される文字列は、lineGetID の場合と同じです。たとえば、行が Comm API をサポートしている場合、 lpszDeviceClass として "COMM" を渡すと、プロバイダーは Comm に関連するパラメーターを表示します (または、少なくとも、マルチレベル構成ダイアログボックスチェーン内の対応するポイントから開始するため、ユーザーは目的のパラメーターを検索するために "掘る" 必要はありません)。

lpszDeviceClass パラメーターは、"tapi/line" 、""、または NULL です。これにより、プロバイダーに行の最上位レベルの構成が表示されます。

この関数と lineConfigDialog の違いは、編集するパラメーターのソースと編集の結果です。 lineConfigDialog では、編集されるパラメーターはデバイスで現在使用されているパラメーター (または次の呼び出しで使用するように設定) であり、行われた変更は (可能な限り) アクティブな接続に即時に影響を与えます。また、アプリケーションでは lineGetDevConfig を使用して、lineConfigDialog からパラメーター変更の結果をフェッチする必要があります。 lineConfigDialogEdit では、編集するパラメーターがアプリケーションから渡され、アクティブな接続に影響を与えずに結果がアプリケーションに返されます。編集の結果はこの関数で返され、アプリケーションは lineGetDevConfig を呼び出す必要はありません。したがって、 lineConfigDialogEdit では、アクティブな呼び出しに影響を与えることなく、ユーザーが将来の呼び出しのパラメーターを設定する機能をアプリケーションに提供できます。ただし、この関数の出力を lineSetDevConfig に渡して、現在の呼び出しまたは次の呼び出しに影響を与えることができます。