Export (0) Print
Expand All
Expand Minimize

SHGetKnownFolderItem function

Retrieves an IShellItem object that represents a known folder.

Syntax


HRESULT SHGetKnownFolderItem(
  _In_   REFKNOWNFOLDERID rfid,
  _In_   KNOWN_FOLDER_FLAG dwFlags,
  _In_   HANDLE hToken,
  _In_   REFIID riid,
  _Out_  void **ppv
);

Parameters

rfid [in]

Type: REFKNOWNFOLDERID

A reference to the KNOWNFOLDERID, a GUID that identifies the folder that contains the item.

dwFlags [in]

Type: KNOWN_FOLDER_FLAG

Flags that specify special options used in the retrieval of the known folder IShellItem. This value can be 0; otherwise, one or more of the KNOWN_FOLDER_FLAG values.

hToken [in]

Type: HANDLE

An access token used to represent a particular user. This parameter is usually set to NULL, in which case the function tries to access the current user's instance of the folder. However, you may need to assign a value to hToken for those folders that can have multiple users but are treated as belonging to a single user. The most commonly used folder of this type is Documents.

The calling application is responsible for correct impersonation when hToken is non-null. It must have appropriate security privileges for the particular user, including TOKEN_QUERY and TOKEN_IMPERSONATE, and the user's registry hive must be currently mounted. See Access Control for further discussion of access control issues.

Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHSetKnownFolderPath to set folder locations (such as the Desktop folder) for the Default User. The Default User user profile is duplicated when any new user account is created, and includes special folders such as Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note that access to the Default User folders requires administrator privileges.

riid [in]

Type: REFIID

A reference to the IID of the interface that represents the item, usually IID_IShellItem or IID_IShellItem2.

ppv [out]

Type: void**

When this method returns, contains the interface pointer requested in riid.

Return value

Type: HRESULT

Returns S_OK if successful, or an error value otherwise, including the following:

Return codeDescription
E_INVALIDARG

Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID that is not present on the system. Not all KNOWNFOLDERID values are present on all systems. Use IKnownFolderManager::GetFolderIds to retrieve the set of KNOWNFOLDERID values for the current system.

 

Remarks

The caller of this function must have Administrator privileges. To call this function on public known folders, the caller must have Administrator privileges. For per-user known folders the caller only requires User privileges.

Some of the known folders, for example, the Documents folder, are per-user. Every user has a different path for their Documents folder. If hToken is NULL, the API tries to access the calling application's instance of the folder, which is that of the current user. If hToken is a valid user token, the API tries to impersonate the user using this token and tries to access that user's instance.

This function cannot be called on folders of type KF_CATEGORY_FIXED and KF_CATEGORY_VIRTUAL.

To call this function on a folder of type KF_CATEGORY_COMMON, the calling application must be running with elevated privileges.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Shlobj.h

Library

Shell32.lib

DLL

Shell32.dll (version 6.1 or later)

See also

IKnownFolder::GetPath
IKnownFolderManager::Redirect
SHGetKnownFolderPath
SHGetKnownFolderIDList
SHCreateItemInKnownFolder
Known Folders Sample

 

 

Community Additions

ADD
Show:
© 2014 Microsoft