ISideShowEvents::ContentMissing Method

Article
11/02/2006

Notifies the Windows SideShow gadget that a particular item of content is missing and must be supplied.

Declaration

[C++]

HRESULT ContentMissing(
    const CONTENT_ID in_contentId,
    ISideShowContent **out_ppIContent
);

Parameters

in_contentId

[in] The identifier associated with the content that is missing according to the Windows SideShow platform.

out_ppIContent

[out] A pointer into which the Windows SideShow gadget writes the address of the ISideShowContent interface through which the Windows SideShow platform can retrieve the content that is missing.

Return Values

HRESULT value	Description
S_OK	Success, indicating that the event has been handled. It is not necessary to return an ISideShowContent interface to return this success code.
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 the 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.

When this call returns with the address of an ISideShowContent interface, the Windows SideShow platform processes the content in much the same way as when the Add method of the ISideShowContentManager interface is called. When your gadget returns an interface pointer in out_ppIContent, it must return a pointer for which IUnknown::AddRef has already been called. Typically a gadget performs a IUnknown::QueryInterface call on the interface to return, using out_ppIContent as the pointer into which the interface pointer is placed. The platform will automatically call IUnknown::Release on this interface when it is finished using it.

The Windows SideShow gadget may choose to return NULL as the value of the out_pIContent parameter and an HRESULT of S_OK, which the Windows SideShow platform will not interpret as an error. In this case, it is expected that the gadget will instead provide the requested content by using the Add method of the ISideShowContentManager interface.

When multiple Windows SideShow devices are associated with a Windows SideShow gadget and this method is called, the gadget cannot determine from which of the devices the event originated.

Example

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

In this example, content control blocks (type tContentCB) are used to maintain a list of pointers to instances of the CSideShowContent class. When the ISideShowEvents::ContentMissing Method is called by the Windows SideShow platform, this Windows SideShow gadget searches through this list, looking for the matching content. If it is found, a pointer to the ISideShowContent interface of the relevant CSideShowContent object is returned to the Windows SideShow platform.

[C++]

STDMETHODIMP CSideShowEvents::ContentMissing(const CONTENT_ID MissingContentID,
                                             ISideShowContent** ppIContent)
{
    //
    // Retrieve the first content control block using the member
    // variable that points at the list head.
    //
    tpContentCB pContentCB = m_pContentListHead->pFirstContentCB;

    HRESULT    hr;
    CONTENT_ID ContentID;
    bool       bFoundContent = false;

    //
    // Search through the list for the missing content.
    //
    do
    {
        //
        // QueryInterface for the ISideShowContent interface pointer.
        //
        ISideShowContent* pISideShowContent;
        hr = pContentCB->pContent->QueryInterface(IID_ISideShowContent,
                                                  (void **)&pISideShowContent);
        if (SUCCEEDED(hr))
        {
            //
            // Use the returned interface pointer to retrieve
            // the content identifier. Check for success.
            //
            hr = pISideShowContent->get_ContentId(&ContentID);

            //
            // As well as checking the HRESULT value, compare the
            // returned content identifier to the one passed as an
            // in parameter to this method. If there is a match,
            // record that the content was found, process the match,
            // and exit the loop early.
            //
            if ((SUCCEEDED(hr)) && (MissingContentID == ContentID))
            {
                bFoundContent = true;

                //
                // Set the out parameter to the ISideShowContent
                // interface pointer that had the matching content identifier.
                // Do not call Release on this interface pointer; it is the
                // responsibility of the caller (the Windows SideShow platform)
                // to call Release when it is finished with the interface.
                //
                *ppIContent = pISideShowContent;

                break;
            }

            //
            // Release the ISideShowContent interface pointer
            // that was not a match before the next iteration.
            //
            pISideShowContent->Release();
        }
        else
        {
            //
            // Handling of failures will be application-specific.
            //
            HandleFailure("QueryInterface for ISideShowContent", hr);
        }

        //
        // Advance to the next element in the list.
        //
        pContentCB = pContentCB->pNextCB;

    } while (pContentCB != NULL);

    //
    // If the missing content was found, return successfully.
    //
    if (true == bFoundContent)
    {
        return S_OK;
    }

    //
    // Otherwise indicate that the content was not found,
    // perhaps because the provided content identifier was not valid.
    //
    else
    {
        return E_INVALIDARG;
    }
}

Applies To

ISideShowEvents

Share via