Função ComDBGetCurrentPortUsage (msports.h)

Artigo
08/25/2023

ComDBGetCurrentPortUsage retorna informações sobre os números da porta COM que estão atualmente registrados como "em uso" no banco de dados de porta COM.

Sintaxe

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

Parâmetros

[in] HComDB

Manipule para o banco de dados de porta COM que foi retornado pelo ComDBOpen.

[out, optional] Buffer

Ponteiro para um buffer alocado pelo chamador no qual a rotina retorna informações sobre o número da porta COM. Consulte a seção Comentários para obter mais informações.

[in] BufferSize

Especifica o tamanho, em bytes, de um buffer alocado pelo chamador no Buffer.

[in] ReportType

Especifica um dos sinalizadores a seguir.

Sinalizador	Significado
CDB_REPORT_BITS	A rotina retorna uma matriz de bits no Buffer que especifica o uso do número da porta.
CDB_REPORT_BYTES	A rotina retorna uma matriz de bytes no Buffer que especifica o uso do número da porta.

[out, optional] MaxPortsReported

Ponteiro para o valor que a rotina usa para retornar o número de portas para as quais a rotina retorna informações em Buffer. Consulte a seção Comentários para obter mais informações.

Retornar valor

ComDBGetCurrentPortUsage retorna um dos seguintes valores de status.

Código de retorno	Descrição
ERROR_SUCCESS	A rotina retornou com êxito as informações de uso do número da porta.
ERROR_INVALID_PARAMETER	Uma das opções a seguir é verdadeira: o identificador especificado para o banco de dados de porta COM não é válido. Buffer e MaxPortsReports são NULL. ReportType não é válido.
ERROR_NOT_CONNECTED	A rotina não pôde acessar o banco de dados. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Ao definir Buffer como NULL e MaxPortsReported como um ponteiro válido, um chamador pode determinar o tamanho atual do banco de dados da porta COM, que é o número de números de porta COM que estão atualmente arbitrados no banco de dados. Nesse caso, a rotina define *MaxPortsReported como o tamanho do banco de dados. ReportType não é usado.

Se Buffer não for NULL e ReportType for válido, a rotina fará o seguinte:

Se ReportType for CDB_REPORT_BITS, a rotina retornará uma matriz de bits que especifica o uso do número da porta. Cada bit no buffer de saída corresponde a um número de porta. Usando um índice baseado em zero, o bit zero de byte zero no Buffer corresponde a COM1, o bit 1 corresponde ao COM2 e assim por diante. Um valor de bit de 1 indica que o número da porta está em uso e um valor igual a zero indica que o número da porta não está em uso. O número de números de porta para os quais a rotina retorna informações de uso é o mínimo do tamanho atual do banco de dados e o número de bits no buffer (BufferSize*8). Se MaxPortsReported não for NULL, a rotina também definirá *MaxPortsReported como o número de números de porta para os quais a rotina retorna informações de uso. Se BufferSize for zero, nenhuma informação de uso da porta será retornada e *MaxPortsReported será definido como zero.
Se ReportType for CDB_REPORT_BYTES, a rotina retornará uma matriz de bytes que especifica o uso do número da porta. Cada byte nas informações retornadas corresponde a um número de porta diferente. Usando um índice baseado em zero, o byte zero em Buffer corresponde a COM1, byte 1 corresponde a COM2 e assim por diante. Um valor de byte de 1 indica que o número da porta está em uso e um valor igual a zero indica que o número da porta não está em uso. O número de números de porta para os quais a rotina retorna informações de uso é o mínimo do tamanho atual do banco de dados e bufferSize. A rotina não define *MaxPortsReported. Se BufferSize for zero, nenhuma informação de uso da porta será retornada.