ComDBGetCurrentPortUsage 関数 (msports.h)

[アーティクル]
02/29/2024

ComDBGetCurrentPortUsage は、COM ポートデータベースで現在 "使用中" としてログに記録されている COM ポート番号に関する情報を返します。

構文

LONG ComDBGetCurrentPortUsage(
  [in]            HCOMDB  HComDB,
  [out, optional] PBYTE   Buffer,
  [in]            DWORD   BufferSize,
  [in]            ULONG   ReportType,
  [out, optional] LPDWORD MaxPortsReported
);

パラメーター

[in] HComDB

ComDBOpen によって返された COM ポートデータベースへのハンドル。

[out, optional] Buffer

ルーチンが COM ポート番号に関する情報を返す呼び出し元によって割り当てられたバッファーへのポインター。詳細については、次の「解説」を参照してください。

[in] BufferSize

Buffer で呼び出し元が割り当てたバッファーのサイズをバイト単位で指定 します。

[in] ReportType

次のいずれかのフラグを指定します。

フラグ	説明
CDB_REPORT_BITS	このルーチンは、ポート番号の使用法を指定するビット配列を Buffer で返します。
CDB_REPORT_BYTES	このルーチンは、ポート番号の使用法を指定するバイト配列を Buffer で返します。

[out, optional] MaxPortsReported

ルーチンが Buffer で情報を返すポートの数を返すためにルーチンが使用する値へのポインター。詳細については、次の「解説」を参照してください。

戻り値

ComDBGetCurrentPortUsage は 、次のいずれかの状態値を返します。

リターンコード	説明
ERROR_SUCCESS	ルーチンからポート番号の使用状況情報が正常に返されました。
ERROR_INVALID_PARAMETER	次のいずれかが当てはまります:COM ポートデータベースに対する指定されたハンドルが無効です。 Buffer と MaxPortsReports の両方がNULL です。 ReportType が無効です。
ERROR_NOT_CONNECTED	ルーチンがデータベースにアクセスできませんでした。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

Buffer を NULL に設定し、MaxPortsReported を有効なポインターに設定すると、呼び出し元は現在の COM ポートデータベースサイズ (データベースで現在裁定されている COM ポート番号の数) を決定できます。この場合、ルーチンは *MaxPortsReported をデータベースサイズに設定します。 ReportType は使用されません。

Buffer が NULL 以外で ReportType が有効な場合、ルーチンは次の処理を行います。

ReportType がCDB_REPORT_BITSの場合、ルーチンはポート番号の使用法を指定するビット配列を返します。出力バッファー内の各ビットは、ポート番号に対応します。 0 から始まるインデックスを使用すると、 Buffer のバイトゼロのビット 0 は COM1 に対応し、ビット 1 は COM2 に対応します。ビット値 1 はポート番号が使用中であることを示し、値 0 はポート番号が使用されていないことを示します。ルーチンが使用状況情報を返すポート番号の数は、現在のデータベースサイズの最小値とバッファー内のビット数 (BufferSize*8) です。 MaxPortsReported が NULL 以外の場合、ルーチンは、ルーチンが使用状況情報を返すポート番号の数に *MaxPortsReported も設定します。 BufferSize が 0 の場合、ポート使用状況情報は返されません。*MaxPortsReported は 0 に設定されます。
ReportType がCDB_REPORT_BYTESの場合、ルーチンはポート番号の使用法を指定するバイト配列を返します。返される情報の各バイトは、異なるポート番号に対応します。 0 から始まるインデックスを使用すると、 Buffer の バイト 0 は COM1 に対応し、バイト 1 は COM2 に対応します。バイト値 1 はポート番号が使用中であることを示し、値 0 はポート番号が使用されていないことを示します。ルーチンが使用状況情報を返すポート番号の数は、現在のデータベースサイズと BufferSize の最小値です。ルーチンは *MaxPortsReported を設定しません。 BufferSize が 0 の場合、ポートの使用状況情報は返されません。