ISideShowSession::RegisterContent Method 

  • [アーティクル]

Registers the calling Windows SideShow gadget with the Windows SideShow platform, thereby enabling it to send content to devices that support the specified endpoint.

Declaration

[C++]

HRESULT RegisterContent(
    REFAPPLICATION_ID in_applicationId,
    REFENDPOINT_ID in_endpointId,
    ISideShowContentManager **out_ppIContent
);

Parameters

in_applicationId

[in] The application identifier of the Windows SideShow gadget requesting to register for sending content to the specified endpoint.

in_endpointId

[in] The identifier of the endpoint to which the Windows SideShow gadget is registering to send content.

out_ppIContent

[out] A handle to the ISideShowContentManager interface, which the Windows SideShow gadget uses to send content to the device corresponding to the specified endpoint, and through which that data is managed.

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_ppIContent parameter contains a valid handle to an ISideShowContentManager interface.

E_INVALIDARG

Either the out_ppIContent parameter is NULL, or the gadget and/or endpoint identifiers are not valid. This occurs when the endpoint is not supported by the gadget, for example.

E_FAIL

Content registration failed. In this case, the value of the out_ppIContent parameter is NULL.

Remarks

The Windows SideShow gadget can call this method for each endpoint that it supports, and receives a distinct ISideShowContentManager interface handle for each endpoint. For information about the endpoints that are pre-defined by the platform, see Platform-Defined Endpoints.

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 ISideShowContentManager 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::RegisterContent Method and the RegisterNotifications 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;
ISideShowContentManager* pISideShowContentManager;

//
// Call the RegisterContent method using the previously established
// pointer to the Session object. This will retrieve
// a pointer to an object that implements the
// ISideShowContentManager interface. Also, check
// for failures and maintain the pointer for subsequent
// calls to Add, Remove, RemoveAll, and so on.
//
// SIDESHOW_ENDPOINT_SIMPLE_CONTENT_FORMAT is defined in the file
// WindowsSideShow.h.
//
hr = pISideShowSession->RegisterContent(SIDESHOW_SAMPLE_CLIENT,
                                        SIDESHOW_ENDPOINT_SIMPLE_CONTENT_FORMAT,
                                        &pISideShowContentManager);

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

Applies To

ISideShowSession

See Also

Concepts

ISideShowContentManager
ISideShowSession::RegisterNotifications Method