ISideShowContent::ContentId Property
Returns the numeric identifier associated with this item of content so that it may be revoked at a later time.
Declaration
[C++]
HRESULT get_ContentId(
PCONTENT_ID out_pcontentId
);
Property Value
out_pcontentId
[out] A pointer to a CONTENT_ID type into which the Windows SideShow gadget writes the unique numeric identifier associated with this item of content.
This property is read-only.
Return Values
HRESULT value |
Description |
S_OK |
Success, indicating that the Windows SideShow gadget successfully wrote the content identifier to the location provided by the Windows SideShow platform. |
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 platform calls this method to retrieve the content identifier only once for each call to the Add method of its ISideShowContentManager interface, regardless of whether it calls the GetContent method once or multiple times (based on the value of the DifferentiateContent property).
The identifier associated with this property is assigned by the Windows SideShow gadget and is used by the gadget and platform to refer to this item of content in other method calls such as the Remove method of the ISideShowContentManager interface and the ContentMissing method of the ISideShowEvents interface.
The content identifier 0 (zero), which is defined by the constant CONTENT_ID_GLANCE, has special meaning and is known as the "glance content identifier." Content associated with this identifier is always a UTF-8 string containing plain text, regardless of the content format employed by the corresponding endpoint, such as the XML format defined for the Simple Content Format. The plain text:
- Should provide high-level information about the type of content (or other real-time information about the content) provided by a gadget.
- Is displayed according to the capabilities of the corresponding device. (Some devices might display the text below the gadget icon on the home screen of the device, while more simple devices might display this text and nothing else on the home screen.)
Examples of glance content include:
- 7 unread e-mail messages
- Next Appointment: 11 A.M. at 123 Main
Gadgets may provide as much or as little glance data as they desire, however the recommended amount is twelve (12) lines of text, with each line separated by a CRLF ("\r\n"). For more information on guidelines for providing glance data, see User Experience Guidelines for Gadgets.
If this method returns an HRESULT value other than S_OK, the corresponding call to the Add method of its ISideShowContentManager interface will return E_INVALIDARG.
Different items of content must be assigned unique values for this property. If two items of content are assigned the same identifier, the second such item sent to the associated devices supersedes the first.
Example
This example demonstrates one possible implementation of the ISideShowContent::ContentId Property in the client-implemented ISideShowContent interface. Other implementations are, of course, possible.
In this example, the content identifier was stored locally in the m_ContentID member variable when the constructor for the CSideShowContent class was called.
[C++]
STDMETHODIMP CSideShowContent::get_ContentId(PCONTENT_ID pContentID)
{
//
// Copy the content identifier into the
// out parameter and return successfully.
//
*pContentID = m_ContentID;
return S_OK;
}