IShellFolder::ParseDisplayName

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

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.

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

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

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

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

See Also

Reference

IShellFolder
IShellFolder::GetAttributesOf
ITEMIDLIST
SHITEMID

Other Resources

IParseDisplayName::ParseDisplayName