windows-nt/Source/XPSP1/NT/published/sdk/inc/msports.h

//+-------------------------------------------------------------------
//
//  Microsoft Windows
//  Copyright (C) Microsoft Corporation, 1993-1999.
//
//  File:        msports.h
//
//  Contents:    public header file for COM name arbitration database
//               and Advanced dialog override and invocation
//
//--------------------------------------------------------------------

#ifndef _MSPORTS_H
#define _MSPORTS_H

#if _MSC_VER > 1000
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#ifdef SERIAL_ADVANCED_SETTINGS

/*++

Routine Description:

    Displays the advanced properties dialog for the COM port specified by
    DeviceInfoSet and DeviceInfoData.

Arguments:

    ParentHwnd  - the parent window of the window to be displayed

    DeviceInfoSet, DeviceInfoData - SetupDi structures representing the COM port

Return Value:

    ERROR_SUCCESS if the dialog was shown

  --*/
LONG
SerialDisplayAdvancedSettings(IN HWND             ParentHwnd,
                              IN HDEVINFO         DeviceInfoSet,
                              IN PSP_DEVINFO_DATA DeviceInfoData
                              );

/*++

Routine Description:

    Prototype to allow serial port vendors to override the advanced dialog
    represented by the COM port specified by DeviceInfoSet and DeviceInfoData.

    To override the advanced page, place a value named EnumAdvancedDialog under
    the same key in which you would put your EnumPropPages32 value.  The format
    of the value is exactly the same as Enum...32 as well.

Arguments:

    ParentHwnd  - the parent window of the window to be displayed

    HidePollingUI - If TRUE, hide all UI that deals with polling.

    DeviceInfoSet, DeviceInfoData - SetupDi structures representing the COM port

    Reserved - Unused

Return Value:

    TRUE if the user pressed OK, FALSE if Cancel was pressed
--*/

typedef
BOOL
(*PPORT_ADVANCED_DIALOG) (
    IN HWND             ParentHwnd,
    IN BOOL             HidePollingUI,
    IN HDEVINFO         DeviceInfoSet,
    IN PSP_DEVINFO_DATA DeviceInfoData,
    IN PVOID            Reserved
    );

#endif

DECLARE_HANDLE(HCOMDB);
typedef HCOMDB *PHCOMDB;
#define HCOMDB_INVALID_HANDLE_VALUE ((HCOMDB) INVALID_HANDLE_VALUE)

//
// Minimum through maximum number of COM names arbitered
//
#define COMDB_MIN_PORTS_ARBITRATED 256
#define COMDB_MAX_PORTS_ARBITRATED 4096

LONG
WINAPI
ComDBOpen (
    PHCOMDB PHComDB
    );
/*++

Routine Description:

    Opens name data base, and returns a handle to be used in future calls.

Arguments:

    None.

Return Value:

    INVALID_HANDLE_VALUE if the call fails, otherwise a valid handle

    If INVALID_HANDLE_VALUE, call GetLastError() to get details (??)

--*/

LONG
WINAPI
ComDBClose (
    HCOMDB HComDB
    );
/*++

Routine Description:

    frees a handle to the database returned from OpenComPortDataBase

Arguments:

    Handle returned from OpenComPortDataBase.

Return Value:

    None

--*/

#define CDB_REPORT_BITS      0x0
#define CDB_REPORT_BYTES     0x1

LONG
WINAPI
ComDBGetCurrentPortUsage (
    HCOMDB   HComDB,
    PBYTE    Buffer,
    DWORD    BufferSize,
    ULONG    ReportType, // CDB_REPORT value
    LPDWORD  MaxPortsReported
    );
/*++

Routine Description:

    if Buffer is NULL, than MaxPortsReported will contain the max number of ports
        the DB will report (this value is NOT the number of bytes need for Buffer).
        ReportType is ignored in this case.

    if ReportType == CDB_REPORT_BITS
        returns a bit array indicating if a comX name is claimed.
        ie, Bit 0 of Byte 0 is com1, bit 1 of byte 0 is com2 and so on.

        BufferSize >= MaxPortsReported / 8


    if ReportType == CDB_REPORT_BYTES
        returns a byte array indicating if a comX name is claimed.  Zero unused, non zero
        used, ie, byte 0 is com1, byte 1 is com2, etc

        BufferSize >= MaxPortsReported

Arguments:

    Handle returned from OpenComPortDataBase.

    Buffer pointes to memory to place bit array

    BufferSize   Size of buffer in bytes

    MaxPortsReported    Pointer to DWORD that holds the number of bytes in buffer filled in

Return Value:

    returns ERROR_SUCCESS if successful.
            ERROR_NOT_CONNECTED cannot connect to DB
            ERROR_MORE_DATA if buffer not large enough

--*/


LONG
WINAPI
ComDBClaimNextFreePort (
    HCOMDB   HComDB,
    LPDWORD  ComNumber
    );
/*++

Routine Description:

    returns the first free COMx value

Arguments:

    Handle returned from OpenComPortDataBase.

Return Value:


    returns ERROR_SUCCESS if successful. or other ERROR_ if not

    if successful, then ComNumber will be that next free com value and claims it in the database


--*/



LONG
WINAPI
ComDBClaimPort (
    HCOMDB   HComDB,
    DWORD    ComNumber,
    BOOL     ForceClaim,
    PBOOL    Forced /* optional */
    );
/*++

Routine Description:

    Attempts to claim a com name in the database

Arguments:

    DataBaseHandle - returned from OpenComPortDataBase.

    ComNumber      - The port value to be claimed

    Force          - If TRUE, will force the port to be claimed even if in use already

    Forced         - will reflect the event that the claim was forced

Return Value:


    returns ERROR_SUCCESS if port name was not already claimed, or if it was claimed
                          and Force was TRUE.

            ERROR_SHARING_VIOLATION if port name is use and Force is false


--*/

LONG
WINAPI
ComDBReleasePort (
    HCOMDB   HComDB,
    DWORD    ComNumber
    );
/*++

Routine Description:

    Releases the port in the database

Arguments:

    DatabaseHandle - returned from OpenComPortDataBase.

    ComNumber      - port to be unclaimed in database

Return Value:


    returns ERROR_SUCCESS if successful
            ERROR_CANTWRITE if the changes cannot be committed
            ERROR_INVALID_PARAMETER if ComNumber is greater than the number of
                                    ports arbitrated


--*/

LONG
WINAPI
ComDBResizeDatabase (
    HCOMDB   HComDB,
    DWORD    NewSize
    );
/*++

Routine Description:

    Resizes the database to the new size.  To get the current size, call
    ComDBGetCurrentPortUsage with a Buffer == NULL.

Arguments:

    DatabaseHandle - returned from OpenComPortDataBase.

    NewSize        - must be a multiple of 1024, with a max of 4096

Return Value:


    returns ERROR_SUCCESS if successful
            ERROR_CANTWRITE if the changes cannot be committed
            ERROR_BAD_LENGTH if NewSize is not greater than the current size or
                             NewSize is greater than COMDB_MAX_PORTS_ARBITRATED

--*/


#ifdef __cplusplus
}
#endif


#endif // _MSPORTS_H