ISideShowEvents::ApplicationEvent Method 

Provides a mechanism for a Windows SideShow-compatible device to post pre-defined events to its associated Windows SideShow gadget.

Declaration

[C++]

HRESULT ApplicationEvent(
    ISideShowCapabilities *in_pICapabilities,
    const DWORD in_dwEventId,
    const DWORD in_dwEventSize,
    const BYTE *in_pbEventData
);

Parameters

in_pICapabilities

[in] A pointer to an ISideShowCapabilities interface that describes the device that is posting the event.

in_dwEventId

[in] The event identifier, which uniquely identifies the event within the scope of the endpoint used by the gadget.

in_dwEventSize

[in] The length, in bytes, of the event data pointed to by the in_pbEventData parameter.

in_pbEventData

[in] A pointer to the event data that corresponds to the event identifier that is passed in the in_dwEventId parameter and the data length that is passed in the in_dwEventSize parameter.

Return Values

HRESULT value	Description
S_OK	Success, indicating that the gadget successfully handled the event.
Other HRESULT values	The Windows SideShow gadget may return HRESULT values other than S_OK to communicate error conditions to the Windows SideShow platform.

Remarks

A Windows SideShow gadget implements the ISideShowEvents interface, through which the Windows SideShow platform posts events to a gadget. The gadget uses the SetEventSink method of the ISideShowContentManager interface to provide a pointer to the ISideShowEvents interface through which events should be posted.

Event identifiers and the structure of the corresponding event data are determined by the particular endpoint used by the gadget to communicate with the device.

One example of how application events might be used is for user-initiated navigation on a device, wherein events posted by using this method result in a display of new content on the device.

There are two pre-defined application events which are sent for all endpoints: SIDESHOW_EVENTID_APPLICATION_ENTER and SIDESHOW_EVENTID_APPLICATION_EXIT. These events are sent by a device when a user initiates and terminates interaction with a gadget on the device. The events are sent so that gadgets can detect when they are likely to be used and perform any necessary actions to prepare for it.

Example

This example demonstrates one possible implementation of the ISideShowEvents::ApplicationEvent Method in the client-implemented ISideShowEvents interface. Other implementations are, of course, possible.

This example assumes that the Simple Content Format is in use, and is consequently expecting one of the three Simple Content Format events. For each event, it validates that the size of the data is as expected, and it then calls a gadget-specific routine to process the event.

[C++]

Applies To

ISideShowEvents

See Also

Concepts

ISideShowContentManager
ISideShowContentManager::SetEventSink Method

Other Resources

Introduction to Simple Content Format and Endpoints