vcecominterfaces.idl

EVC4.rar

/*==================================================================
	File:		VCEComInterfaces.idl
	
	Contains:	Definition of VirtualCE's COM interfaces.
	
				This file is compiled by the MIDL.exe tool
				to create the C/C++ header files, code for
				building the marshalling DLL, and the
				type library (VCEComInterfaces.tlb)
				
	Written by:	Jake Hoelter
	
	Copyright:	2001 Connectix Corporation
==================================================================*/

import "oaidl.idl";		// Standard types
import "ocidl.idl";

cpp_quote( "const ULONG kVCETypeLibrary_MajorVersion = 1;" )
cpp_quote( "const ULONG kVCETypeLibrary_MinorVersion = 0;" )


/*------------------------------------------------------------------
	IDMATransportCompletionSink interface.
	
------------------------------------------------------------------*/
[
	object,
	uuid(AC6A6347-ECE0-46c1-B668-9DF3A17153C8),
	helpstring("IDMATransportCompletionSink Interface"),
	pointer_default(unique)
]

// {AC6A6347-ECE0-46c1-B668-9DF3A17153C8}
//	DEFINE_GUID(<<name>>,0xac6a6347, 0xece0, 0x46c1, 0xb6, 0x68, 0x9d, 0xf3, 0xa1, 0x71, 0x53, 0xc8);

interface IDMATransportCompletionSink : IUnknown
{
	HRESULT CompletionCallback( 
		[in] DWORD	stage );
};

/*------------------------------------------------------------------
	IEmulatorVirtualMachineManager interface.
	
	This interface allows the caller to manipulate virtual machines
	within VirtualCE. It effectively replaces the standard
	VirtualPC configuration dialog with a programmatic interface.
	
	It is used by Microsoft's CE Platform Builder tools to
	control the virtual machines.
------------------------------------------------------------------*/
[
	object,
	uuid(71D756A3-B729-472b-9C90-12F393A9BFF8),
	helpstring("IEmulatorVirtualMachineManager Interface"),
	pointer_default(unique)
]

interface IEmulatorVirtualMachineManager : IUnknown
{
	[ helpstring("Gets count of all virtual machines available (running or not)") ]
	HRESULT GetVirtualMachineCount(
		[out, retval] ULONG* numberOfVMs );
	
	[ helpstring("Gets array of GUIDs of all virtual machines available (running or not)") ]
	HRESULT EnumerateVirtualMachines(
		[in, out] ULONG* numberOfVMs,
		[out, size_is(*numberOfVMs)] GUID virtualMachineID[] );
	
	[ helpstring("Tests if a virtual machine is running or not, returns error if unknown machine ID") ]
	HRESULT IsVirtualMachineRunning(
		[in]  		  GUID*		virtualMachineID,
		[out, retval] boolean*	isRunning );
		
	[ helpstring("Resets a virtual machine, either a hard or soft reset") ]
	HRESULT ResetVirtualMachine(
		[in] GUID*		virtualMachineID,
		[in] boolean	hardReset );
	
	[ helpstring("Starts a new virtual machine using command line parameters") ]
	HRESULT CreateVirtualMachine(
		[in] LPOLESTR	commandLine );
	
	[ helpstring("Starts a new virtual machine using command line parameters and installs a callback for DMA transport completion routine") ]
	HRESULT CreateVirtualMachineWithTransportCompletion(
		[in] LPOLESTR						commandLine,
		[in]IDMATransportCompletionSink*	completionSink,
		[in] DWORD 							dmaTransportCompletionRoutineIdentifier ); // IRQ of desired DMA channel
		
	[ helpstring("Shuts down a virtual machine, optionally saving the state") ]
	HRESULT ShutdownVirtualMachine(
		[in] GUID*		virtualMachineID,
		[in] boolean	saveMachine );
	
	[ helpstring("Restores a previously saved virtual machine") ]
	HRESULT RestoreVirtualMachine(
		[in] GUID*		virtualMachineID );
		
	[ helpstring("Restores a previously saved virtual machine and installs a callback for DMA transport completion routine") ]
	HRESULT RestoreVirtualMachineWithTransportCompletion(
		[in] GUID*							virtualMachineID,
		[in]IDMATransportCompletionSink*	completionSink,
		[in] DWORD 							dmaTransportCompletionRoutineIdentifier ); // IRQ of desired DMA channel
	
