IActiveDesktop::AddDesktopItemWithUI method (shlobj_core.h)

Article
10/13/2021

Adds a desktop item to the Active Desktop after displaying user interfaces that confirm the addition of the desktop item, verifying security zone permissions, and asking if the user wants to create a subscription.

Syntax

HRESULT AddDesktopItemWithUI(
  [in, optional] HWND        hwnd,
  [in]           LPCOMPONENT pcomp,
                 DWORD       dwReserved
);

Parameters

[in, optional] hwnd

Type: HWND

The handle of the parent window. If NULL, the desktop item is added without displaying any user interface, in accordance with the corresponding security zone permissions. For more information, see About URL Security Zones.

[in] pcomp

Type: LPCOMPONENT

Address of the COMPONENT structure containing the details of the desktop item to be added.

dwReserved

Type: DWORD

Unsigned long integer value that contains the flags that control how the desktop item is added. Can be one of the following values.

DTI_ADDUI_DEFAULT

Do default action. Identical to using zero.

DTI_ADDUI_DISPSUBWIZARD

Activate the subscription wizard to allow the user to subscribe to this desktop item.

DTI_ADDUI_POSITIONITEM

Instruct the system to look at the COMPPOS structure passed to the cpPos member of the COMPONENT structure to ensure that the values are within reasonable limits. This value was added for Internet Explorer 5.

Return value

Type: HRESULT

Returns one of the following values.

Return code	Description
E_FAIL	Failed to add the desktop item, or an instance of the desktop item already exists on the Active Desktop.
E_INVAILDARG	One or more of the parameters were invalid.
S_OK	If the ADDURL_SILENT flag has been set, the desktop item has either been added successfully or it already exists on the Active Desktop. Otherwise, the desktop item has been added successfully.

Remarks

This method creates a second instance of the Active Desktop to add the desktop item, so the desktop item does not appear in the current instance. The application must call the IUnknown::Release method on this IActiveDesktop interface and then use the CoCreateInstance function to retrieve the Active Desktop object with the newly added component.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	shlobj_core.h
DLL	Shell32.dll (version 4.71 or later)