About Windows SideShow Gadgets
Before writing a gadget for Windows SideShow, developers should understand the following concepts related to the Windows SideShow technology.
Each gadget is uniquely identified with a GUID, which is known as the gadget ID or application ID. This application ID is what the Windows SideShow platform uses to identify each gadget. The gadget provides its application ID to the platform as part of its metadata (described in Installing a Gadget) as well as when the gadget initially registers itself with the platform. Note that this differs from Windows Sidebar: Sidebar gadgets do not need to generate their own application IDs; they are generated automatically by Sidebar itself. To generate a new random GUID for a Windows SideShow gadget, run guidgen.exe from the bin directory in the Windows Vista Platform SDK.
In the Windows SideShow platform, an endpoint represents a contract between a device and a gadget regarding the format of the data that is sent to the device and the events that are sent from the device back to the gadget. Gadgets and devices are only able to communicate with each other when they have an endpoint in common. As part of the gadget metadata (discussed in Installing a Gadget), gadgets must indicate to Windows SideShow which endpoints they support by specifying endpoint IDs. This information is then used by Windows SideShow in Control Panel to enable gadgets and allow data to flow to the device. In many ways, an endpoint is a similar concept to the notion of a port in TCP/IP. Microsoft currently defines two endpoint IDs for Windows SideShow:
The endpoint mechanism is meant to be fully extensible to allow device manufacturers to develop custom endpoints for scenarios where a custom data format is required or the Microsoft-defined endpoints are not sufficient to provide the desired user experience. Gadgets can use any custom endpoint supported by a device.
In some cases, gadgets can support multiple endpoints. Endpoints are specified in priority order, and typically the highest priority endpoints provide the richest experience for that gadget. Because not all devices can support the richest experience, the gadget should also support a scaled-down or alternate experience for devices that use one of the common endpoints, such as the Simple Content Format (SCF) endpoint. For example, the Microsoft Office Outlook Calendar gadget supports both iCalendar and SCF endpoints, which allows devices that do not support the iCalendar endpoint to still receive upcoming appointment data. For more information about endpoints, see Platform-Defined Endpoints.
Gadgets display content. In the Windows SideShow COM API, the ISideShowContent interface represents a content item and the ISideShowContentManager interface enables you to manage the flow of content between the gadget and a device. In the managed API, an instance of the Content represents a content item and the SideShowGadget includes methods for managing content flow. Both APIs provide a ContentMissing event that can notify a gadget when the device needs new content. See the following section for more information about events.
A content ID uniquely identifies a specific piece of content for an endpoint. Technically, a content ID is an unsigned 32-bit integer that is unique only for a given application ID and endpoint ID pair. Interpretation of a particular content ID depends on the endpoint for which it is being used. Content ID 0 retains a special meaning in Windows SideShow for all endpoints: it is reserved for a high-level summary, called glance content, which is always a UTF-8 encoded text string. Note that not all endpoints utilize content ID 0 (for example, iCalendar does not).
All other content IDs are available for a gadget, and contain content in a format dictated by the endpoint. Gadgets are able to add, update, and remove a content segment by referencing its content ID.
Most gadgets will primarily push data down to the devices. However, some gadgets might require information about user interaction with the device. For example, the Windows Media Player gadget listens to events from the device to control media playback on the computer.
There are six events available to gadgets that use the Windows SideShow managed API:
There are four events available to gadgets that use the Windows SideShow COM API:
The DeviceAdded, DeviceRemoved, and AllDevicesRemoved events tell a gadget when there is a change in the set of devices to which they are providing content. This may be due to physical device connection and disconnection, or enabling and disabling gadgets in Windows SideShow in Control Panel.
The GadgetEnter and GadgetExit events notify the gadget when the user views the first page of the gadget or returns to the main page on the device.
The ContentMissing event is sent by a device when, due to user interaction, it needs to display a piece of content which it does not have. The gadget can use this event to provide the appropriate content, if it is available.
The ApplicationEvent is a general-purpose event C++ developers can use to send endpoint-specific data from a device to the gadget on the PC. The endpoint defines the set of events available to a gadget. There are two global application events defined for all endpoints: SIDESHOW_EVENTID_APPLICATION_ENTER and SIDESHOW_EVENTID_APPLICATION_EXIT. These two events are fired when a user begins to view content from a gadget or stops viewing content from a gadget. For more information about SIDESHOW_EVENTID_APPLICATION_ENTER and SIDESHOW_EVENTID_APPLICATION_EXIT, see ApplicationEvent Method.
In addition to content, Windows SideShow allows gadgets to send notifications to connected devices. Notifications consist of a title, message, and icon. Gadgets can specify an expiration time for a notification, which indicates the time after which the notification should no longer be displayed. For example, an instant messaging gadget may use notifications to alert the user when buddies sign in, or an e-mail gadget may send a notification when new e-mail is received.
The Gadget Manager is a utility that performs a number of tasks, including:
Providing system-tray notifications on new gadget and device installations.
Automatically launching gadgets when they are enabled for connected devices.
Cleanup on gadget removal.
Using the Gadget Manager is optional, though highly recommended, because it helps to provide a consistent user experience on Windows. The Gadget Manager is well-suited for gadgets that have no Windows UI and that run in the background. If you install your gadget as part of a larger software application package, you should consider using the Gadget Manager to provide a clear notification to the user about the new gadget. For more information about using the Gadget Manager, see Installing a Gadget
To be registered with Windows SideShow, the gadget must provide a minimum set of metadata in the registry. This metadata includes the application ID, the name of the gadget, the gadget's icon, the endpoint IDs it supports, information on how the Gadget Manager can invoke it, and additional optional values. These are discussed in more detail in Installing a Gadget.
Gadget metadata can be written to either of the following locations:
Gadgets written to HKLM will be available for all users on the computer. Gadgets written to HKCU will be available only for the current user.
The Windows SideShow Managed API provides the GadgetRegistration to make registering and unregistering a gadget easier. This class can be especially useful when registering and unregistering your gadget during development, or when creating a custom installer.
Online and Offline Gadgets
Certain types of gadgets, such as those that remotely control the computer, require the computer to be on for full functionality. Windows SideShow can (through the metadata described above) allow a gadget to indicate that it is an online gadget that requires the computer to be on for operation. Gadgets are offline by default, which means that their content is available on the device when the computer is off (assuming that the device is capable of this). For an online gadget, the device will not allow the user to view content when the computer is turned off or disconnected.
Device Cache Algorithms
Some devices maintain a content cache, which helps to avoid requesting the same content multiple times. Such devices can choose from a variety of rules, or device cache algorithms, for how to remove content from the cache when there is not much memory available. For example, a device could choose to remove the most recent content first or to remove the oldest content first.
Devices can use a hint from your gadget when deciding how to flush cache memory. On Windows Vista, SideShow was designed to read a registry value to determine which device cache algorithm to suggest for devices. However, due to a known issue, the SideShow platform does not use this registry value. Instead, the device cache algorithm setting corresponds to whether you have specified your gadget to be an online gadget or not.
When you specify your gadget to be an online gadget, Windows SideShow reports to the device that the device should give priority to the oldest content in the cache. When you specify your gadget to be offline, Windows SideShow reports to the device that the device should give priority to the newest content in the cache.
This behavior is usually not an issue. Most gadgets do not specify the online-only behavior and most gadgets give priority to the newest content, so the default settings provide the most common behavior. For online gadgets, the cache algorithm setting does not prevent any particular content from reaching the device, because the gadget only works when the device is connected to Windows. Therefore, the gadget can always provide whatever content the user requests.
This issue is fixed in Windows 7.
A device that maintains a cache of data can, under certain circumstances, experience so much memory pressure that it must flush some of its cached data. This may occur, for example, when a user has enabled a significant number of gadgets that all require a significant amount of memory to hold their content. As part of the gadget metadata, the gadget can specify its ideal algorithm for managing its device-side cache. Typically, gadgets do not encounter such situations; however, in case they do, you may want to include fine-grained control over how the cache is purged.
The current defined values for the CacheAlgorithm metadata entry are:
0: Default, give priority to newest content in the cache.
1: Keep Oldest, give priority to the oldest content in the cache.
2: Keep Frequently Accessed, give priority to the most frequently accessed content. Can be combined with Keep Oldest to give priority to oldest item when multiple items have the same access frequency.
4: Keep Recently Accessed, give priority to the content most recently accessed (by the user). Can be combined with the Keep Oldest to give priority to the oldest item when multiple items have the same last access time.
For more information about CacheAlgorithm and other metadata, see "Gadget Metadata" in Installing a Gadget
Managed API Content Cache
The managed API provides a cache that stores content that your gadget has pushed to devices. When a device requests a particular content item, the managed API first tries to provide the content from the content cache. If the requested content does not exist in the cache, the managed API raises the ContentMissing event in your gadget. This event gives your gadget an opportunity to provide the missing content.
Often, gadgets created using the managed API actively push content to devices, so the ContentMissing event may never occur. However, you can choose only to provide content in response to the event.
Whether or not the managed API’s content cache is enabled depends on how you create the gadget. If you use a constructor that does not have the useCache parameter, then the content cache is enabled, by default. Otherwise, you must specify a value for useCache.
Whether or not the managed API’s content cache contains a particular content item depends on whether you have previously pushed the content to the device, for example by calling AddContent.
Note that the managed API’s content cache is not related to the device cache algorithm, which specifies behavior for the device content cache.