	[ helpstring("Deletes a previously saved virtual machine") ]
	HRESULT DeleteVirtualMachine(
		[in] GUID*		virtualMachineID );
	
	[ helpstring("Returns the name of a virtual machine") ]
	HRESULT GetVirtualMachineName(
		[in]  GUID*		virtualMachineID,
		[out] LPOLESTR*	virtualMachineName );
	
	[ helpstring("Sets the name of a virtual machine") ]
	HRESULT SetVirtualMachineName(
		[in] GUID*		virtualMachineID,
		[in] LPOLESTR	virtualMachineName );
		
	[ helpstring("Un-installs a callback for DMA transport completion routine.") ]
	HRESULT UninstallVirtualMachineDMATransportCompletionRoutine (
		[in] GUID*		inVirtualMachineID,
		[in] DWORD 		inId ); // IRQ of desired DMA channel
	
	[ helpstring("Bring a VM Window to be frontmost") ]
	HRESULT BringVirtualMachineToFront(
		[in] GUID*		virtualMachineID );
		
	HRESULT VirtualMachineManagerVersion(
	[out]DWORD* version );

};


/*------------------------------------------------------------------
	IEmulatorVirtualTransportSink interface.
	
	This is used as a callback by the IEmulatorVirtualTransport
	interface. The IEmulatorVirtualTransport object
	will call this sink when data is available.
------------------------------------------------------------------*/
[
	object,
	uuid(6747A265-2720-4c36-B778-51CD2D10524A),
	helpstring("IEmulatorVirtualTransportSink Interface"),
	pointer_default(unique)
]

interface IEmulatorVirtualTransportSink : IUnknown
{
	HRESULT ReceiveData(
		[in]					 ULONG	transportID,
		[in, size_is(byteCount)] const BYTE* dataBuffer,
		[in]					 USHORT	byteCount );
};


/*------------------------------------------------------------------
	IEmulatorVirtualTransport interface.
	
	This interface provides the connection to the kernel
	independent transport layer (KITL) to allow the Windows CE
	kernel to talk to Microsoft's Windows CE Platform Builder
	development tool. It will connect to a virtual transport
	device in the emulator.
	
	If a CE kernel is built with the emulator's kitl (a part
	of the HAL that knows how to talk to this virtual
	transport device), then the CE kernel can be debugged
	using Platform Builder.
	
	The bottom layer transport interface to Platform Builder
	is exposed as a .DLL interface rather than a COM
	interface, unfortunately. This interface mirrors the .dll
	transport interface, and the .dll simply passes calls
	through to this COM interface.
------------------------------------------------------------------*/
[
	object,
	uuid(F3D1162F-B815-4ae4-8C86-DC4A95FB3882),
	helpstring("IEmulatorVirtualTransport Interface"),
	pointer_default(unique)
]

interface IEmulatorVirtualTransport : IUnknown
{
	HRESULT Initialize();
	
	HRESULT TearDown();
	
	[ helpstring("Creates a new transport channel.") ]
	HRESULT Create(
		[in]  GUID*			virtualMachineID,
		[in]  ULONG			dmaChannel,
		[out] ULONG*		transportID );
	
	[ helpstring("Deletes a transport channel.") ]
	HRESULT Delete(
		[in] ULONG transportID );
	
	[ helpstring("Installs a callback for data receiving.") ]
	HRESULT Advise(
		[in]  IEmulatorVirtualTransportSink*	transportSink );
	
	[ helpstring("Sends data across the transport.") ]
	HRESULT Send(
		[in]					 ULONG	transportID,
		[in, size_is(byteCount)] const BYTE* dataBuffer,
		[in]					 USHORT	byteCount,
		[in]					 ULONG	timeout );
		
	[ helpstring("Polls for data received from the transport, only works if datasink hasn't been installed.") ]
	HRESULT Receive(
		[in]					   ULONG    transportID,
		[out, size_is(*byteCount), length_is(*byteCount)] BYTE*   dataBuffer,
		[in, out]				   USHORT* byteCount,
		[in]					   ULONG   timeout );
	
