ISideShowContent::GetContent Method

Article
11/02/2006

Retrieves content for display on a device that is associated with the Windows SideShow gadget into which it is calling.

Declaration

[C++]

HRESULT GetContent(
    ISideShowCapabilities *in_pICapabilities,
    DWORD *out_pdwSize,
    BYTE **out_ppbData
);

Parameters

in_pICapabilities

[in] Either a pointer to an ISideShowCapabilities interface or NULL. This depends on whether the Windows SideShow gadget intends to return content that is customized for the capabilities of each of its associated devices or whether the gadget intends to return content that is generic for display on all of its associated devices, respectively.

out_pdwSize

[out] A pointer to a DWORD into which the Windows SideShow platform expects the Windows SideShow gadget to write the length, in bytes, of the content returned in the out_ppbData parameter.

out_ppbData

[out] A pointer to a byte pointer into which the Windows SideShow platform expects the Windows SideShow gadget to write the address of the content to be displayed on the associated device or devices.

Return Values

HRESULT value	Description
S_OK	Success, indicating that the two out parameters contain the length and address of the content to be displayed.
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

The Windows SideShow gadget must allocate memory for the content by using CoTaskMemAlloc. The Windows SideShow platform takes responsibility for freeing the content memory, pointed to by the out_ppbData parameter, when it has finished with it.

The Boolean value that the Windows SideShow gadget sets for the DifferentiateContent property determines whether the Windows SideShow platform calls this method one or more times. If the value of that property is true, and more than one device is associated with the gadget, the Windows SideShow platform calls this method multiple times, once for each such device. The value of the in_pICapabilities parameter for each call points to an ISideShowCapabilities interface through which the gadget can determine the corresponding device capabilities, and can thus return content customized for those capabilities.

When using the Simple Content Format endpoint, the XML content provided to the platform must be encoded as UTF-8. The size of the content returned (out_pdwSize) should include the terminating NULL character, but it is not required. When copying or allocating memory containing strings, be sure to always include enough room for a terminating NULL. The function WideCharToMultiByte might be useful in converting Unicode strings into UTF-8 strings.

If the value of the DifferentiateContent property is false, the Windows SideShow platform calls this method only once, with the in_pICapabilities parameter set to NULL. Gadgets are expected to return generic content that is appropriate for display on all of the associated devices.

If this method returns an HRESULT value other than S_OK, then the corresponding call to the Add method of its ISideShowContentManager interface returns E_INVALIDARG.

Example

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

In this example, the content length and the content itself are stored locally in the m_ContentLength and m_pContentXML member variables, respectively, when the constructor for the CSideShowContent class is called.

[C++]

STDMETHODIMP CSideShowContent::GetContent(ISideShowCapabilities* pCapabilities,
                                          DWORD* pContentByteCount,
                                          BYTE** ppContentBuf)
{
    //
    // Declare a buffer pointer to contain the content.
    //
    BYTE* pContentBuf;

    //
    // Allocate memory to contain the content. Use CoTaskMemAlloc
    // so that the platform can properly release it.
    //
    pContentBuf = (BYTE*)CoTaskMemAlloc(m_ContentLength);
    
    //
    // Return an error if no memory was available.
    //
    if (NULL == pContentBuf)
    {
        return E_OUTOFMEMORY;
    }

    //
    // Copy the content into the newly allocated memory.
    //
    memcpy((void*)pContentBuf,
           (void*)m_pContentXML,
           (size_t)m_ContentLength);

    //
    // Set the out parameters before returning successfully.
    //
    *pContentByteCount = m_ContentLength;

    *ppContentBuf = (BYTE*)pContentBuf;

    return S_OK;
}

Applies To

ISideShowContent

Partager via