About Windows SideShow Gadgets
Before writing a gadget for Windows SideShow, developers should understand the following concepts of the Windows SideShow technology.
Terminology
Application IDs
Each gadget is uniquely identified with a GUID 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; it is done 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.
Endpoint IDs
In the Windows SideShow platform, an endpoint ID 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; 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 endpoints for Windows SideShow:
- SIDESHOW_ENDPOINT_SIMPLE_CONTENT_FORMAT
- SIDESHOW_ENDPOINT_ICAL
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 Cimple 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.
Content IDs
A content ID uniquely identifies a specific piece of content with respect to an endpoint. Technically, it is an unsigned 32-bit integer that is unique only for a given application ID and endpoint ID pair. Interpretation of content IDs 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 high-level summary or "glance" content, which is always a UTF-8 encoded text string containing glance data for a gadget. Note that not all endpoints utilize content ID 0 (for example, iCalendar does not).
All other content IDs are available for use by 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.
Events
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 in order to control media playback on the computer. There are four events available to gadgets that use the Windows SideShow API:
- ISideShowEvents::DeviceAdded Method
- ISideShowEvents::DeviceRemoved Method
- ISideShowEvents::ContentMissing Method
- ISideShowEvents::ApplicationEvent Method
The DeviceAdded and DeviceRemoved 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 or disconnection, or enabling or disabling gadgets in Windows SideShow in Control Panel.
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 used 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 and stops viewing content from a gadget, respectively. For more information about SIDESHOW_EVENTID_APPLICATION_ENTER and SIDESHOW_EVENTID_APPLICATION_EXIT, see ISideShowEvents::ApplicationEvent Method.
Notifications
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, indicating 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 on and off the service, or an e-mail gadget may send a notification when new mail is received.
Gadget Manager
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
The use of the gadget manager by a gadget is optional, though highly recommended, because it helps to provide a consistent user experience on the device. The Gadget Manager is well-suited for gadgets that have no Windows UI and that run in the background.
Metadata
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:
HKLM\Software\Microsoft\SideShow\Gadgets
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.
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 has a way (through the metadata described above) to allow a gadget to indicate that it is an "online" gadget that requires the computer to be on for operation. The default is that a gadget is an "offline" gadget, meaning that its content is available to browse through on the device when the computer is off (assuming that the device is capable of this). For a gadget that specifies it is an "online" gadget, the device will not allow the user to browse through the content when the computer is off or disconnected.
Device Cache Algorithms
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 it does, 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. May 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). May 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.
Getting Started with the COM API
The first step in writing a gadget is to register with the Windows SideShow platform. Create an instance of the object that implements the ISideShowSession interface and then use the ISideShowSession::RegisterContent Method method. This call takes the application ID and endpoint ID and returns a pointer to an ISideShowContentManager.
The ISideShowContentManager interfaceinterface provides the core of the content management on the device and allows a gadget to send or remove content from connected devices or the simulator. Other interfaces augment the gadget’s functionality. The ISideShowNotificationManager interface is obtained by calling the ISideShowSession::RegisterNotifications Method and allows notifications to be sent or revoked from a device. Events are received from the device through a registered ISideShowEvents callback interface. These and other interfaces are documented and demonstrated as a part of the SDK and the associated Windows SideShow Samples.