Creating and Deploying SideShow Applications


You create and deploy SideShow gadget applications on a Windows Vista personal computer. There is no means to place any active content on the target device over and above the Simple Content Format descriptions of the pages that are to be displayed on it. Simple Content Format descriptions are expressed in Extensible Markup Language (XML). We will consider the content of these descriptions in detail in the section titled "SideShow Content and Endpoints" later in this chapter.

A SideShow gadget application can be written in managed or unmanaged code; for the sake of consistency, you will create your SideShow application using managed code and C#. You can create a SideShow gadget application on the personal computer to deliver content to a SideShow device, or you can modify a larger application to send relevant content to a SideShow device.

For an example of the former, consider an application that downloads daily weather and tidal updates into a SideShow device for use by river pilots. For an example of the latter, note that the Microsoft Office Outlook 2007 program provides a SideShow gadget application that you can use to send calendar and e-mail notifications to a connected device. If you are creating a personal computer application, it is worth considering how you could add value to it by including some SideShow features-for example, an image editing program could provide a facility that could also download photo album content into a SideShow device.

Creating SideShow Applications

We are going to create our SideShow application using the C# language and Microsoft Visual Studio 2005. To create SideShow applications, you must have downloaded the Microsoft-Windows Software Development Kit for Windows Vista. You can find this on MSDN. It provides a set of libraries and additional components that integrate with your Visual Studio 2005 installation. Next, you need the libraries that let you create the SideShow classes on your personal computer. You can find these in the Windows SideShow .NET Framework Components 1.0, which is also available for download from MSDN.

Hardware Requirements for SideShow Development

If you have a SideShow device, you can just connect it, and it will become available as a target for SideShow applications configurable in the Control Panel dialog box, which was shown in Figure 8-1. However, you may wish to develop for the platform without having a physical device. Fortunately, an emulator is supplied for this purpose. The emulator runs as a program on your development computer, but it behaves exactly as a real physical device. It communicates to a server that runs on the host machine. The server provides the communications channel between the device and the gadget applications. When the emulator starts, it makes contact with the server process. Before you can use the server, you must register it by issuing this command:

 WindowsSideShowVirtualDevice.exe /regserver 

You need to perform the registration only once on a particular machine. This program can be found in the SDK installation directory, for example:

 C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin 

An administrator must run the regserver command on the target system. You can do this by starting a command window using "Run as administrator." Once you have registered the server, you should find that you can create an instance of a SideShow device on your personal computer by running this program: VirtualSideShow.exe.

You can find the program in the same directory as the server that you started earlier. This command will start an instance of the Virtual SideShow device on your machine. This will register itself with the server and should become visible in the Windows SideShow Control Panel. If you connect gadget applications to the device, these applications will appear on the device menu. You can create multiple SideShow devices if you wish; to do this, follow the VirtualSideShow command with an ID number for the device you are starting.

 VirtualSideShow.exe 1 

This command would start a device with an ID of 1. When you finish using a simulator, you can close it by right-clicking anywhere on the simulator display and selecting Close from the menu that appears. By default, an emulator will retain its state when it closes so that the next time it runs, it will have the same content and configuration as before. If you wish to remove a simulator completely, you can uninstall the SideShow device it is simulating by using the SideShow Control Panel.

Our Sample Application

The sample application we will create is a simple memo system for use by security guards who carry our ultimate flashlight. Our system's customer has asked us to provide a means by which pictures of areas that need special attention, along with text instructions, can be loaded into the flashlight at the start of each shift. The application will be registered on the personal computer as a "Flashlight Memo."

On the personal computer, you need to create a program that will allow users to enter pictures and text and create content to send to a SideShow device when the program next connects to the host computer. The device will then allow the user to browse the content after the user disconnects it from the system.

The following sections will show you how to create a SideShow gadget application, install it on a host system, and then design the pages to be sent to the SideShow device.

Creating an Application Project

A gadget application is a Windows program that includes the SideShow libraries. The program is registered on the host system, and when a SideShow device is connected, the application is started so that it can interact with the device. You can start by creating an application project in Visual Studio 2005. Next, you must add the SideShow library as a reference. Finally, you add a couple of using statements to allow us to refer to the SideShow classes directly.

 using Microsoft.SideShow; using Microsoft.SideShow.SimpleContentFormat; 

The first of these allows us to use the SideShow classes to talk to the device. We will use the second when creating Simple Content Format classes, in the section titled "SideShow Content and Endpoints" later in this chapter.

Registering a Gadget Application

For a gadget application to appear on the SideShow Control Panel of a machine, the application must first be registered on it. The list of gadget applications installed on a particular computer is held in registry keys on that computer. There are two key locations, one for gadget applications available to all users, held in the HKEY_LOCAL_MACHINE registry key, and the other that identifies those available to a particular user, held in the HKEY_CURRENT_USER registry key.

Figure 8-5 shows a registry entry that we could use for our application. It contains configuration details for the gadget application and also selects some behavior options for the program in the device itself. The registry key itself is the globally unique identifier (GUID) value for that particular gadget.

image from book
Figure 8-5: Registry entry for our SideShow Flashlight Memo application.

You can obtain a unique GUID for any gadget application that you write by using the program uuidgen, which is provided in the SDK directory. The following code is an example of calling it to create the key for the Flashlight Memo gadget:

 C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin>uuidgen 

You can then cut the response out of the command prompt window and use it to create a GUID instance in the program.

 private static readonly Guid gadgetId = new Guid("{}"); 

Each GUID value is designed to be unique in the world, which will prevent the gadget from being confused with any other.

