ComDBGetCurrentPortUsage 函数 (msports.h)

项目
08/25/2023

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

指向例程用于返回 缓冲区中信息的端口数的指针。有关详细信息，请参阅备注部分。

返回值

ComDBGetCurrentPortUsage 返回以下状态值之一。

返回代码	说明
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 表示正在使用端口号，值为 0 表示端口号未使用。例程返回使用情况信息的端口号是当前数据库大小的最小值，缓冲区 (BufferSize*8) 位数。如果 MaxPortsReported 为非 NULL，则例程还会将 *MaxPortsReported 设置为例程返回使用情况信息的端口号数。如果 BufferSize 为零，则不返回端口使用情况信息，并且 *MaxPortsReported 设置为零。
如果 ReportType 是CDB_REPORT_BYTES，则例程将返回一个字节数组，用于指定端口号用法。返回的信息中的每个字节对应于不同的端口号。使用从零开始的索引， Buffer 中的字节 0 对应于 COM1，字节 1 对应于 COM2，依此。字节值为 1 表示正在使用端口号，值为 0 表示端口号未使用。例程返回使用情况信息的端口号是当前数据库大小和 BufferSize 的最小值。例程未设置 *MaxPortsReported。如果 BufferSize 为零，则不返回端口使用情况信息。