ISideShowSession::RegisterNotifications Method

Article
11/02/2006

Registers the calling Windows SideShow gadget for notifications, thereby allowing the gadget to send and manage notifications on devices.

Declaration

[C++]

HRESULT RegisterNotifications(
    REFAPPLICATION_ID in_gadgetId,
    ISideShowNotificationManager **out_ppINotification
);

Parameters

in_gadgetId

[in] The application identifier of the Windows SideShow gadget requesting to register for notifications with the Windows SideShow platform.

out_ppINotification

[out] A pointer to the ISideShowNotificationManager interface that the Windows SideShow gadget uses to send and manage notifications on devices.

Return Values

Possible values include, but are not limited to, those in the following table.

HRESULT value	Description
S_OK	Success, indicating that the out_ppINotification parameter contains a valid pointer to an ISideShowNotificationManager interface.
E_INVALIDARG	Either the out_ppIContent parameter is NULL, or the application identifier is not valid.
E_FAIL	Notification registration failed. In this case, the value of the out_ppINotification parameter is NULL.

Remarks

The Windows SideShow gadgets call this method once and use the returned ISideShowNotificationManager interface pointer for sending and managing notifications for all of the devices with which they are configured to communicate.

This method fails if the Windows SideShow gadget is not properly registered with the Windows SideShow platform. The properly registered gadget appears in the Windows SideShow Control Panel. For more information about this, see Installing a Gadget.

This method succeeds even if there are no currently connected or enabled Windows SideShow devices. The Windows SideShow Control Panel must be used to enable Windows SideShow devices for each Windows SideShow gadget.

Example

This example demonstrates how to retrieve a pointer to the ISideShowNotificationManager interface after having created an instance of the SideShowSession class. For an example of creating an instance of the SideShowSession class, see ISideShowSession.

The first section of code shows an example of the application identifier GUID that Windows SideShow gadgets must define for themselves and pass to both the ISideShowSession::RegisterNotifications Method and the RegisterContent method.

[C++]

// {E6C8D205-D04D-4783-867F-28B7F526537D}
static const APPLICATION_ID SIDESHOW_SAMPLE_CLIENT = 
{ 0xe6c8d205, 0xd04d, 0x4783, { 0x86, 0x7f, 0x28, 0xb7, 0xf5, 0x26, 0x53, 0x7d } };

HRESULT hr;
ISideShowNotificationManager* pISideShowNotificationManager;

//
// Call the RegisterNotifications method using the previously
// established pointer to the Session object. This will
// retrieve a pointer to an object that implements the
// ISideShowNotificationManager interface. Also, check
// for failures and maintain the pointer for subsequent
// calls to Show, Revoke, and RevokeAll.
//
hr = pISideShowSession->RegisterNotifications(SIDESHOW_SAMPLE_CLIENT,
                                              &pISideShowNotificationManager);

if (FAILED(hr))
{
    //
    // Handling of failures will be application-specific.
    //
    HandleFailure("RegisterNotifications", hr);
}

Applies To

ISideShowSession