ISideShowContentManager::SetEventSink Method

Article
11/02/2006

Provides an ISideShowEvents interface pointer through which the Windows SideShow platform can post events from associated devices to the gadget.

Declaration

[C++]

HRESULT SetEventSink(
    ISideShowEvents *in_pIEvents
);

Parameters

in_pIEvents

[in] A pointer to an ISideShowEvents interface, through which the Windows SideShow platform can post events from the Windows SideShow devices associated with this gadget.

Return Values

HRESULT value	Description
S_OK	Success.
E_FAIL	The Windows SideShow platform is not properly initialized.

Remarks

If the value of the passed interface pointer is NULL or invalid, then the Windows SideShow platform does not post any events to the Windows SideShow gadget.

An Windows SideShow gadget can have at most one event sink at a time. To remove the current event sink, pass the value NULL for the in_pIEvents parameter. To replace the current event sink, pass a different ISideShowEvents interface pointer for the in_pIEvents parameter. The Windows SideShow platform will maintain a reference to the passed in ISideShowEvents interface until the content manager object is destructed or the event sink is replaced (either will NULL or another ISideShowEvents interface).

Example

This example demonstrates how Windows SideShow gadgets should initialize the Windows SideShow platform so that the Windows SideShow platform can post events to the gadgets. This initialization includes creating an instance of a client-implemented class that implements the ISideShowEvents interface, retrieving a pointer to that interface, passing that pointer to the Windows SideShow platform, and then releasing it.

[C++]

HRESULT hr;
CSideShowEvents* pSideShowEvents;
ISideShowEvents* pISideShowEvents;

//
// Create an instance of the client-implemented
// CSideShowEvents class. Its constructor takes
// a pointer to the head of the list of content as
// a parameter. Check for successful creation.
//
pSideShowEvents = new CSideShowEvents(&ContentList);

if (NULL != pSideShowEvents)
{
    //
    // QueryInterface for the ISideShowEvents interface pointer.
    //
    hr = pSideShowEvents->QueryInterface(IID_ISideShowEvents,
                                         (void **)&pISideShowEvents);
    if (SUCCEEDED(hr))
    {
        //
        // Use the returned interface pointer to call SetEventSink,
        // using the previously established pointer to the ContentManager
        // object. This establishes the mechanism through which the
        // Windows SideShow platform will post events to the gadget.
        //
        hr = pISideShowContentManager->SetEventSink(pISideShowEvents);
        
        if (SUCCEEDED(hr))
        {
            //
            // Release the ISideShowEvents interface pointer
            // now that the Windows SideShow platform has its copy of it.
            //
            pISideShowEvents->Release();
        }
        else
        {
            //
            // Handling of failures will be application-specific.
            //
            HandleFailure("SetEventSink", hr);
        }
    }
    else
    {
        //
        // Handling of failures will be application-specific.
        //
        HandleFailure("QueryInterface in SetEventSink", hr);
    }
}
else
{
    //
    // Handling of failures will be application-specific.
    //
    HandleFailure("new CSideShowEvents", E_OUTOFMEMORY);
}

Applies To

ISideShowContentManager

Share via