//+-------------------------------------------------------------------------
//
//  Microsoft Windows
//  Copyright (c) Microsoft Corporation. All rights reserved.
//
//  File: HNetBcon.idl
//
//  Contents: This interface definition contains objects to query ICS Beaconing Service
//
//  History:  09-JUL-00 RGatta - created file
//
//--------------------------------------------------------------------------


cpp_quote("//+--------------------------------------------------------------------------")
cpp_quote("//")
cpp_quote("//  Microsoft Windows")
cpp_quote("//  Copyright (c) Microsoft Corporation. All rights reserved.")
cpp_quote("//")
cpp_quote("//---------------------------------------------------------------------------")

// This file will be processed by the MIDL tool to
// produce the type library (HomeNetBeaconObjects.tlb) and marshalling code.

#ifndef DO_NO_IMPORTS
import "unknwn.idl";
import "wtypes.idl";
#endif


cpp_quote("")
cpp_quote("EXTERN_C const CLSID CLSID_InternetConnectionBeaconService;")


// Reserved GUIDS for our use
//
//04df6137-5610-11d4-9ec8-00b0d022dd1f    IID_IInternetConnectionDevice
//04df6138-5610-11d4-9ec8-00b0d022dd1f    IID_IInternetConnectionDeviceSharedConnection
//04df6139-5610-11d4-9ec8-00b0d022dd1f    IID_IInternetConnectionDeviceClient
//04df613a-5610-11d4-9ec8-00b0d022dd1f    CLSID_InternetConnectionBeaconService
//...
//04df6199-5610-11d4-9ec8-00b0d022dd1f
//04df619a-5610-11d4-9ec8-00b0d022dd1f


interface IInternetConnectionDevice;
interface IInternetConnectionDeviceSharedConnection;
interface IInternetConnectionDeviceClient;


//===========================================================================
//
// USAGE NOTES:
//
// The two interfaces (IInternetConnectionDevice and
// IInternetConnectionDeviceSharedConnection) defined below are designed 
// primarily for querying the ICS Device state. Since this implies in a query
// and response behaviour, the caller may be blocked till a reply is received.
// For this reason, such functions have been written to be used in BLOCKING
// and NON-BLOCKING modes. The last parameter in each of these query
// functions is a boolean value which if TRUE means block else dont block.
//
// (Also note that the control functions are ALL blocking calls - no option
//  is provided here for non-blocking.)
//
// SEMANTICS:
//
// +     Blocking Mode : This would mean that the component would do a fresh
//                       query for the required information and return the
//                       most uptodate information. The maximum delay for a
//                       blocking call would be 9 seconds.
//
// + Non-Blocking Mode : This would mean that the component would return
//                       the latest cached information in its information
//                       store.
//
// Default Mode is Blocking Mode (TRUE) which means a fresh query each time.
//
//
// SPECIFIC FUNCTION NOTES:
//
// GetICSDeviceNameInfo : the MachineName that is returned by the ICS Device
//     depends on the naming conventions used by the ICS Device. If the
//     ICS Device is NT based, then the name returned will be the
//     NetBIOS name (assuming NetBIOS is enabled).
//
// GetICSDeviceOSVersion : the OSVersion (ICS_OS_VER) field tells us the kind
//     of OS we are receiving the beacon from. Special processing is done
//     for a Windows Millenium (WINME_OS) beacon. Default values will be
//     returned in such a case. The use of such a beacon is deprecated.
//
//===========================================================================




//===========================================================================
//
// IInternetConnectionDevice Interface
//
//  The IInternetConnectionDevice interface is used to query state of the
//  ICS Host Beaconing Device
//
//
// [Member functions]
//
// IsICSDeviceAvailable        - returns the presence of ICS Beacon Device
//                               on the (private) connected network.
//
// GetICSDeviceNameInfo        - returns info on the machine hosting the 
//                               ICS shared connection.
//
// GetICSDeviceSystemTime      - returns the system time on the machine hosting
//                               the ICS shared connection as a FILETIME.
//
// GetICSDeviceOSVersion       - returns OS version info on the machine hosting
//                               the ICS shared connection.
//

[
    object,
    uuid(04df6137-5610-11d4-9ec8-00b0d022dd1f),
    helpstring("HomeNet ICS Beacon Device info"),
    pointer_default(unique)
]
interface IInternetConnectionDevice : IUnknown
{
    HRESULT
    IsICSDeviceAvailable(
        [in] BOOL fBlock
        );

    HRESULT
    GetICSDeviceNameInfo(
        [out, string] LPOLESTR *ppszMachineName,
        [out, string] LPOLESTR *ppszDomainName,
        [out, string] LPOLESTR *ppszSharedAdapterName,
        [in] BOOL fBlock
        );

