//+-------------------------------------------------------------------------
//
// 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
);
};