TSPI_lineSetDevConfig関数 (tspi.h)

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

TSPI_lineSetDevConfig関数は、TSPI_lineGetDevConfigを使用して以前に取得したデータ構造から、ラインデバイスに関連付けられているデバイスの構成を復元します。このデータ構造の内容は、行 [サービスプロバイダー] とデバイスクラスに固有です。

構文

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

パラメーター

dwDeviceID

構成する回線デバイス。

lpDeviceConfig

TSPI_lineGetDevConfigによって VARSTRING 構造体の変数部分で返される構成データ構造体へのポインター。

dwSize

lpDeviceConfig が指す構造体のバイト数。この値は、TSPI_lineGetDevConfigによって返される VARSTRING 構造体の dwStringSize メンバーで返されます。

メモ構造体のサイズパラメーターが正しくない場合は、データが上書きされる可能性があります。構造体サイズの設定の詳細については、メモリ割り当てに関するトピックを参照してください。

lpszDeviceClass

構成を復元するデバイスのデバイスクラスを指定する、null で終わる Unicode 文字列へのポインター。有効なデバイスクラス文字列は、 TSPI_lineGetID 関数が "line" デバイスに適用されるときに指定したものと同じです (つまり、 dwSelect の値がLINECALLSELECT_LINEの場合)。

戻り値

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

LINEERR_INVALDEVICECLASS、LINEERR_NOMEM、LINEERR_INVALPOINTER、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALPARAM、LINEERR_OPERATIONFAILED、LINEERR_INVALLINESTATE、LINEERR_RESOURCEUNAVAIL、LINEERR_NODRIVER。

注釈

呼び出し状態はデバイス固有です。

lpDeviceConfig が指す構造体に含まれる情報がこのデバイスに対して有効でない場合、サービスプロバイダーはLINEERR_INVALPARAMを返します。

現在の回線状態でデバイス構成を変更できない場合、サービスプロバイダーはLINEERR_INVALLINESTATEを返します。この行は、別のアプリケーションで使用されている可能性があります。

この関数を使用すると、TSPI_lineGetDevConfig関数を使用してサービスプロバイダーから以前に取得したデータ構造から、回線デバイスに関連付けられているデバイスの構成を復元できます。 lpszDeviceClass パラメーターは、構成を復元するデバイスのクラスを選択します。サポートされているクラスのセットは、デバイスが回線デバイスと 1 対 1 で対応するクラスに制限されます。一般的なデバイスクラスの詳細については、「 TSPI デバイスクラス」を参照してください。

通常、サービスプロバイダーは、この関数の下で tapi/line デバイスクラスを許可します。この行のアドレスの一覧や、アドレスに対応する COMM ポートや同時呼び出しの最大数 (構成可能な場合) などの物理ハードウェアデバイスの一覧など、"行" スコープを持つパラメーターを復元します。

一般に、mci waveaudio、低レベルウェーブ、datamodem デバイスクラスなどのメディア関連のデバイスクラスは、通常、特定の呼び出しまたは特定のアドレスに適用されるため、この関数では許可されません。これらのデバイスは 1 行のデバイスごとに複数存在する可能性があるため、この関数の回線デバイス識別子パラメーターによる特定の呼び出しまたはアドレスの識別はあいまいです。最初の既定値など、回線デバイススコープ全体に適用されるクラス構成情報がある場合は、呼び出し固有またはアドレス固有のデバイスクラスに対して例外を発生させることができます。

呼び出し固有およびアドレス固有のデバイスクラスの例外的なサポートが、この関数の値が制限されている理由はいくつかあります。最初に、これらのクラスは複数アドレスの複数呼び出しサービスプロバイダーであいまいになる可能性があるため、それらをサポートするのはサービスプロバイダーのサブセットのみです。アプリケーションプログラムは、この関数にこれらのクラスを含めることにデバイス固有の依存関係を追加する可能性はありません。次に、下位レベルのトランスポート API の観点からダイヤルインファイルシステムアクセスなどの高レベルのプロトコルを実装する上位レベルのメディアクラスが出現するにつれて、これらのクラスの構成はクラススコープではなくインスタンススコープに向かう傾向があります。高レベルのメディア API は、呼び出し固有またはアドレス固有のインスタンスを構成するために独自の関数を提供する必要があります。

この関数がサポートするデバイスとデバイスクラスの種類に関係なく、永続的な構成情報と一時的な構成情報の 2 種類に影響を与える可能性があります。永続的な情報は、回線の異なる "開く" 間、およびサービスプロバイダー自体の異なる "inits" 間でも存続します。一時的な情報は、行の一意の "開いている" 内でのみ存続します。行を閉じると、 TSPI_lineGetDevConfigによって設定または取得された一時的な情報は、既定値または未定義の値に戻すことができます。呼び出し元は、TSPI_lineOpen、TSPI_lineConfigDialog、TSPI_lineGetDevConfigなどのシーケンスによってのみ、一時的な構成を確実に取得できます。呼び出し元は、このようなシーケンスによって取得された一時的な構成情報を 、TSPI_lineOpen、 TSPI_lineSetDevConfigなどのシーケンスを通じて確実に設定できます。構成の一時的な部分は、次のTSPI_lineConfigDialog、TSPI_lineSetDevConfig、またはTSPI_lineCloseまでだけ安定しています。サービスプロバイダーは、構成の永続的な部分 (通常は .ini ファイル) を格納し、サービスプロバイダーが初期化されるたびに再読み込みを行う必要があります。

この関数に渡される構造体に含まれるデータの正確な形式は、行およびデバイスクラス API に固有であり、文書化されておらず、未定義です。この関数に渡される構造体は、アプリケーションから直接アクセスしたり操作したりすることはできませんが、そのまま保存し、後で設定を取得するために前のTSPI_lineGetDevConfig から使用することしかできません。構造体は、同じデバイスクラスであっても、必ずしも他のデバイスに渡すことはできません (ただし、これは一部のインスタンスで動作する可能性がありますが、保証されません)。サービスプロバイダーは、互換性のない情報を渡すクライアントアプリケーションが原因で障害を防ぐために、一貫性のためにこのデータ構造をチェックする必要があります。

メモ一部のサービスプロバイダーでは、デバイスの使用中に構成の設定を許可する場合もあれば、使用できないサービスプロバイダーもあります。