ComDBGetCurrentPortUsage 函式 (msports.h)

發行項
03/05/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

指定 緩衝區上呼叫端配置緩衝區的大小，以位元組為單位。

[in] ReportType

指定下列其中一個旗標。

旗標	意義
CDB_REPORT_BITS	例程會在 Buffer 傳回位數組，指定埠號碼使用方式。
CDB_REPORT_BYTES	例程會在 Buffer 傳回位元組陣列，指定埠號碼使用方式。

[out, optional] MaxPortsReported

例程用來傳回 在 Buffer 傳回資訊的埠數目的值指標。如需詳細資訊，請參閱＜備註＞一節。

傳回值

ComDBGetCurrentPortUsage 會傳回下列其中一個狀態值。

傳回碼	Description
ERROR_SUCCESS	例程已成功傳回埠號碼使用資訊。
ERROR_INVALID_PARAMETER	下列其中一個是 true：COM 埠資料庫的指定句柄無效。 Buffer 和 MaxPortsReports 都是 NULL。 ReportType 無效。
ERROR_NOT_CONNECTED	例程無法存取資料庫。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

藉由將 Buffer 設定為 NULL ，並將 MaxPortsReported 設定為有效的指標，呼叫端可以判斷目前的 COM 埠資料庫大小，這是目前在資料庫中仲裁的 COM 埠號碼數目。在此情況下，例程會將 *MaxPortsReported 設定為資料庫大小。不使用 ReportType。

如果 Buffer 為非 NULL 且 ReportType 有效，則例程會執行下列動作：

如果 ReportType 是CDB_REPORT_BITS，例程會傳回指定埠號碼使用量的位數組。輸出緩衝區中的每個位都會對應至埠號碼。使用以零起始的索引， Buffer 的位零位元組零會對應至 COM1、位 1 對應至 COM2 等等。位值為 1 表示埠號碼正在使用中，而值為零表示埠號碼不在使用中。例程傳回使用量資訊的埠號碼數目是目前資料庫大小下限和緩衝區中的位數目， (BufferSize*8) 。如果 MaxPortsReported 不是 NULL，例程也會將 *MaxPortsReported 設定為例程傳回使用資訊所在的埠號碼數目。如果 BufferSize 為零，則不會傳回埠使用資訊，且 *MaxPortsReported 設定為零。
如果 ReportType 是CDB_REPORT_BYTES，例程會傳回指定埠號碼使用量的位元組陣列。傳回資訊中的每個位元組都會對應至不同的埠號碼。使用以零起始的索引時， Buffer 的位元組零會對應至 COM1、位元組 1 對應至 COM2 等等。位元組值為 1 表示埠號碼正在使用中，而值為零表示埠號碼不在使用中。例程傳回使用量資訊的埠號碼數目是目前資料庫大小和 BufferSize 的最小值。例程未設定 *MaxPortsReported。如果 BufferSize 為零，則不會傳回埠使用資訊。