ComDBGetCurrentPortUsage-Funktion (msports.h)

Artikel
03/04/2024

ComDBGetCurrentPortUsage gibt Informationen zu den COM-Portnummern zurück, die derzeit in der COM-Portdatenbank als "verwendet" protokolliert werden.

Syntax

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

Parameter

[in] HComDB

Handle mit der COM-Portdatenbank, die von ComDBOpen zurückgegeben wurde.

[out, optional] Buffer

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in dem die Routine Informationen zur COM-Portnummer zurückgibt. Weitere Informationen finden Sie im Abschnitt Hinweise.

[in] BufferSize

Gibt die Größe eines vom Aufrufer zugewiesenen Puffers in Bytes bei Buffer an.

[in] ReportType

Gibt eines der folgenden Flags an.

Flag	Bedeutung
CDB_REPORT_BITS	Die Routine gibt ein Bitarray bei Buffer zurück, das die Portnummernutzung angibt.
CDB_REPORT_BYTES	Die Routine gibt ein Bytearray bei Buffer zurück, das die Verwendung der Portnummer angibt.

[out, optional] MaxPortsReported

Zeiger auf den Wert, den die Routine verwendet, um die Anzahl der Ports zurückzugeben, für die die Routine Informationen bei Buffer zurückgibt. Weitere Informationen finden Sie im Abschnitt Hinweise.

Rückgabewert

ComDBGetCurrentPortUsage gibt einen der folgenden status-Werte zurück.

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Routine hat erfolgreich Informationen zur Portnummer-Nutzung zurückgegeben.
ERROR_INVALID_PARAMETER	Eine der folgenden Punkte ist wahr: Das angegebene Handle für die COM-Portdatenbank ist ungültig. Sowohl Buffer als auch MaxPortsReports sind NULL. ReportType ist ungültig.
ERROR_NOT_CONNECTED	Die Routine konnte nicht auf die Datenbank zugreifen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Durch Festlegen von Puffer auf NULL und MaxPortsReported auf einen gültigen Zeiger kann ein Aufrufer die aktuelle COM-Portdatenbankgröße bestimmen, d. h. die Anzahl der COM-Portnummern, die derzeit in der Datenbank festgelegt werden. In diesem Fall legt die Routine *MaxPortsReported auf die Datenbankgröße fest. ReportType wird nicht verwendet.

Wenn Puffer nicht NULL und ReportType gültig ist, führt die Routine folgendes aus:

Wenn ReportType CDB_REPORT_BITS ist, gibt die Routine ein Bitarray zurück, das die Portnummernnutzung angibt. Jedes Bit im Ausgabepuffer entspricht einer Portnummer. Bei Verwendung eines nullbasierten Index entspricht Bit null byte null bei Buffer COM1, Bit 1 entspricht COM2 usw. Ein Bitwert von 1 gibt an, dass die Portnummer verwendet wird, und der Wert 0 gibt an, dass die Portnummer nicht verwendet wird. Die Anzahl der Portnummern, für die die Routine Nutzungsinformationen zurückgibt, entspricht dem Minimum der aktuellen Datenbankgröße und der Anzahl der Bits im Puffer (BufferSize*8). Wenn MaxPortsReported nicht NULL ist, legt die Routine *MaxPortsReported auch auf die Anzahl der Portnummern fest, für die die Routine Nutzungsinformationen zurückgibt. Wenn BufferSize 0 ist, werden keine Informationen zur Portnutzung zurückgegeben, und *MaxPortsReported ist auf 0 festgelegt.
Wenn ReportType CDB_REPORT_BYTES ist, gibt die Routine ein Bytearray zurück, das die Verwendung der Portnummer angibt. Jedes Byte in den zurückgegebenen Informationen entspricht einer anderen Portnummer. Bei Verwendung eines nullbasierten Index entspricht Byte null bei Buffer COM1, Byte 1 entspricht COM2 usw. Ein Bytewert von 1 gibt an, dass die Portnummer verwendet wird, und der Wert 0 gibt an, dass die Portnummer nicht verwendet wird. Die Anzahl der Portnummern, für die die Routine Nutzungsinformationen zurückgibt, entspricht dem Minimum der aktuellen Datenbankgröße und BufferSize. Die Routine legt *MaxPortsReported nicht fest. Wenn BufferSize null ist, werden keine Portnutzungsinformationen zurückgegeben.