ISideShowNotification::ExpirationTime Property
Contains the expiration date and time of a notification as a SYSTEMTIME structure.
Declaration
[C++]
HRESULT get_ExpirationTime(
SYSTEMTIME *out_pTime
);
HRESULT put_ExpirationTime(
SYSTEMTIME *in_pTime
);
Property Value
out_pTime
[out] A pointer to a SYSTEMTIME structure that contains the expiration date and time established for the notification by the Windows SideShow gadget and retrieved by the Windows SideShow platform. If the returned SYSTEMTIME structure contains all zero values, then the default expiration time of the device is used. This time may vary depending on the specific device.
in_pTime
[in] A pointer to a SYSTEMTIME structure that contains the expiration date and time, presumably established by the Windows SideShow gadget. If the caller passes a NULL pointer for this parameter, the default expiration time of the device is used. This time may vary depending on the specific device.
This property is read/write.
Return Values
HRESULT value |
Description |
S_OK |
Success |
E_INVALIDARG |
A NULL pointer was passed as the value of the out_pTime parameter. |
Remarks
Instances of a Component Object Model (COM) object that implement the ISideShowNotification interface, of which this property is a member, are created by the Windows SideShow gadget. After creation, the gadget sets the value of this property so that the Windows SideShow platform can retrieve it.
Passing a NULL pointer as the value of the in_pTime parameter indicates that the notification will use the default expiration time of the device. This time may vary depending on the specific device.
When a pointer to a SYSTEMTIME structure is passed to either of these property routines, the caller retains ownership of the corresponding memory.
The date and time should be specified and interpreted as local system time. Notifications should dismiss themselves after that date and time have passed, regardless of whether it has been displayed or not. It is up to the firmware on the device or the driver to properly honor the expiration time.
The default value of this property is all zero values within the SYSTEMTIME structure, indicating that the default expiration time for the device is associated with this notification.
Example
This example demonstrates how to set the value of the ISideShowNotification::ExpirationTime Property property in an instance of the SideShowNotification class. Before setting the value of this property, Windows SideShow gadgets must create an instance of the SideShowNotification class, as demonstrated in the example for the ISideShowNotification interface. After setting the value of this property, and after setting other property values in the instance of the SideShowNotification class, Windows SideShow gadgets normally show the notification, as demonstrated by the example for the Show method of the ISideShowNotificationManager interface.
In this example, before setting the value of the ISideShowNotification::ExpirationTime Property property, the current system time is retrieved and the client-specific routine, AddThirtySeconds, is called to give the notification a 30-second lifespan.
[C++]
HRESULT hr;
SYSTEMTIME ExpirationTime = {0, 0, 0, 0, 0, 0, 0, 0};
//
// Call GetSystemTime to retrieve the current time.
// Add 30 seconds to the current time and use that as
// the expiration time of the notification.
//
GetSystemTime(&ExpirationTime);
AddThirtySeconds(&ExpirationTime);
//
// Call put_ExpirationTime to write the ExpirationTime property,
// passing the address of the SYSTEMTIME structure.
//
// Use a previously established pointer to the
// ISideShowNotification interface of an
// SideShowNotification object.
//
// Also check for failure.
//
hr = pISideShowNotification->put_ExpirationTime(&ExpirationTime);
if (FAILED(hr))
{
//
// Handling of failures will be application-specific.
//
HandleFailure("put_ExpirationTime", hr);
}