Función ComDBGetCurrentPortUsage (msports.h)

Artículo
03/08/2023

ComDBGetCurrentPortUsage devuelve información sobre los números de puerto COM que se registran actualmente como "en uso" en la base de datos de puertos COM.

Sintaxis

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

Parámetros

[in] HComDB

Identificador de la base de datos de puerto COM devuelta por ComDBOpen.

[out, optional] Buffer

Puntero a un búfer asignado por el autor de la llamada en el que la rutina devuelve información sobre el número de puerto COM. Vea la sección Comentarios para obtener más información.

[in] BufferSize

Especifica el tamaño, en bytes, de un búfer asignado por el autor de la llamada en buffer.

[in] ReportType

Especifica una de las marcas siguientes.

Marca	Significado
CDB_REPORT_BITS	La rutina devuelve una matriz de bits en buffer que especifica el uso del número de puerto.
CDB_REPORT_BYTES	La rutina devuelve una matriz de bytes en buffer que especifica el uso del número de puerto.

[out, optional] MaxPortsReported

Puntero al valor que usa la rutina para devolver el número de puertos para los que la rutina devuelve información en buffer. Vea la sección Comentarios para obtener más información.

Valor devuelto

ComDBGetCurrentPortUsage devuelve uno de los siguientes valores de estado.

Código devuelto	Descripción
ERROR_SUCCESS	La rutina devolvió correctamente la información de uso del número de puerto.
ERROR_INVALID_PARAMETER	Uno de los siguientes valores es true: el identificador especificado para la base de datos de puertos COM no es válido. Buffer y MaxPortsReports son NULL. ReportType no es válido.
ERROR_NOT_CONNECTED	La rutina no pudo acceder a la base de datos. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Al establecer Buffer en NULL y MaxPortsReported en un puntero válido, un llamador puede determinar el tamaño actual de la base de datos de puerto COM, que es el número de números de puerto COM que están actualmente arbitrados en la base de datos. En este caso, la rutina establece *MaxPortsReported en el tamaño de la base de datos. No se usa ReportType.

Si Buffer no es NULL y ReportType es válido, la rutina hace lo siguiente:

Si ReportType es CDB_REPORT_BITS, la rutina devuelve una matriz de bits que especifica el uso del número de puerto. Cada bit del búfer de salida corresponde a un número de puerto. Con un índice de base cero, el bit cero de bytes cero en buffer corresponde a COM1, el bit 1 corresponde a COM2, etc. Un valor de bit de 1 indica que el número de puerto está en uso y un valor de cero indica que el número de puerto no está en uso. Número de números de puerto para los que la rutina devuelve información de uso es el mínimo del tamaño de la base de datos actual y el número de bits en el búfer (BufferSize*8). Si MaxPortsReported no es NULL, la rutina también establece *MaxPortsReported en el número de números de puerto para los que la rutina devuelve información de uso. Si BufferSize es cero, no se devuelve ninguna información de uso del puerto y *MaxPortsReported se establece en cero.
Si ReportType es CDB_REPORT_BYTES, la rutina devuelve una matriz de bytes que especifica el uso del número de puerto. Cada byte de la información devuelta corresponde a un número de puerto diferente. Con un índice de base cero, el byte cero en buffer corresponde a COM1, byte 1 corresponde a COM2, etc. Un valor de byte de 1 indica que el número de puerto está en uso y un valor de cero indica que el número de puerto no está en uso. El número de números de puerto para los que la rutina devuelve información de uso es el mínimo del tamaño de la base de datos actual y BufferSize. La rutina no establece *MaxPortsReported. Si BufferSize es cero, no se devuelve información de uso del puerto.