IShellFolder::SetNameOf (Compact 2013)

3/28/2014

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

Syntax

HRESULT SetNameOf(
  HWND hwndOwner,
  LPCITEMIDLIST pidl,
  LPCOLESTR lpszName,
  DWORD uFlags,
  LPITEMIDLIST* ppidlOut
);

Parameters

• hwndOwner
  [in] Handle to the owner window of any dialog or message boxes that the client displays.

• pidl
  [in] 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.

• lpszName
  [in] Pointer to a null-terminated string that specifies the new display name.

• uFlags
  [in] Flags indicating the type of name specified by the lpszName parameter. For a list of possible values, see the description of the SHGNO enumerated type.

• ppidlOut
  [out] Address of a pointer to an ITEMIDLIST structure that receives the new ITEMIDLIST.

Return Value

Returns NOERROR if successful, or an error value otherwise.

Remarks

Implementations of IShellFolder::SetNameOf usually return a pointer to the new ITEMIDLIST in the ppidlOut parameter, but callers of this interface must be capable of handling the case where *ppidlOut is not set. If you call IShellFolder::SetNameOf with ppidlOut set to NULL, it will not return a new ITEMIDLIST for the object. If an error occurs, the implementation must set *ppidlOut to NULL if ppidlOut is non-NULL.

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. This flag is essentially a hint to namespace clients. It does not necessarily imply that IShellFolder::SetNameOf will succeed or fail.

Requirements

See Also

Reference

IShellFolder
ITEMIDLIST
SHITEMID
SHGNO
IShellFolder::GetAttributesOf