TSPI_lineGetDevConfig関数 (tspi.h)
TSPI_lineGetDevConfig関数は、データ構造オブジェクトを返します。その内容は回線 (サービス プロバイダー) とデバイス クラスに固有であり、回線デバイスと一対一で関連付けられたデバイスの現在の構成を提供します。
構文
LONG TSPIAPI TSPI_lineGetDevConfig(
DWORD dwDeviceID,
LPVARSTRING lpDeviceConfig,
LPCWSTR lpszDeviceClass
);
パラメーター
dwDeviceID
構成する回線デバイス。
lpDeviceConfig
関連付けられたデバイスのデバイス構成構造が返される VARSTRING 型のデータ構造へのポインター。 要求が正常に完了すると、サービス プロバイダーはこのデータ構造にデバイス構成を入力します。 VARSTRING 構造体の dwStringFormat メンバーは、STRINGFORMAT_BINARYに設定する必要があります。 lpDeviceConfig パラメーターが指す VARSTRING 構造体の dwTotalSize メンバーが構造体の固定部分のサイズ以上の場合、サービス プロバイダーは dwNeededSize メンバーを必要なサイズに設定し、0 を返します。
lpszDeviceClass
構成が要求されるデバイスのデバイス クラスを指定する、null で終わる Unicode 文字列へのポインター。 有効なデバイス クラス文字列は、 TSPI_lineGetID関数が ライン デバイスに適用されるときに指定されたものと同じです (dwSelect の値はLINECALLSELECT_LINE)。
戻り値
関数が成功した場合は 0 を返し、エラーが発生した場合はエラー番号を返します。 可能な戻り値は次のとおりです。
LINEERR_INVALDEVICECLASS、LINEERR_NOMEM、LINEERR_INVALPOINTER、LINEERR_OPERATIONUNAVAIL、LINEERR_STRUCTURETOOSMALL、LINEERR_OPERATIONFAILED、LINEERR_NODRIVER、LINEERR_RESOURCEUNAVAIL。
解説
呼び出し状態はデバイス固有です。
この関数を使用すると、回線デバイスと一対一で関連付けられたデバイスの構成を指定するデータ構造をサービス プロバイダーから取得できます。 lpszDeviceClass パラメーターは、構成を取得するデバイスのクラスが異なる可能性がある中からどれを選択します。 サポートされているクラスのセットは、デバイスが回線デバイスと 1 対 1 で対応するクラスに制限されます。 一般的なデバイス クラスの詳細については、「 TSPI デバイス クラス」を参照してください。
サービス プロバイダーは通常、この関数の下で tapi/line デバイス クラスを許可する必要があります。 この行のアドレスの一覧、アドレスに対応する COMM ポートなどの物理ハードウェア デバイスの一覧、同時呼び出しの最大数 (構成可能な場合) など、"行" スコープを持つパラメーターを取得します。
通常、この関数は、特定の呼び出しまたは特定のアドレスに適用されるため、mci waveaudio、低レベルウェーブ、datamodem デバイス クラスなどのメディア関連のデバイス クラスを許可しません。 これらの 1 行のデバイスごとに複数のが存在する可能性があるため、この関数の回線デバイス識別子パラメーターによる特定の呼び出しまたはアドレスの識別はあいまいになります。 初期の既定値など、回線デバイス スコープ全体に適用されるクラス構成情報がある場合は、呼び出し固有またはアドレス固有のデバイス クラスに対して例外を発生させることができます。
呼び出し固有およびアドレス固有のデバイス クラスの例外的なサポートが、この関数の値が制限されている理由はいくつかあります。 最初に、これらのクラスは複数のアドレスまたは複数の呼び出しサービス プロバイダーであいまいになる可能性があるため、それらをサポートするのはサービス プロバイダーのサブセットのみです。 アプリケーションは、この関数にこれらのクラスを含めることにデバイス固有の依存関係を追加する可能性はありません。 第 2 に、低レベルのトランスポート API の観点からダイヤルイン ファイル システム アクセスなどの高レベルのプロトコルを実装する上位レベルのメディア "クラス" が出現するにつれて、これらのクラスの構成は "クラス" スコープではなく "インスタンス" スコープに向かう傾向があります。 高レベルのメディア API は、呼び出し固有またはアドレス固有のインスタンスを構成するために独自の関数を提供する必要があります。
この関数がサポートするデバイスとデバイス クラスの種類に関係なく、永続的な構成情報と一時的な構成情報の 2 種類に影響を与える可能性があります。 永続的な情報は、回線の異なる "開く" 間、およびサービス プロバイダー自体の異なる "inits" 間でも存続します。 一時的な情報は、行の一意の "開いている" 内でのみ存続します。 行が閉じられると、 TSPI_lineSetDevConfigを介 して取得または設定されたこのような一時的な情報は、既定値または未定義の値に戻すことができます。 呼び出し元は、TSPI_lineOpen、TSPI_lineConfigDialog、TSPI_lineGetDevConfigなどのシーケンスによってのみ、一時的な構成を確実に取得できます。 呼び出し元は、このようなシーケンスによって取得された一時的な構成情報を 、TSPI_lineOpen、 TSPI_lineSetDevConfigなどのシーケンスを通じて確実に設定できます。 構成の一時的な部分は、次のTSPI_lineConfigDialog、TSPI_lineSetDevConfig、またはTSPI_lineCloseまでだけ安定しています。 サービス プロバイダーは、構成の永続的な部分 (通常は .ini ファイル) を格納し、サービス プロバイダーが初期化されるたびに再読み込みを行う必要があります。
この関数によって返される構造体に含まれるデータの正確な形式は、行およびデバイス クラス API に固有であり、文書化されておらず、未定義です。 この関数によって返される構造体に直接アクセスしたり、アプリケーションで操作したりすることはできませんが、そのまま保存し、後で設定を復元するために TSPI_lineSetDevConfig で使用することしかできません。 構造体は、同じデバイス クラスであっても、必ずしも他のデバイスに渡すことはできません (ただし、これは一部のインスタンスで動作する可能性がありますが、保証されません)。 サービス プロバイダーは、互換性のない情報を渡すクライアント アプリケーションが原因でエラーを防ぐために、データ構造に項目を配置して、一貫性をチェックできるようにする必要があります。
要件
| 対象プラットフォーム | Windows |
| ヘッダー | tspi.h |