ApplicationEvent Method

Provides a mechanism for a Windows SideShow-compatible device to post predefined 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, which indicates 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 predefined 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 ApplicationEvent Method in the client-implemented ISideShowEvents interface. Other implementations are 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++]

STDMETHODIMP CSideShowEvents::ApplicationEvent(ISideShowCapabilities* pCapabilities,
                                                 const DWORD EventID,
                                                 const DWORD EventSize,
                                                 const BYTE* pEventData)
{
    //
    // Declare pointers to all three possible event data structures.
    //
    PSCF_CONTEXTMENU_EVENT pContextMenuEvent;
    PSCF_MENUACTION_EVENT  pMenuActionEvent;
    PSCF_NAVIGATION_EVENT  pNavigationEvent;

    //
    // Switch on the event identifier, expecting one of the
    // three Simple Content Format events.
    //
    switch (EventID)
    {
        case SCF_EVENT_CONTEXTMENU:
            //
            // Validate the size of the event data with its expected size.
            //
            if (EventSize == sizeof(SCF_CONTEXTMENU_EVENT))
            {
                //
                // If the size is right, cast the event data to
                // the previously declared pointer of the appropriate
                // type and call an application-specific routine
                // to process the context menu event.
                //
                pContextMenuEvent = (PSCF_CONTEXTMENU_EVENT)pEventData;

                ProcessContextMenuEvent(pContextMenuEvent);
            }
            else
            {
                //
                // Handle the failure case where the size of the data
                // passed with this event is not what was expected.
                //
                // Handling of failures will be application-specific.
                //
                HandleFailure("ContextMenu data not expected size", 0);
            }
            break;

        case SCF_EVENT_MENUACTION:
            //
            // Validate the size of the event data with its expected size.
            //
            if (EventSize == sizeof(SCF_MENUACTION_EVENT))
            {
                //
                // If the size is right, cast the event data to
                // the previously declared pointer of the appropriate
                // type and call an application-specific routine
                // to process the context menu event.
                //
                pMenuActionEvent = (PSCF_MENUACTION_EVENT)pEventData;

                ProcessMenuActionEvent(pMenuActionEvent);
            }
            else
            {
                //
                // Handle the failure case where the size of the data
                // passed with this event is not what was expected.
                //
                // Handling of failures will be application-specific.
                //
                HandleFailure("MenuAction data not expected size", 0);
            }
            break;

        case SCF_EVENT_NAVIGATION:
            //
            // Validate the size of the event data with its expected size.
            //
            if (EventSize == sizeof(SCF_NAVIGATION_EVENT))
            {
                //
                // If the size is right, cast the event data to
                // the previously declared pointer of the appropriate
                // type and call an application-specific routine
                // to process the context menu event.
                //
                pNavigationEvent = (PSCF_NAVIGATION_EVENT)pEventData;

                ProcessNavigationEvent(pNavigationEvent);
            }
            else
            {
                //
                // Handle the failure case where the size of the data
                // passed with this event is not what was expected.
                //
                // Handling of failures will be application-specific.
                //
                HandleFailure("Navigation data not expected size", 0);
            }
            break;

        default:
            //
            // Handle the failure case where an unexpected
            // event occurred.
            //
            // Handling of failures will be application-specific.
            //
            HandleFailure("Unexpected event", 0);
            break;

    }  // End of switch statement.

    return S_OK;

}

Applies To

ISideShowEvents

See Also

Concepts

ISideShowContentManager
SetEventSink Method

Other Resources

Introduction to Simple Content Format and Endpoints