	[ helpstring("Indicates which virtual machine a transport should be talking to.") ]
	HRESULT SetVirtualMachineIDForTransport(
		[in] ULONG		transportID,
		[in] GUID*		virtualMachineID );
};

#if 0

/*------------------------------------------------------------------
	IVirtualMachineManagerPB interface.
	
	This interface allows the caller to manipulate virtual machines
	within VirtualCE. It effectively replaces the standard
	VirtualPC configuration dialog with a programmatic interface.
	
	It is used by Microsoft's CE Platform Builder tools to
	control the virtual machines.
------------------------------------------------------------------*/
[
	object,
	uuid(D057809F-CB63-4c28-A7E7-83A0E3E9F57C),
	helpstring("IVirtualMachineManagerPB Interface"),
	pointer_default(unique)
]
interface IVirtualMachineManagerPB : IUnknown
{
	[ helpstring("Gets count of all virtual machines available (running or not)") ]
	HRESULT GetVirtualMachineCount(
		[out, retval] ULONG* numberOfVMs );
	
	[ helpstring("Gets array of GUIDs of all virtual machines available (running or not)") ]
	HRESULT EnumerateVirtualMachines(
		[in, out] ULONG* numberOfVMs,
		[out, size_is(*numberOfVMs)] GUID virtualMachineID[] );
	
	[ helpstring("Tests if a virtual machine is running or not, returns error if unknown machine ID") ]
	HRESULT IsVirtualMachineRunning(
		[in]  		  GUID*		virtualMachineID,
		[out, retval] boolean*	isRunning );
	
	[ helpstring("Resets a virtual machine, either a hard or soft reset") ]
	HRESULT ResetVirtualMachine(
		[in] GUID*		virtualMachineID,
		[in] boolean	hardReset );
	
	[ helpstring("Starts a new virtual machine using command line parameters") ]
	HRESULT CreateVirtualMachine(
		[in] LPOLESTR	commandLine );
	
	[ helpstring("Shuts down a virtual machine, optionally saving the state") ]
	HRESULT ShutdownVirtualMachine(
		[in] GUID*		virtualMachineID,
		[in] boolean	saveMachine );
	
	[ helpstring("Restores a previously saved virtual machine") ]
	HRESULT RestoreVirtualMachine(
		[in] GUID*		virtualMachineID );
	
	[ helpstring("Deletes a previously saved virtual machine") ]
	HRESULT DeleteVirtualMachine(
		[in] GUID*		virtualMachineID );
	
	[ helpstring("Returns the name of a virtual machine") ]
	HRESULT GetVirtualMachineName(
		[in]  GUID*		virtualMachineID,
		[out] LPOLESTR*	virtualMachineName );
	
	[ helpstring("Sets the name of a virtual machine") ]
	HRESULT SetVirtualMachineName(
		[in] GUID*		virtualMachineID,
		[in] LPOLESTR	virtualMachineName );
};


/*------------------------------------------------------------------
	IVirtualTransportSinkPB interface.
	
	This is used as a callback by the IVirtualTransport
	interface. The IVirtualTransport object
	will call this sink when data is available.
------------------------------------------------------------------*/
[
	object,
	uuid(80D16A14-1241-4539-B937-651821A4C9D7),
	helpstring("IVirtualTransportSinkPB Interface"),
	pointer_default(unique)
]
interface IVirtualTransportSinkPB : IUnknown
{
	HRESULT ReceiveData(
		[in]					 ULONG	transportID,
		[in, size_is(byteCount)] const BYTE* dataBuffer,
		[in]					 USHORT	byteCount );
};


/*------------------------------------------------------------------
	IVirtualTransportPB interface.
	
	This interface provides the connection to the kernel
	independent transport layer (KITL) to allow the Windows CE
	kernel to talk to Microsoft's Windows CE Platform Builder
	development tool. It will connect to a virtual transport
	device in the emulator.
	
	If a CE kernel is built with the emulator's kitl (a part
	of the HAL that knows how to talk to this virtual
	transport device), then the CE kernel can be debugged
	using Platform Builder.
	
	The bottom layer transport interface to Platform Builder