Поделиться через

Функция ComDBGetCurrentPortUsage (msports.h)

  • Статья

ComDBGetCurrentPortUsage возвращает сведения о номерах COM-портов, которые в настоящее время регистрируются как используемые в базе данных COM-портов.

Синтаксис

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

Параметры

[in] HComDB

Обработка базы данных COM-порта, возвращенной ComDBOpen.

[out, optional] Buffer

Указатель на буфер, выделенный вызывающим объектом, в котором подпрограмма возвращает сведения о номере COM-порта. Дополнительные сведения см. в разделе "Примечания".

[in] BufferSize

Указывает размер буфера, выделенного вызывающим объектом в байтах, в буфере.

[in] ReportType

Задает один из следующих флагов.

Flag Значение
CDB_REPORT_BITS Подпрограмма возвращает битовый массив в буфере , указывающий использование номера порта.
CDB_REPORT_BYTES Подпрограмма возвращает массив байтов в буфере , указывающий использование номера порта.

[out, optional] MaxPortsReported

Указатель на значение, используемое подпрограммой для возврата количества портов, для которых подпрограмма возвращает сведения в буфере. Дополнительные сведения см. в разделе "Примечания".

Возвращаемое значение

ComDBGetCurrentPortUsage возвращает одно из следующих значений состояния.

Код возврата Описание
ERROR_SUCCESS
 Подпрограмма успешно вернула сведения об использовании номера порта.
ERROR_INVALID_PARAMETER
 Одно из следующих значений имеет значение true: указанный дескриптор для базы данных COM-порта недопустим. Значения Buffer и MaxPortsReports имеют значение NULL. Тип отчета недопустим.
ERROR_NOT_CONNECTED
 Подпрограмме не удалось получить доступ к базе данных. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Задав параметру Bufferзначение NULL , а для Параметра MaxPortsReported — допустимый указатель, вызывающий объект может определить текущий размер базы данных COM-портов, то есть количество номеров COM-портов, которые в настоящее время находятся в базе данных. В этом случае подпрограмма устанавливает для параметра *MaxPortsReported размер базы данных. ReportType не используется.

Если параметр Buffer имеет значение, отличное от NULL, а ReportType является допустимым, подпрограмма выполняет следующие действия:

  • Если параметр ReportType CDB_REPORT_BITS, подпрограмма возвращает битовый массив, указывающий использование номера порта. Каждый бит в выходном буфере соответствует номеру порта. При использовании отсчитываемого от нуля индекса бит нулевого байта в буфере соответствует COM1, бит 1 соответствует COM2 и т. д. Битовое значение 1 указывает, что номер порта используется, а нулевое значение указывает, что номер порта не используется. Число портов, для которых подпрограмма возвращает сведения об использовании, является минимальным размером текущей базы данных и числом битов в буфере (BufferSize*8). Если параметр MaxPortsReported не равен NULL, подпрограмма также задает для параметра *MaxPortsReported число номеров портов, для которых подпрограмма возвращает сведения об использовании. Если параметр BufferSize равен нулю, сведения об использовании порта не возвращаются, а параметр *MaxPortsReported имеет значение 0.
  • Если параметр ReportType CDB_REPORT_BYTES, подпрограмма возвращает массив байтов, указывающий использование номеров портов. Каждый байт в возвращаемой информации соответствует другому номеру порта. При использовании отсчитываемого от нуля индекса нулевой байт в буфере соответствует COM1, байт 1 соответствует COM2 и т. д. Байтовое значение 1 указывает, что используется номер порта, а нулевое значение указывает, что номер порта не используется. Число номеров портов, для которых подпрограмма возвращает сведения об использовании, является минимальным для текущего размера базы данных и BufferSize. Подпрограмма не устанавливает *MaxPortsReported. Если параметр BufferSize равен нулю, сведения об использовании порта не возвращаются.
ComDBGetCurrentPortUsage выполняется в пользовательском режиме.

Требования

Требование Значение
Целевая платформа Персональный компьютер
Верхняя часть msports.h (включая Msports.h)
Библиотека Msports.lib
DLL Msports.dll

См. также раздел

ComDBClaimNextFreePort

ComDBClaimPort

ComDBResizeDatabase