IShellFolder::ParseDisplayName (Compact 2013)

3/28/2014

This method translates the display name of a file object or folder into an item identifier list.

Syntax

HRESULT ParseDisplayName(
  HWND hwnd,
  LPBC pbc,
  LPOLESTR pwszDisplayName,
  ULONG* pchEaten,
  LPITEMIDLIST* ppidl,
  ULONG* pdwAttributes
);

Parameters

• hwnd
  [in] Optional window handle. The client should provide a window handle if it displays a dialog or message box. Otherwise, set hwnd to NULL.

• pbc
  [in] Optional bind context that controls the parsing operation. This parameter is typically set to NULL.

• pwszDisplayName
  [in] Null-terminated UNICODE string with the display name. Because each shell folder defines its own parsing syntax, the form this string can take may vary. The desktop folder, for instance, accepts paths such as "c:\My Docs\My File.txt". It also accepts references to items in the namespace that have a globally unique identifier (GUID) associated with them using the "::{GUID}" syntax. For example, to retrieve a fully qualified identifier list for the control panel from the desktop folder, you can use"{CLSID for My Computer}\::{CLSID for the Control Panel}".

• pchEaten
  [out] Pointer to a ULONG value that receives the number of characters of the display name that was parsed. If your application does not need this information, set pchEaten to NULL, and no value will be returned.

• ppidl
  [out] Pointer to an ITEMIDLIST pointer that receives the item identifier list for the object. The returned item identifier list specifies the item relative to the parsing folder. If the object associated with pwszDisplayName is within the parsing folder, the returned item identifier list contains only one SHITEMID structure. If the object is in a subfolder of the parsing folder, the returned item identifier list contains multiple SHITEMID structures. If an error occurs, NULL is returned in this address.

• pdwAttributes
  [in, out] Optional parameter that can be used to query for file attributes. If not used, it should be set to NULL. To query for one or more attributes, initialize the pdwAttributes with the flags that represent the attributes of interest. On return, those attributes that are true and were requested are set. See Remarks for possible values.

Return Value

Returns NOERROR if successful, or an error value otherwise.

Remarks

Some shell folders may not implement IShellFolder::ParseDisplayName. Each folder that does defines its own parsing syntax.

The following values are valid for the pdwAttributes parameter.

A file object's capability flags may be zero or a combination of values shown in the following table.

Flag (value)	Description
SFGAO_CANCOPY (0x00000001)	The specified file objects or folders can be copied (same value as the DROPEFFECT_COPY flag).
SFGAO_CANDELETE (0x00000020)	The specified file objects or folders can be deleted.
SFGAO_CANLINK (0x00000004)	Shortcuts can be created for the specified file objects or folders. This flag has the same value as DROPEFFECT. The typical use of this flag is to add a Create Shortcut item to the shortcut menu that is displayed during drag-and-drop operations. However, SFGAO_CANLINK also adds a Create Shortcut item to the Windows Explorer File menu, and to typical shortcut menus. If this item is selected, your application's IContextMenu::InvokeCommand interface is invoked with the lpVerb member of the CMINVOKECOMMANDINFO structure set to "link". Your application is responsible for creating the link.
SFGAO_CANMONIKER (0x00400000)	It is possible to create monikers for the specified file objects or folders.
SFGAO_CANMOVE (0x00000002)	The specified file objects or folders can be moved (same value as the DROPEFFECT_MOVE flag).
SFGAO_CANRENAME (0x00000010)	The specified file objects or folders can be renamed. This flag is essentially a suggestion. It does not guarantee that a namespace client will rename the file or folder object.
SFGAO_CAPABILITYMASK (0x00000177)	A mask for the capability flags.
SFGAO_DROPTARGET (0x00000100)	The specified file objects or folders are drop targets.
SFGAO_HASPROPSHEET (0x00000040)	The specified file objects or folders have property sheets.

A file object's display attributes may be zero or a combination values shown in the following table.

Flag (value)	Description
SFGAO_DISPLAYATTRMASK (0x000F0000)	A mask for the display attributes.
SFGAO_GHOSTED (0x00080000)	The specified file objects or folders should be displayed using a ghosted icon.
SFGAO_LINK (0x00010000)	The specified file objects are shortcuts.
SFGAO_READONLY (0x00040000)	The specified file objects or folders are read-only.
SFGAO_SHARE (0x00020000)	The specified folders are shared.
SFGAO_DISPLAYATTRMASK (0x000F0000)	A mask for the display attributes.

A file object's contents flags may be zero or a combination values shown in the following table.

Flag (value)	Description
SFGAO_CONTENTSMASK (0x80000000)	A mask for the contents attributes.
SFGAO_HASSUBFOLDER (0x80000000)	The specified folders may have subfolders, and are therefore expandable in the left pane of Windows Explorer. The SFGAO_HASSUBFOLDER attribute is only advisory, and may be returned by shell folder implementations even if they do not contain subfolders. Returning SFGAO_HASSUBFOLDER is recommended whenever a significant amount of time is required to determine whether or not any subfolders exist. For example, the shell always returns SFGAO_HASSUBFOLDER when a folder is located on a network drive.

A file object's miscellaneous attributes may be zero or a combination values shown in the following table.

Flag (value)	Description
SFGAO_BROWSABLE (0x08000000)	The specified items can be browsed in place.
SFGAO_COMPRESSED (0x04000000)	The specified items are compressed.
SFGAO_FILESYSTEM (0x40000000)	The specified folders or file objects are part of the file system (that is, they are files, directories, or root directories).
SFGAO_FILESYSANCESTOR (0x10000000)	The specified folders contain one or more file system folders.
SFGAO_FOLDER (0x20000000)	The specified items are folders.
SFGAO_NEWCONTENT (0x00200000)	The objects contain new content.
SFGAO_NONENUMERATED (0x00100000)	The items are not enumerated.
SFGAO_REMOVABLE (0x02000000)	The specified file objects or folders are on removable media.
SFGAO_VALIDATE (0x01000000)	Validate cached information. The shell confirms that the objects specified in apidl still exist and does not use cached information when retrieving the attributes. If one or more of the items specified in apidl no longer exist, this method returns an error code. If cidl is zero, the shell discards all cached information for the shell folder. This is similar to doing a refresh of the folder.

Querying for some attributes may be relatively slow and use significant amounts of memory. For example, to determine if a file is shared, the shell loads network components. This procedure may require the loading of several dynamic-link libraries (DLLs). The purpose of dwAttributes is to allow you to restrict the query to only the information that is needed.

The following example shows how to find out if a file is compressed.

IShellFolder *psf;
DWORD dwAttribs = SFGAO_COMPRESSED;
...
hres = psf->ParseDisplayName(NULL,
            NULL,
            lpwszDisplayName,
            &cbEaten,
            &pidl,
            &dwAttribs);
if(dwAttribs & SFGAO_COMPRESSED)
{
//do something with the compressed file
}

Because pdwAttributes is a parameter that is used for both input and output, you should always initialize it. If you pass in an uninitialized value, some of the bits may be set. IShellFolder::ParseDisplayName then queries for the corresponding attributes, and this may lead to undesirable delays or memory demands. If you do not wish to query for attributes, set pdwAttributes to NULL to avoid unpredictable behavior.

This method is similar to the IParseDisplayName::ParseDisplayName method.

Requirements

Header	shobjidl.h, shobjidl.idl
Library	Developer Implemented

See Also

Reference

IShellFolder
IShellFolder::GetAttributesOf
ITEMIDLIST
SHITEMID

Other Resources

IParseDisplayName::ParseDisplayName