KNOWNFOLDER_DEFINITION structure (shobjidl_core.h)
Defines the specifics of a known folder.
Syntax
typedef struct KNOWNFOLDER_DEFINITION {
KF_CATEGORY category;
LPWSTR pszName;
LPWSTR pszDescription;
KNOWNFOLDERID fidParent;
LPWSTR pszRelativePath;
LPWSTR pszParsingName;
LPWSTR pszTooltip;
LPWSTR pszLocalizedName;
LPWSTR pszIcon;
LPWSTR pszSecurity;
DWORD dwAttributes;
KF_DEFINITION_FLAGS kfdFlags;
FOLDERTYPEID ftidType;
} KNOWNFOLDER_DEFINITION;
Members
category
Type: KF_CATEGORY
A single value from the KF_CATEGORY constants that classifies the folder as virtual, fixed, common, or per-user.
pszName
Type: LPWSTR
A pointer to the non-localized, canonical name for the known folder, stored as a null-terminated Unicode string. If this folder is a common or per-user folder, this value is also used as the value name of the "User Shell Folders" registry settings. This name is meant to be a unique, human-readable name. Third parties are recommended to follow the format Company.Application.Name. The name given here should not be confused with the display name.
pszDescription
Type: LPWSTR
A pointer to a short description of the known folder, stored as a null-terminated Unicode string. This description should include the folder's purpose and usage.
fidParent
Type: KNOWNFOLDERID
A KNOWNFOLDERID value that names another known folder to serve as the parent folder. Applies to common and per-user folders only. This value is used in conjunction with pszRelativePath. See Remarks for more details.
This value is optional if no value is provided for pszRelativePath.
pszRelativePath
Type: LPWSTR
Optional. A pointer to a path relative to the parent folder specified in fidParent. This is a null-terminated Unicode string, refers to the physical file system path, and is not localized. Applies to common and per-user folders only. See Remarks for more details.
pszParsingName
Type: LPWSTR
A pointer to the Shell namespace folder path of the folder, stored as a null-terminated Unicode string. Applies to virtual folders only. For example, Control Panel has a parsing name of ::%CLSID_MyComputer%::%CLSID_ControlPanel%.
pszTooltip
Type: LPWSTR
Optional. A pointer to the default tooltip resource used for this known folder when it is created. This is a null-terminated Unicode string in this form:
Module name, Resource ID
For example, @%_SYS_MOD_PATH%,-12688 is the tooltip for Common Pictures. When the folder is created, this string is stored in that folder's copy of Desktop.ini. It can be changed later by other Shell APIs. This resource might be localized.
This information is not required for virtual folders.
pszLocalizedName
Type: LPWSTR
Optional. A pointer to the default localized name resource used when the folder is created. This is a null-terminated Unicode string in this form:
Module name, Resource ID
When the folder is created, this string is stored in that folder's copy of Desktop.ini. It can be changed later by other Shell APIs.
This information is not required for virtual folders.
pszIcon
Type: LPWSTR
Optional. A pointer to the default icon resource used when the folder is created. This is a null-terminated Unicode string in this form:
Module name, Resource ID
When the folder is created, this string is stored in that folder's copy of Desktop.ini. It can be changed later by other Shell APIs.
This information is not required for virtual folders.
pszSecurity
Type: LPWSTR
Optional. A pointer to a Security Descriptor Definition Language format string. This is a null-terminated Unicode string that describes the default security descriptor that the folder receives when it is created. If this parameter is NULL, the new folder inherits the security descriptor of its parent. This is particularly useful for common folders that are accessed by all users.
dwAttributes
Type: DWORD
Optional. Default file system attributes given to the folder when it is created. For example, the file could be hidden and read-only (FILE_ATTRIBUTE_HIDDEN and FILE_ATTRIBUTE_READONLY). For a complete list of possible values, see the dwFlagsAndAttributes parameter of the CreateFile function. Set to -1 if not needed.
kfdFlags
Type: KF_DEFINITION_FLAGS
Optional. One of more values from the KF_DEFINITION_FLAGS enumeration that allow you to restrict redirection, allow PC-to-PC roaming, and control the time at which the known folder is created. Set to 0 if not needed.
ftidType
Type: FOLDERTYPEID
One of the FOLDERTYPEID values that identifies the known folder type based on its contents (such as documents, music, or photographs). This value is a GUID.
Remarks
The fidParent and pszRelativePath values work together. For example, suppose you are defining a folder called MyNewFolder and want to create that folder as ...<Username>\AppData\Local\MyApp\MyNewFolder. Provide FOLDERID_LocalAppData in fidParent to represent ...<Username>\AppData\Local. Provide "\MyApp\MyNewFolder" in pszRelativePath.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Header | shobjidl_core.h (include Shobjidl.h) |
See also
IKnownFolder::GetFolderDefinition