Note 

If you want to create different kinds of GUIDs, you can use the tool GuidGen, which is also in the SDK directory. This provides a Windows Forms application that can produce a number of different GUID formats.

Now that we have an identifier for our gadget, we can create a registry entry for it. The registry entries for the gadget application can be created by hand, but the GadetRegistration class in the SideShow libraries provides a static method called Register that will do this for us. We will call it once during the installation process of the gadget application. The method is shown in Listing 8-1.

Listing 8-1: Creating a registry entry for a gadget

image from book
 GadgetRegistration.Register(   true,                                                // register for all users   gadgetId,                                            // gadget GUID   ScfSideShowGadget.ScfEndpointId,                     // content endpoint - want SCF   "Flashlight Memo",                                   // friendly name   @"c:\Program Files\FlashlightMemo\FlashlightMemo.exe device",                                                        // program parameter   @"c:\Program Files\FlashlightMemo\flashlight.ico",   // icon location   false,                                               // true if online only   GadgetCachePolicies.KeepNewest,                      // cache policy   null);                                               // property page GUID 
image from book

The first parameter, "register for all users," determines whether the gadget application is registered for all users. If this parameter is set to true, the entry is made in the HKEY_LOCAL_MACHINE part of the registry, and the application will be available to all users of the machine. If this parameter is set to false, the entry is made in the HKEY_CURRENT_USER area, and the application will work only for the currently authenticated user.

The second parameter, "gadget GUID," is the GUID of this gadget application. The operating system uses the GUID to identify the gadget application, giving the key created in the registry this name.

The third parameter, "content endpoint," identifies the endpoints that a device must be able to support if our application is to be able to talk to it. At the moment, two endpoints are available: SCF and the ICalendar (ICAL) endpoint. These identify the means by which the gadget application will speak to the SideShow device. If the device does not support the required endpoints, the operating system will not allow the user to connect our application to that device.

The fourth parameter, "friendly name," sets the name that the user will see in the operating system gadget Control Panel on the host computer. This is also the name of the gadget displayed on the SideShow device itself. The gadget is going to be called Flashlight Memo, and so that is the text we specify.

The fifth parameter identifies the gadget program that will provide content to the SideShow devices when they connect to the computer. The name of the program file can be followed by a parameter which can be used in the application. The next section, "Running the SideShow Gadget Application," shows how this is done.

The sixth parameter, "icon location," tells the host computer the location of the file containing the icon for this gadget. The icon appears in the Control Panel and is also downloaded into the gadget itself. The Control Panel uses a 32 × 32 pixel icon and the SideShow device itself uses a 48 × 48 pixel version. If you don't provide an icon location, or the icon is not found, a default icon is used instead.

The seventh parameter, "true if online only," tells the system whether the SideShow device should display the content when it is not connected to the host. If this value is set to true, it means that the content will be visible only when the device is connected. The Flashlight Memo items must be visible when the device is disconnected, so this has been set to false.

The eighth parameter, "cache policy," selects the way that the SideShow device is to manage message items that it receives. This has been set to KeepNewest, because the newer information is the most important. You can also select KeepOldest, which means that older items will be kept in preference to newer ones. You may combine these with two other settings: KeepFrequentlyAccessed means that the most frequently accessed items are given priority, and KeepRecentlyAccessed selects the most recently accessed content items.

The final parameter, "property page GUID," identifies a property page that you can use to modify further settings for this gadget. This can be left null if you don't wish to set properties in this manner.

Once you register the gadget, the gadget will appear in the SideShow Control Panel as available for deployment. Figure 8-6 shows our new gadget application in the Windows SideShow Control Panel. The Flashlight Memo gadget has been configured to appear on the Momento SideShow device.

image from book
Figure 8-6: SideShow Control Panel entry for the Flashlight Memo application.

Figure 8-7 shows how our Flashlight Memo gadget appears on a target device. At the moment, no content is being sent, so no information is available. You now need to create the application that will run when the SideShow device connects, and deliver some content to it.

image from book
Figure 8-7: Flashlight Memo on a SideShow device.

Running the SideShow Gadget Application

When you connect a SideShow device to its host personal computer, the SideShow infrastructure enumerates all the SideShow gadget applications available on it (that is, those gadgets installed on the machine host and selected via the Control Panel). The host computer then starts the gadget application for each gadget, using the program command found in the registry for that gadget. In our case, the command is:

 c:\Program Files\FlashlightMemo\FlashlightMemo.exe device 

Note 

You should have placed this program in the correct location prior to creating the registry entry for the application. Failure to provide a correct program path will not cause any problems, but of course, no updates will take place.

The application will then run and update the content in the device. You will note the parameter "device" after the application name, which allows us to use the same application to deliver content to the device as is used to prepare the content. The Main method in the application can then detect the parameter and behave appropriately.

 static void Main(string [] args) {    if (args.Length > 0)    {       if (args[0] == "device")       {          doUpdateDevice();       }    }    else    {       doNormalBehaviour();    } } 

If the program finds the argument device, it calls the method doUpdateDevice to update the device display; otherwise, the program calls the doNormalBehaviour method.

Note 

Note also that the gadget application is started even if an existing copy of the program is already running. It is up to you to detect this and stop the second copy.

So at this point, we know how to install our gadget application and run it when the device connects. Next, we will consider how to send content to the SideShow device.




Embedded Programming with the Microsoft .Net Micro Framework
Embedded Programming with the Microsoft .NET Micro Framework
ISBN: 0735623651
EAN: 2147483647
Year: 2007
Pages: 118

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net