IActiveDesktop::AddDesktopItemWithUI method

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

C++


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

Parameters

hwnd [in, optional]

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.

pcomp [in]

Type: LPCOMPONENT

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

dwFlags

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

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