ComDBClaimNextFreePort function

ComDBClaimNextFreePort returns the lowest COM port number that is not already in use.

Syntax


LONG WINAPI ComDBClaimNextFreePort(
  _In_  HCOMDB  HComDB,
  _Out_ LPDWORD ComNumber
);

Parameters

HComDB [in]

Handle to the COM port database that is returned by ComDBOpen.

ComNumber [out]

Pointer to the COM port number that the routine returns to the caller. This pointer must be non-NULL. A port number is an integer that ranges from 1 to COMDB_MAX_PORTS_ARBITRATED.

Return value

ComDBClaimNextFreePort returns one of the following status values.

Return codeDescription
ERROR_SUCCESS

The routine successfully returned a COM port number.

ERROR_CANTWRITE

The routine could not write to the database.

ERROR_INVALID_PARAMETER

The specified COM port database handle is not valid.

ERROR_NO_LOG_SPACE

The database cannot arbitrate any more port numbers.

ERROR_NOT_CONNECTED

The routine could not access the database. To get extended error information, call GetLastError.

ERROR_Xxx

An internal error occurred; call GetLastError to get extended error information.

 

Remarks

Claiming a COM port number in the COM port database logs the port number as "in use". Note that the database does not contain information about the caller or device that claims a port number.

ComDBClaimNextFreePort runs in user mode.

For more information, see Obtaining and Releasing a COM Port Number.

Requirements

Target platform

Desktop

Header

Msports.h (include Msports.h)

Library

Msports.lib

DLL

Msports.dll

See also

ComDBClaimPort
ComDBReleasePort

 

 

Send comments about this topic to Microsoft

Show: