ISideShowContentManager::Add Method
Retrieves content for display on the Windows SideShow-compatible devices that are associated with a gadget.
Declaration
[C++]
HRESULT Add(
ISideShowContent *in_pIContent
);
Parameters
in_pIContent
[in] A pointer to an ISideShowContent interface, implemented by the Windows SideShow gadget making this call, through which the Windows SideShow platform retrieves the actual content to be displayed on the associated Windows SideShow-compatible devices.
Return Values
HRESULT value |
Description |
S_OK |
Success. |
S_FALSE |
Sending content to one or more Windows SideShow-compatible devices failed, or there are no such devices to which content can be sent. |
E_INVALIDARG |
The in_pIContent parameter is NULL or otherwise invalid, if subsequent calls to retrieve the values of the ContentId or DifferentiateContent properties fail, for example. |
E_FAIL |
The Windows SideShow platform is not properly initialized. |
Remarks
A Windows SideShow gadget implements the ISideShowContent interface, through which the Windows SideShow platform retrieves content to be added to the caches of the Windows SideShow-compatible devices that are associated with the gadget.
The gadget uses this method to request that the Windows SideShow platform use the provided interface pointer to retrieve the content from the gadget.
The Windows SideShow platform does not maintain a cache of the ISideShowContent interface pointers that are passed to it by using this method. After using the interface to transfer content to the associated devices, it releases its reference to it. Windows SideShow gadgets should maintain a cache of ISideShowContent interface pointers for the gadgets' content to facilitate the ability to respond quickly to a subsequent need for the associated content, when the ContentMissing method of the ISideShowEvents interface is called, for example, or when a new device has been added.
Glance content is text-only content that has a content identifier of 0 (zero) and typically contains the highest level of summary information for a gadget; this may be the temperature in selected cities for a weather gadget, current playing track information for a media player gadget, or recent mail headers from your inbox for a mail gadget. This glance content is always sent as a null-terminated UTF-8 string, and has a content ID of 0. The use of content ID 0 is reserved for glance content for each endpoint, though it is recommended that gadgets supporting endpoints other than the Simple Content Format (SCF) for content should also support the SCF endpoint and provide at least content ID 0. For more information on content identifiers, see the ISideShowContent::ContentId Property of the ISideShowContent interface.
Example
This example demonstrates how Windows SideShow gadgets add content to their connected Windows SideShow-compatible devices. It assumes that an instance of a client-implemented class that implements the ISideShowContent interface already exists and is pointed to by the pContent variable shown in the QueryInterface line.
[C++]
HRESULT hr;
ISideShowContent* pISideShowContent;
//
// QueryInterface for the ISideShowContent interface pointer.
//
hr = pContent->QueryInterface(IID_ISideShowContent,
(void **)&pISideShowContent);
if (SUCCEEDED(hr))
{
//
// Pass the returned interface pointer to the Add method,
// using a previously established pointer to the
// ContentManager object. Also, check for failure.
//
hr = pISideShowContentManager->Add(pISideShowContent);
if (FAILED(hr))
{
//
// Handling of failures will be application-specific.
//
HandleFailure("Add", hr);
}
//
// Release the ISideShowContent interface pointer.
//
pISideShowContent->Release();
}
else
{
HandleFailure("QueryInterface in Add", hr);
}