Fonction ComDBGetCurrentPortUsage (msports.h)

Article
08/25/2023

ComDBGetCurrentPortUsage retourne des informations sur les numéros de port COM actuellement enregistrés comme « en cours d’utilisation » dans la base de données des ports COM.

Syntaxe

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

Paramètres

[in] HComDB

Gérez la base de données de port COM retournée par ComDBOpen.

[out, optional] Buffer

Pointeur vers une mémoire tampon allouée à l’appelant dans laquelle la routine retourne des informations sur le numéro de port COM. Pour plus d'informations, consultez la section Notes.

[in] BufferSize

Spécifie la taille, en octets, d’une mémoire tampon allouée à l’appelant au niveau de la mémoire tampon.

[in] ReportType

Spécifie l’un des indicateurs suivants.

Indicateur	Signification
CDB_REPORT_BITS	La routine retourne un tableau de bits dans La mémoire tampon qui spécifie l’utilisation du numéro de port.
CDB_REPORT_BYTES	La routine retourne un tableau d’octets dans La mémoire tampon qui spécifie l’utilisation du numéro de port.

[out, optional] MaxPortsReported

Pointeur vers la valeur utilisée par la routine pour renvoyer le nombre de ports pour lesquels la routine retourne des informations dans La mémoire tampon. Pour plus d'informations, consultez la section Notes.

Valeur retournée

ComDBGetCurrentPortUsage retourne l’une des valeurs status suivantes.

Code de retour	Description
ERROR_SUCCESS	La routine a correctement retourné les informations d’utilisation du numéro de port.
ERROR_INVALID_PARAMETER	L’une des conditions suivantes est vraie : le handle spécifié pour la base de données de port COM n’est pas valide. Buffer et MaxPortsReports ont la valeur NULL. ReportType n’est pas valide.
ERROR_NOT_CONNECTED	La routine n’a pas pu accéder à la base de données. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

En définissant Buffer sur NULL et MaxPortsReported sur un pointeur valide, un appelant peut déterminer la taille actuelle de la base de données de port COM, qui correspond au nombre de numéros de port COM actuellement arbitrés dans la base de données. Dans ce cas, la routine définit *MaxPortsReported sur la taille de la base de données. ReportType n’est pas utilisé.

Si La mémoire tampon n’a pas la valeur NULL et que ReportType est valide, la routine effectue les opérations suivantes :

Si ReportType est CDB_REPORT_BITS, la routine retourne un tableau de bits qui spécifie l’utilisation du numéro de port. Chaque bit dans la mémoire tampon de sortie correspond à un numéro de port. À l’aide d’un index de base zéro, le bit zéro de l’octet zéro au niveau de la mémoire tampon correspond à COM1, le bit 1 correspond à COM2, et ainsi de suite. La valeur de bit 1 indique que le numéro de port est en cours d’utilisation et une valeur de zéro indique que le numéro de port n’est pas en cours d’utilisation. Le nombre de numéros de port pour lesquels la routine retourne des informations d’utilisation est le minimum de la taille actuelle de la base de données et le nombre de bits dans la mémoire tampon (BufferSize*8). Si MaxPortsReported n’a pas la valeur NULL, la routine définit également *MaxPortsReported sur le nombre de numéros de port pour lesquels la routine retourne des informations d’utilisation. Si BufferSize a la valeur zéro, aucune information d’utilisation du port n’est retournée et *MaxPortsReported est défini sur zéro.
Si ReportType est CDB_REPORT_BYTES, la routine retourne un tableau d’octets qui spécifie l’utilisation du numéro de port. Chaque octet dans les informations retournées correspond à un numéro de port différent. À l’aide d’un index de base zéro, l’octet zéro de la mémoire tampon correspond à COM1, l’octet 1 correspond à COM2, et ainsi de suite. Une valeur d’octet de 1 indique que le numéro de port est en cours d’utilisation et une valeur de zéro indique que le numéro de port n’est pas en cours d’utilisation. Le nombre de numéros de port pour lesquels la routine retourne des informations d’utilisation est le minimum de la taille de base de données actuelle et de BufferSize. La routine ne définit pas *MaxPortsReported. Si BufferSize est égal à zéro, aucune information d’utilisation du port n’est retournée.