Edit

IShellFolder::SetNameOf method (shobjidl_core.h)

  • Article

Sets the display name of a file object or subfolder, changing the item identifier in the process.

Syntax

HRESULT SetNameOf(
  [in]  HWND            hwnd,
  [in]  PCUITEMID_CHILD pidl,
  [in]  LPCWSTR         pszName,
  [in]  SHGDNF          uFlags,
  [out] PITEMID_CHILD   *ppidlOut
);

Parameters

[in] hwnd

Type: HWND

A handle to the owner window of any dialog or message box that the client displays.

[in] pidl

Type: PCUITEMID_CHILD

A pointer to an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder. The structure must contain exactly one SHITEMID structure followed by a terminating zero.

[in] pszName

Type: LPCWSTR

A pointer to a null-terminated string that specifies the new display name.

[in] uFlags

Type: SHGDNF

Flags that indicate the type of name specified by the pszName parameter. For a list of possible values and combinations of values, see SHGDNF.

[out] ppidlOut

Type: PITEMID_CHILD*

Optional. If specified, the address of a pointer to an ITEMIDLIST structure that receives the ITEMIDLIST of the renamed item. The caller requests this value by passing a non-null ppidlOut. Implementations of IShellFolder::SetNameOf must return a pointer to the new ITEMIDLIST in the ppidlOut parameter.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Changing the display name of a file system object, or a folder within it, renames the file or directory.

Before calling this method, applications should call IShellFolder::GetAttributesOf and check that the SFGAO_CANRENAME flag is set. Note that this flag is essentially a hint to namespace clients. It does not necessarily imply that IShellFolder::SetNameOf will succeed or fail.

Implementers of IShellFolder::SetNameOf must call SHChangeNotify with both the old and new absolute PIDLs once the renaming of an object is complete. This following example shows the call to SHChangeNotify following the renaming of a folder object.

SHChangeNotify(SHCNE_RENAMEFOLDER, SHCNF_IDLIST, pidlFullOld, pidlFullNew);

This call prevents both the old and new names being displayed in the view.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header shobjidl_core.h (include Shobjidl.h)
DLL Shell32.dll (version 4.0 or later)