The most common Device Emulator API interface you use is the IDeviceEmulatorManagerVMIDinterface. The IDeviceEmulatorManagerVMIDinterface represents an individual Device Emulator image such as Windows Mobile 5.0 Pocket PC, Pocket PC 2003 SE, or Windows Mobile 6 Standard. Using the IDeviceEmulatorManagerVMIDinterface, you can programmatically perform the actions exposed by the Device Emulator Manager user interface. Table 1 shows the IDeviceEmulatorManagerVMIDinterface methods and corresponding descriptions.

Table 1. IDeviceEmulatorManagerVMID Interface Methods

Note:
The GetConfigurationand SetConfigurationmethods provide a wide variety of capabilities; a separate paper will discuss the capabilities of these functions in detail.

The following code sample demonstrates how to cradle an emulator using the IDeviceEmulatorManagerVMIDinterface.

Copy Code

void CradleEmulator(IDeviceEmulatorManagerVMID theEmulator) { if (theEmulator != null) throw new ArgumentException("Must provide a valid reference"); EMULATOR_STATE state = theEmulator.get_State(); if (state == EMULATOR_STATE.EMU_NOT_RUNNING) theEmulator.Connect(); // start emulator if (state != EMULATOR_STATE.EMU_CRADLED) theEmulator.Cradle(); // cradle to start ActiveSync else theEmulator.BringToFront(); }

To cradle the emulator, the emulator must already be running; therefore, the preceding sample code gets the emulator state by calling the get_Statemethod and then checks to see if the current state indicates that the emulator is not running. If this is the case, the program starts the emulator by calling the Connectmethod. The program then checks the emulator state to see if the emulator is already cradled. If necessary, the program then cradles the emulator by calling the Cradlemethod; cradling the emulator initiates the emulator's connection to ActiveSync (Windows XP) or Windows Mobile Device Center (Windows Vista). If the emulator is already cradled, the program gives the emulator focus by calling the BringToFrontmethod.

The beauty of the Device Emulator Manager API is that interacting with and controlling a Device Emulator is quite easy. To work with any of the Device Emulators you must first navigate through the Device Emulator Manager hierarchy.

The Device Emulator Manager hierarchy is divided into three layers. At the highest level are the categories. Categories are used to group Windows Mobile Software Development Kits (SDKs). Each SDK contains a list of Device Emulators. To locate a specific Device Emulator, you need to traverse the layers of the hierarchy above it.

Note:

The next several sections discuss the details of programmatically working with the COM-style features of the Device Emulator Manager API hierarchy. You are encouraged to read these sections to get a better understanding of the API. However, if you have only limited time available you may want to jump ahead to the A Device Emulator Manager Wrappersection, which discusses a simplified Device Emulator Manager API programming model.

To get started with the Device Emulator Manager API, you must first create an instance of the Device Emulator Manager. You do this by creating an instance of the DeviceEmulatorManagerClassclass. This class encapsulates the COM component that represents the Device Emulator Manager. When working with the Device Emulator Manager, you can use the DeviceEmulatorManagerClassclass directly or use the IDeviceEmulatorManagerinterface. Both the class and the interface provide all of the same methods. For consistency with the interface-based nature of COM, this paper uses the interface as shown in the following code sample.

	Copy Code
IDeviceEmulatorManager _emulatorManager; _emulatorManager = new DeviceEmulatorManagerClass();

Once you have a reference to the Device Emulator Manager, you can start working with the first level of the hierarchy, the categories. Two points that you should be aware of when iterating through the list of categories are the multifaceted nature of the IDeviceEmulatorManagerinterface and the way the IDeviceEmulatorManagerinterface indicates the end of the list. First, the multifaceted nature of the IDeviceEmulatorManagerinterface. The IDeviceEmulatorManagerinterface plays three distinct roles: the Device Emulator Manager, the enumerator over the list of categories, and the current category in the list. When working with the individual interface methods you'll want to be certain that you understand to which of these three identities the specific method applies. The other point is the way that the IDeviceEmulatorManager.MoveNextmethod indicates that there are no more categories left, which is to throw a COMException. The following sample demonstrates aspects of both points.

Copy Code

void ListDEMCategoryMembers(IDeviceEmulatorManager emulatorManager) { const int END_OF_DATA = -2147024637; string categoryName; emulatorManager.Reset(); // Ensure that at beginning of categories try { while (true) { categoryName = emulatorManager.get_Name(); Console.WriteLine(categoryName); ListDEMSdkMembers(emulatorManager); // SDKs for this category _mulatorManager.MoveNext(); } } catch (COMException ex) { if (ex.ErrorCode != END_OF_DATA) throw ex; } }

As mentioned previously, the IDeviceEmulatorManagerinterface represents multiple roles. You can see in the preceding sample code that the IDeviceEmulatorManagerreference, emulatorManager, exposes the methods Reset, MoveNext, and get_Name. The first two methods allow you to work with the category enumerator. The Resetmethod positions the emulatorManagerreference at the beginning of the category list; the MoveNextmethod advances the emulatorManagerreference to the next category in the list. The get_Namemethod returns the name of category at the emulatorManager's current position in the category list thereby representing the current category. This code sample does not show any of the IDeviceEmulatorManagermethods that represent the Device Emulator Manager role, however upcoming code samples will. Similar multi-role behavior is repeated in the IEnumManagerSDKsinterface discussed in the next section.

With regard to the way that the MoveNextmethod indicates that no categories remain, notice that the loop iterating over the category list uses a truevalue as the exit condition for the whileloop. Using a truevalue within the loop condition often indicates an endless loop, but not in this case. As you can see, the whileloop is contained within the tryportion of a try/ catchblock. The way this code is written, the only way to exit the whileloop is for one of the Device Emulator Manager API methods to throw an exception. In fact, that is how the MoveNextmethod exits the loop.

Being written as a COM component, the Device Emulator Manager API uses numeric codes known as HRESULTs to indicate the success or failure of each method call; in most cases a zero-value HRESULT indicates success. In addition to success or failure, HRESULTs can also indicate a state change such as reaching the end of a list. In the case of the MoveNextmethod, this is exactly what happens.

When the call to the MoveNextmethod causes the emulatorManagerto advance beyond the end of the category list, the MoveNextmethod returns a specific HRESULT value (-2147024637) to the COM layer to indicate that no further data exists in the category list. The .NET Interoperability layer interprets the non-zero HRESULT value as an error and translates the HRESULT into a COMException. With this being the case, the .NET Interoperability layer will always raise a COMExceptionwhen reaching the end of the category list; the preceding code catches the exception outside of the whileloop and checks the COMExceptionHRESULT. When the HRESULT is the expected end-of-data value the program continues normally, otherwise the COMExceptionis re-thrown. The Device Emulator Manager SDK enumerator and Device Emulator enumerator indicate the end-of-data in this same way.

Working with the SDK list is very similar to working with the category list. Each category has its own list of SDKs; therefore, each category has a separate SDK enumerator. The Device Emulator Manager API exposes each SDK enumerator through the IEnumManagerSDKsinterface. You access the SDK enumerator for a specific category through the IDeviceEmulatorManager.EnumerateSDKsmethod for that category. Similar to the IDeviceEmulatorManagerinterface, the IEnumManagerSDKsinterface plays multiple roles acting as both the SDK list enumerator and the current SDK in the list.

The following code sample demonstrates how to iterate over the list of SDKs for a particular category. The method in this sample code is called once for each iteration of the loop within the ListDEMCategoryMembersmethod shown in the previous sample code.

Copy Code

void ListDEMSdkMembers(IDeviceEmulatorManager emulatorManager) { const int END_OF_DATA = -2147024637; string sdkName; IEnumManagerSDKs sdkEnum = emulatorManager.EnumerateSDKs(); sdkEnum.Reset(); try { while (true) { sdkName = sdkEnum.get_Name(); Console.WriteLine("\t"+sdkName); ListDEMEmulators(sdkEnum); sdkEnum.MoveNext(); } } catch (COMException ex) { if (ex.ErrorCode != END_OF_DATA && ex.ErrorCode != DeviceEmulatorManagerErrorCodes.E_ENUMSDK_NOT_LOADED) throw ex; } }

Just as was the case in the earlier sample code for iterating over the category list, the Device Emulator Manager API indicates the end of the SDK list through a COMExceptionwith an HRESULT value of -2147024637. In addition to the catchblock handling the end of the SDK list HRESULT, this code sample includes a check for an additional HRESULT. This additional HRESULT check handles the case of a category that contains no SDKs.

The Device Emulator Manager API is implemented such that the Resetmethod positions the enumerator at the first item in the list and you cannot call the MoveNextmethod until you no longer need the first list item, because the call to the MoveNextmethod immediately advances the enumerator to the next member in the list. What this means is that there is no method call you can make that will indicate that the list is empty (in other words a category with no SDKs). The only way to know that the SDK list is empty is to call one of the methods that represent the current list item, such as the get_Namemethod. When you call the get_Namemethod when no SDK is available, the method returns an HRESULT value that corresponds to the constant DeviceEmulatorManagerErrorCodes.E_ENUMSDK_NOT_LOADED, which the .NET Interoperability layer translates into a COMExceptioncontaining this same HRESULT. Like when reaching the end of the list, the program catches the COMExceptionand checks that the HRESULT has the expected value, if not, the COMExceptionis re-thrown.

The IEnumVMIDsinterface represents the list enumerator for the Device Emulators within an SDK. Working with the emulator list is very much like working with the SDK list. The following code sample demonstrates how to iterate over the list of Device Emulators. The method shown in this code sample, ListDEMEmulators, is called once for each iteration of the loop within the ListDEMSdkMembersmethod shown in the previous sample code.

Copy Code

void ListDEMEmulators(IEnumManagerSDKs sdkEnum) { string emulatorName; IDeviceEmulatorManagerVMID theEmulator; IEnumVMIDs vmidEnum = sdkEnum.EnumerateVMIDs(); vmidEnum.Reset(); try { while (true) { theEmulator = vmidEnum.GetVMID(); emulatorName = theEmulator.get_Name(); Console.WriteLine(emulatorName); vmidEnum.MoveNext(); } } catch (COMException ex) { if (ex.ErrorCode != END_OF_DATA && ex.ErrorCode != DeviceEmulatorManagerErrorCodes.E_ENUMVMID_INVALID_VMID && ex.ErrorCode != DeviceEmulatorManagerErrorCodes.E_ENUMVMID_NOT_LOADED) throw ex; } }

One minor difference in looping through the Device Emulator list as compared to the SDK list is the error codes you must handle in the case of an empty list. When working with the SDK list, the enumerator always returns DeviceEmulatorManagerErrorCodes.E_ENUMSDK_NOT_LOADED, whereas the Device Emulator enumerator indicates an empty list by returning DeviceEmulatorManagerErrorCodes.E_ENUMVMID_INVALID_VMIDin some cases and DeviceEmulatorManagerErrorCodes.E_ENUMVMID_NOT_LOADEDin others. For this reason, the catchblock must check for both of these HRESULTs in addition to the end-of-data HRESULT.

Unlike the IDeviceEmulatorManagerand IEnumManagerSDKsinterfaces, which each represent both their list enumerator and the current item in their list, the IEnumVMIDsinterface represents only the Device Emulator list enumerator. To access an individual Device Emulator enumerator, you use the IDeviceEmulatorManagerVMIDinterface. Through this interface you can access not only the emulator name but gain full control of the Device Emulator including all of the capabilities shown earlier in the Controlling the Device Emulatorsection of this paper.

The Device Emulator Manager API does not provide any facility for directly accessing a Device Emulator; you loop through the layers of the hierarchy to find a particular Device Emulator. For this reason, one of the most important facilities to have for the Device Emulator Manager API is a Findmethod. To create a Findmethod you combine the category, SDK, and Device Emulator iteration code from the previous three code samples adding a condition in the Device Emulator iteration code to locate the Device Emulator of interest by matching its name.

A complete implementation of a Device Emulator Manager API Findmethod is available at Windows Mobile Device Emulator Programmability - Just Needs a Find-Emulator Function .

The information in the Device Emulator Manager hierarchy can change for a variety reasons: a user installs or uninstalls a SDK, a user creates or deletes an emulator configuration, an application creates or deletes an emulator configuration, and so on. The Device Emulator Manager API provides notification of such changes through a Win32® synchronization event object.

You should monitor for changes in the Device Emulator Manager hierarchy to be aware of any new items but more importantly to avoid any unexpected issues that may occur as a result of the removal of one of the Device Emulator Manager objects.

To monitor for changes in the Device Emulator Manager hierarchy, you must create a named Win32 synchronization event object and pass the name of event object to the IDeviceEmulatorManager.RegisterRefreshEventmethod. You must then launch a thread that blocks on the event. If any changes in Device Emulator Manager hierarchy occur, the Device Emulator Manager will signal the synchronization event. The following code sample demonstrates how to monitor for a change in the Device Emulator Manager hierarchy.

Copy Code

const string refreshEventName = "MyApplication.Refresh"; EventWaitHandle _refreshEvent; Thread _refreshEventThread; volatile bool _shutDownRequested = false; private void SetupEventListener(IDeviceEmulatorManager emulatorMgr) { // Create the event _refreshEvent = new EventWaitHandle(false, EventResetMode.AutoReset, refreshEventName); // Start thread to monitor for changes _shutDownRequested = false; _refreshEventThread = new Thread(RefreshEventMonitor); _refreshEventThread.Start(); // Notify Device Emulator Manager API of event name emulatorMgr.RegisterRefreshEvent(refreshEventName); } void RefreshEventMonitor() { while (!_shutDownRequested) { bool signaled = _refreshEvent.WaitOne(); if (signaled && !_shutDownRequested) // hierarchy has changed } } private void ShutdownEventListener(IDeviceEmulatorManager emulatorMgr) { // Tell Device Emulator Manager that we're done listening emulatorMgr.UnRegisterRefreshEvent(); // Bring down thread monitoring the refresh event _shutDownRequested = true; _refreshEvent.Set(); _refreshEventThread.Join(); // Release event _refreshEvent.Close(); }

The code that actually monitors for changes to the Device Emulator Manager hierarchy is in the RefreshEventMonitormethod. This method runs on a thread separate from the main application. Anytime the synchronization event signals, RefreshEventMonitorperforms the appropriate action to deal with the Device Emulator Manager hierarchy changes. Each instance of the DeviceEmulatorManagerClassand the related Device Emulator Manager classes cache the list of objects in the Device Emulator Manager hierarchy; therefore, most applications should call the IDeviceEmulatorManager.Refreshmethod to update this cached list. Other actions may include re-reading the contents of the Device Emulator Manager hierarchy, updating any cached references your program holds to one of the Device Emulator Manager objects, and so on. When these actions are complete, the RefreshEventMonitormethod then goes back to monitoring for changes.

Note:

Because the function monitoring the refresh synchronization event runs on a thread separate from the main application thread, use caution if you call the IDeviceEmulatorManager.Refreshmethod from this thread, as the update to the Device Emulator Manager hierarchy may cause problems with code using the hierarchy on the main application thread. For information on synchronizing activities between threads, C# developers should see Thread Synchronization from C# Programming Guide; Visual Basic .NET developers should see Thread Synchronization from Visual Basic Language concepts.

The RefreshEventMonitorcontinues monitoring for changes until the class-level field, _shutDownRequested, is set to true. Notice that the _shutDownRequestedfield is declared with the volatilekeyword; this is necessary because the thread that modifies the field value is separate from the thread that reads the field value. Without the volatilemodifier, the thread monitoring for refresh events may cache the value of the _shutDownRequestedfield, possibly causing the thread to miss the main application thread's change to the field value.

The code to start the process of monitoring for changes to the Device Emulator Manager hierarchy is contained in the SetupEventListenermethod. This method starts by creating a named Win32 synchronization AutoResetevent object. As an AutoResetsynchronization event, the synchronization event guarantees that the RefreshEventMonitormethod will carry out exactly one iteration of the whileloop; the next time the RefreshEventFunctioncalls the _refreshEvent.WaitOnemethod, the thread is guaranteed to block again. The event name can be any value you like but should be a value that is not likely to collide with event names that other programs may use.

Note:
For information on working with threads using AutoReset and ManualReset events, see EventWaitHandle, AutoResetEvent, and ManualResetEvent and Managed Threading in the MSDN® library.

Once the program creates the synchronization event, the program then goes on to start the thread on which the RefreshEventMonitormethod runs. Finally, the program informs the Device Emulator Manager API of the name of the event to signal if the Device Emulator Manager hierarchy changes.

When the program no longer needs to monitor the Device Emulator Manager API for changes, most likely just before the application exits, the ShutdownEventListenermethod takes care of the details. The ShutdownEventListenermethod first calls the IDeviceEmulatorManager.UnRegisterRefreshEventmethod to inform the Device Emulator Manager API that the program no longer needs to be notified of changes. The method then shuts down the RefreshEventMontorthread and releases the synchronization event.

One of the things that can sometimes be confusing is that the Device Emulator Manager API interfaces do not always differentiate between a list of objects and the individual objects in the list. For example, the IDeviceEmulatorManagerinterface represents the Device Emulator Manager, the list of categories, and an individual category. The wrapper avoids this confusion by providing individual classes for each object. Table 2 shows the list of classes and their descriptions.

Table 2. Classes for the Device Emulator Manager Objects

With the exception of the DeviceEmulatorclass, the classes in Table 2 are relatively simple. In general they expose a Nameproperty and a collection representing the next level of the hierarchy.

As mentioned earlier in this paper, the most significant issue in working with the Device Emulator Manager API is that the hierarchy of lists is exposed in a COM-style representation rather than as .NET collections. The logical thing to do is provide .NET collections for each level of the lists in the hierarchy. Table 3 shows the collection classes.

Table 3. Collection Classes for the Device Emulator Manager Lists

With the collection classes defined, each of the wrapper classes in the Device Emulator Manager hierarchy can expose the list of objects in the next level of the hierarchy as a simple collection property. Table 4 shows the collection properties for each of the wrapper classes.

Table 4. Collection Properties

Using the collection properties, iterating through the entire hierarchy becomes very simple. The following code sample writes out the Device Emulator Manager hierarchy.

	Copy Code
DeviceEmulatorManagerEx demManagerEx = new DeviceEmulatorManagerEx(); foreach (DeviceEmulatorCategory category in demManagerEx.Categories) { Console.WriteLine(category.Name); foreach (DeviceEmulatorSdk sdk in category.Sdks) { Console.WriteLine("\t" + sdk.Name); foreach (DeviceEmulator deviceEmulator in sdk.DeviceEmulators) { Console.WriteLine("\t\t" + deviceEmulator.Name); } } }

The 13 lines in this sample code do the same thing as the 78 lines in the second, third, forth, and fifth code samples from this paper combined.

One of the most common reasons that you will likely iterate over the Device Emulator Manager hierarchy is to locate an item within the hierarchy. Although the wrapper classes simplify the process of iterating over the Device Emulator Manager hierarchy, the better solution is to allow you to directly access the specific item of interest.

Note:
Each of the samples in this section and the following section makes the assumption that there is an existing DeviceEmulatorManagerExvariable named demManagerEx.

To make locating a Device Emulator easier, the DeviceEmulatorManagerExclass provides a FindEmulatormethod. The FindEmulatormethod allows you to locate a Device Emulator using either its name of VMID. The following sample code demonstrates using the FindEmulatormethod to locate the Windows Mobile 6 Professional Emulator; the sample code then demonstrates using the returned DeviceEmulatorreference to start the emulator if it is not running.

	Copy Code
DeviceEmulator wm6Pro = demManagerEx.FindEmulator("Windows Mobile 6 Professional Emulator "); if (wm6Pro != null) { if (wm6Pro.State == EMULATOR_STATE.EMU_NOT_RUNNING) wm6Pro.Connect(); }

To simplify locating items at any layer in the hierarchy, each of the collections provides a string-based indexer. To use the indexer simply pass the string name of the item of interest.

Note:
The collections all inherit from the ReadOnlyCollection<T>class, which provides an integer-based indexer that allows you to access the members of the collection by numeric position such as 0, 1, and so on.

The following sample code demonstrates using an indexer to locate the DataStore category.

	Copy Code
DeviceEmulatorCategory dataStore = demManager.Categories["DataStore"];

The following sample code demonstrates using indexers to locate the Windows Mobile 6 Professional SDK within the DataStore category.

	Copy Code
DeviceEmulatorSdk wm6ProSdk = demManager.Categories["DataStore"].Sdks["Windows Mobile 6 Professional SDK"];

The following sample code demonstrates using indexers to locate the Windows Mobile 6 Professional Emulator within the Windows Mobile 6 Professional SDK within the DataStore category.

	Copy Code
DeviceEmulator wm6Pro = demManager.Categories["DataStore"].Sdks["Windows Mobile 6 Professional SDK"].DeviceEmulators["Windows Mobile 6 Professional Emulator"];

Note:
In the case of locating a specific emulator, one would generally use the DeviceEmulatorManagerEx.FindEmulatormethod rather than a sequence of indexers.

The DeviceEmulatorManagerExclass makes Device Emulator Manager hierarchy change notifications available as a standard .NET event through the RefreshRequiredevent. The event type is MethodInvokerand therefore requires that your event handler accept no parameters and has no return value. The threading and synchronization event handling details that the Device Emulator Manager API requires for change notifications is encapsulated in the DeviceEmulatorManagerExclass.

The DeviceEmulatorManagerExclass monitors for changes to the Device Emulator Manager hierarchy on a thread separate from the main application thread and therefore calls your event handler on this same thread. As a result, you should use caution when interacting with the user interface; always use Control.Invokeor Control.BeginInvoke.

Note:
You should always call the Disposemethod on the DeviceEmulatorManagerExclass. The Disposemethod handles the details of terminating the thread that monitors for Device Emulator Manager hierarchy changes. If you forget to call the Disposemethod, you may find that your application appears to stop responding during the application exit process.

Like the IDeviceEmulatorManagerinterface, the DeviceEmulatorManagerExclass includes a Refreshmethod to update the internal cache of Device Emulator Manager objects and hierarchies. Because the DeviceEmulatorManagerEx.RefreshRequiredevent signals your event handler on a thread separate from the main application thread, calling the Refreshmethod from your RefreshRequiredevent handler requires the same caution as described in the earlier IDeviceEmulatorManager.Refreshdiscussion.

Automating the Device Emulator Manager Using the IDeviceEmulatorManager Interface

Windows Mobile Device Emulator Programmability - Just Needs a Find-Emulator Function

Thread Synchronization from C# Programming Guide

Thread Synchronization from Visual Basic Language concepts

EventWaitHandle, AutoResetEvent, and ManualResetEvent

Managed Threading

Device Emulator Manager Automation Interfaces

Device Emulator Reference

Jim Wilson is president of JW Hedgehog, Inc. (http://www.jwhh.com) a New Hampshire–based consulting firm specializing in solutions, content creation, and mentoring for the Windows Mobile platform. Jim has worked extensively with the .NET Framework and .NET Compact Framework since the original beta release of each; he has over 20 years experience in the software industry including more than 14 years experience with relational database programming including SQL Server and SQL Server Compact Edition. Jim writes frequently for MSDN and has developed mobility curriculums for two of the industry’s leading technology training organizations, DevelopMentor and PluralSight. Jim speaks regularly at Tech Ed, the Professional Developer's Conference (PDC), VSLive, and the Mobility & Embedded DevCon. You will find Jim online at http://pluralsight.com/blogs/jimw.