    HRESULT
    GetICSDeviceSystemTime(
        [out] FILETIME *pTime,
        [in] BOOL fBlock
        );

    //
    // The ICS_OSVER is meant to help identifying which kind of beacon we are
    // receiving. A WINME beacon calls for special exception handling since
    // its use is deprecated.
    //
    typedef [v1_enum] enum tagICS_OS_VER
    {
        WINDOWS_OS        = 1,     // beacon sent by versions of Windows before WinME (none)
        WINME_OS          = 2,     // beacon sent by WinME (deprecated unsupported version)
        WINNT_OS          = 3,     // beacon sent by versions of NT (prime supported version)
        OTHER_OS          = 4,     // beacon sent by none of the above && non NT based OSes
        UNK_OS            = 5      // beacon sent by unknown OS
    } ICS_OS_VER;

    HRESULT
    GetICSDeviceOSVersion(
        [out] ICS_OS_VER *pOSVersion,
        [out] DWORD *pdwOSMajorVersion,
        [out] DWORD *pdwOSMinorVersion,
        [out] DWORD *pdwOSBuildNumber,
        [out, string] LPOLESTR *ppszOSName,
        [out, string] LPOLESTR *ppszPlatformName,
        [in] BOOL fBlock
        );


}



//===========================================================================
//
// IInternetConnectionDeviceSharedConnection Interface
//
//  The IInternetConnectionDeviceSharedConnection interface is used to query
//  state of the shared (single public) connection
//
//
// [Member functions]
//
// Connect            - If the public interface is a LAN connection,
//                      it is enabled
//                      If the public interface is a RAS connection,
//                      it is dialed
//
// Disconnect         - If the public interface is a LAN connection,
//                      it is disabled
//                      If the public interface is a RAS connection,
//                      it is disconnected
//
// GetDialState       - returns the current state of the shared connection
//
// GetConnectionInfo  - returns the bytes & packets, sent & received on the
//                      shared connection as well duration (in secs) connection
//                      has been up
//
// GetConnectionSpeed - returns the connection speed of the
//                      shared connection
//
// GetConnectionType  - returns the type of the shared connection
//

[
    object,
    uuid(04df6138-5610-11d4-9ec8-00b0d022dd1f),
    helpstring("HomeNet ICS Beacon Device's shared connection"),
    pointer_default(unique)
]
interface IInternetConnectionDeviceSharedConnection : IUnknown
{
    HRESULT
    Connect(
        );

    HRESULT
    Disconnect(
        );

    typedef [v1_enum] enum tagICS_CONN_DIAL_STATE
    {
        STARTING       = 1,
        CONNECTING     = 2,
        CONNECTED      = 3,
        DISCONNECTING  = 4,
        DISCONNECTED   = 5,
        STOPPED        = 6,
        PERMANENT      = 7,
        UNK_DIAL_STATE = 8,
        CALLWAITING    = 9
    } ICS_CONN_DIAL_STATE;
    
    HRESULT
    GetDialState(
        [out] ICS_CONN_DIAL_STATE *pDialState,
        [in] BOOL fBlock
        );

    HRESULT
    GetConnectionInfo(
        [out] ULONGLONG *pBytesSent,
        [out] ULONGLONG *pBytesRecv,
        [out] ULONGLONG *pPktsSent,
        [out] ULONGLONG *pPktsRecv,
        [out] ULONGLONG *pUptime,
        [in] BOOL fBlock
        );

    HRESULT
    GetConnectionSpeed(
        [out] DWORD *pdwBps,
        [in] BOOL fBlock
        );

    typedef [v1_enum] enum tagICS_CONN_TYPE
    {
        LAN            = 1,
        RAS            = 2,
        UNK_CONN_TYPE  = 3
    } ICS_CONN_TYPE;
    
    HRESULT
    GetConnectionType(
        [out] ICS_CONN_TYPE *pConnectionType,
        [in] BOOL fBlock
        );

};


//===========================================================================
//
// IInternetConnectionDeviceClient Interface
//
//  The IInternetConnectionDeviceClient interface is used to query
//  the local client which listens to the ICS Device.
//
//
// [Member functions]
//
// GetAdapterGuid     - returns the guid of the adapter on which the local
//                      client is listening for the beacon packets
//

[
    object,
    uuid(04df6139-5610-11d4-9ec8-00b0d022dd1f),
    helpstring("HomeNet ICS Beacon Device's Local Client"),
    pointer_default(unique)
]
interface IInternetConnectionDeviceClient : IUnknown
{

    HRESULT
    GetAdapterGuid(
        [out] GUID **ppGuid
        );

};