Shell Functions

This section describes the Windows Shell functions.

In this section

Topic Description
Intsafe.h Functions
Library Functions
Path Functions
AssocCreateForClasses
Retrieves an object that implements an IQueryAssociations interface.
AssocGetDetailsOfPropKey
Retrieves the value for a given property key using the file association information provided by the Namespace Extensions.
CDefFolderMenu_Create2
Creates a context menu for a selected group of file folder objects.
CommandLineToArgvW
Parses a Unicode command line string and returns an array of pointers to the command line arguments, along with a count of such arguments, in a way that is similar to the standard C run-time argv and argc values.
APPLET_PROC
Serves as the entry point for a Control Panel application. This is a library-defined callback function.
CreateAppContainerProfile
Creates a per-user, per-app profile for Windows Store apps.
CreateEnvironmentBlock
Retrieves the environment variables for the specified user. This block can then be passed to the CreateProcessAsUser function.
CreateMRUListW
Creates a new most recently used (MRU) list.
CreateProfile
Creates a new user profile.
DefScreenSaverProc
Provides default processing for any messages that a screen saver application does not process.
DefSubclassProc
Calls the next handler in a window's subclass chain. The last handler in the subclass chain calls the original window procedure for the window.
DeleteAppContainerProfile
Deletes the specified per-user, per-app profile.
DeleteProfile
Deletes the user profile and all user-related settings from the specified computer. The caller must have administrative privileges to delete a user's profile.
DestroyEnvironmentBlock
Frees environment variables created by the CreateEnvironmentBlock function.
DeriveAppContainerSidFromAppContainerName
Gets the SID of the specified profile.
DeriveRestrictedAppContainerSidFromAppContainerSidAndRestrictedName
DeriveRestrictedAppContainerSidFromAppContainerSidAndRestrictedName is reserved for future use.
DLLGETVERSIONPROC
Implemented by many of the Windows Shell DLLs to allow applications to obtain DLL-specific version information.
DragAcceptFiles
Registers whether a window accepts dropped files.
DragFinish
Releases memory that the system allocated for use in transferring file names to the application.
DragQueryFile
Retrieves the names of dropped files that result from a successful drag-and-drop operation.
DragQueryPoint
Retrieves the position of the mouse pointer at the time a file was dropped during a drag-and-drop operation.
DuplicateIcon
Creates a duplicate of a specified icon.
ExpandEnvironmentStringsForUser
Expands the source string by using the environment block established for the specified user.
ExtractAssociatedIcon
Gets a handle to an icon stored as a resource in a file or an icon stored in a file's associated executable file.
ExtractIcon
Gets a handle to an icon from the specified executable file, DLL, or icon file.
To retrieve an array of handles to large or small icons, use the ExtractIconEx function.
ExtractIconEx
The ExtractIconEx function creates an array of handles to large or small icons extracted from the specified executable file, DLL, or icon file.
FileIconInit
Initializes or reinitializes the system image list.
FindExecutable
Retrieves the name of and handle to the executable (.exe) file associated with a specific document file.
FreeConfirmConflictItem
Frees the resources that have been allocated for a CONFIRM_CONFLICT_ITEM structure.
FreeIDListArray
Frees the memory used by a pointer to an item identifier list (PIDL) list array.
FreeIDListArrayChild
Releases the memory space for the array of pointers to child item IDs. This releases both the PITEMID_CHILDs within the array and the array itself.
FreeIDListArrayFull
Releases the memory space for the PIDL array. This releases both the PIDLIST_ABSOLUTEs within the array and the array itself.
FreeKnownFolderDefinitionFields
Frees the allocated fields in the result from IKnownFolder::GetFolderDefinition.
FreeMRUList
Frees the handle associated with the MRU list and writes cached data to the registry.
GetAllUsersProfileDirectory
Retrieves the path to the root of the directory that contains program data shared by all users.
GetAppContainerFolderPath
Gets the path of the local app data folder for the specified app container.
GetAppContainerRegistryLocation
Gets the location of the registry storage associated with an app container.
GetContractDelegateWindow
Retrieves a window that has been set as a delegate for an app's primary foreground window for the purpose of associating the delegate window with the app's contracts. Use this function if you are a developer writing a Windows Store app in native C++.
GetCurrentProcessExplicitAppUserModelID
Retrieves the application-defined, explicit Application User Model ID (AppUserModelID) for the current process.
GetDefaultUserProfileDirectory
Retrieves the path to the root of the default user's profile.
GetDpiForShellUiComponent
Retrieves the dots per inch (dpi) occupied by a SHELL_UI_COMPONENT based on the current scale factor and PROCESS_DPI_AWARENESS.
GetMenuContextHelpId
Retrieves the Help context identifier associated with the specified menu.
GetProfilesDirectory
Retrieves the path to the root directory where user profiles are stored.
GetProfileType
Retrieves the type of profile loaded for the current user.
GetScaleFactorForDevice
Gets the preferred scale factor for a display device.
GetScaleFactorForMonitor
Gets the scale factor of a specific monitor. This function replaces GetScaleFactorForDevice.
GetUserProfileDirectory
Retrieves the path to the root directory of the specified user's profile.
GetWindowContextHelpId
Retrieves the Help context identifier, if any, associated with the specified window.
GetWindowSubclass
Retrieves the reference data for the specified window subclass callback.
IDListContainerIsConsistent
Verifies that the container structure of an IDList is valid.
ILAppendID
Appends or prepends an SHITEMID structure to an ITEMIDLIST structure.
ILClone
Clones an ITEMIDLIST structure.
ILCloneChild
Clones a child ITEMIDLIST structure.
ILCloneFirst
Clones the first SHITEMID structure in an ITEMIDLIST structure.
ILCloneFull
Clones a full, or absolute, ITEMIDLIST structure.
ILCombine
Combines two ITEMIDLIST structures.
ILCreateFromPath
Returns the ITEMIDLIST structure associated with a specified file path.
ILFindChild
Determines whether a specified ITEMIDLIST structure is the child of another ITEMIDLIST structure.
ILFindLastID
Returns a pointer to the last SHITEMID structure in an ITEMIDLIST structure.
ILFree
Frees an ITEMIDLIST structure allocated by the Shell.
ILGetNext
Retrieves the next SHITEMID structure in an ITEMIDLIST structure.
ILGetSize
Returns the size, in bytes, of an ITEMIDLIST structure.
ILIsAligned
Verifies whether a constant ITEMIDLIST is aligned on a pointer boundary, which is a DWORD on 32-bit architectures and a QWORD on 64-bit architectures.
ILIsChild
Verifies whether a PIDL is a child PIDL, which is a PIDL with exactly one SHITEMID.
ILIsEmpty
Verifies whether an ITEMIDLIST structure is empty.
ILIsEqual
Tests whether two ITEMIDLIST structures are equal in a binary comparison.
ILIsParent
Tests whether an ITEMIDLIST structure is the parent of another ITEMIDLIST structure.
ILNext(PCUIDLIST_RELATIVE)
Retrieves the next SHITEMID structure in an ITEMIDLIST structure.
ILNext(PUIDLIST_RELATIVE)
Retrieves the next SHITEMID structure in an ITEMIDLIST structure.
ILRemoveLastID
Removes the last SHITEMID structure from an ITEMIDLIST structure.
ILSaveToStream
Saves an ITEMIDLIST structure to a stream.
ILSkip(PCUIDLIST_RELATIVE, UINT)
Skips a given number of bytes in a constant, unaligned, relative ITEMIDLIST structure.
ILSkip(PUIDLIST_RELATIVE, UINT)
Skips a given number of bytes in an unaligned, relative ITEMIDLIST structure.
InetIsOffline
Determines whether the system is connected to the Internet.
InitNetworkAddressControl
Initializes the network address control window class.
LoadUserProfile
Loads the specified user's profile. The profile can be a local user profile or a roaming user profile.
MIMEAssociationDialog
Runs the unregistered MIME content type dialog box.
Note: Windows XP Service Pack 2 (SP2) or later: This function is no longer supported.
PathMakeUniqueName
Creates a unique path name from a template.
PathYetAnotherMakeUniqueName
Creates a unique filename based on an existing filename.
RegisterAppStateChangeNotification
Enables an app to register a callback function through which it can be notified that its library is going into or coming out of a suspended state. The app can use this information to perform any necessary operations, such as preserving state, that should be performed at that point.
RegisterDialogClasses
Registers any nonstandard window classes required by a screen saver's configuration dialog box.
RegisterScaleChangeEvent
Registers for an event that is triggered when the scale has possibly changed. This function replaces RegisterScaleChangeNotifications.
RegisterScaleChangeNotifications
Registers a window to receive callbacks when scaling information changes.
Note: This function is not supported as of Windows 8.1. Use RegisterScaleChangeEvent instead.
RemoveWindowSubclass
Removes a subclass callback from a window.
RevokeScaleChangeNotifications
Revokes the registration of a window, preventing it from receiving callbacks when scaling information changes.
Note: This function is not supported as of Windows 8.1. Use UnregisterScaleChangeEvent instead.
ScreenSaverConfigureDialog
Receives messages sent to a screen saver's configuration dialog box. A screen saver that allows user configuration must define this function.
ScreenSaverProc
Receives messages sent to the specified screen saver window.
SetContractDelegateWindow
Associates an app window other than the primary foreground window with an app's contracts. Use this function if you are a developer writing a Windows Store app in native C++.
SetCurrentProcessExplicitAppUserModelID
Specifies a unique application-defined AppUserModelID that identifies the current process to the taskbar. This identifier allows an application to group its associated processes and windows under a single taskbar button.
SetMenuContextHelpId
Associates a Help context identifier with a menu.
SetWindowContextHelpId
Associates a Help context identifier with the specified window.
SetWindowSubclass
Installs or updates a window subclass callback.
SHAddToRecentDocs
Notifies the system that an item has been accessed, for the purposes of tracking those items used most recently and most frequently. This function can also be used to clear all usage data.
SHAppBarMessage
Sends an appbar message to the system.
SHAssocEnumHandlers
Returns an enumeration object for a specified set of file name extension handlers.
SHAssocEnumHandlersForProtocolByApplication
Gets an enumeration interface that provides access to handlers associated with a given protocol.
SHBindToFolderIDListParent
Given a Shell namespace item specified in the form of a folder, and an item identifier list relative to that folder, this function binds to the parent of the namespace item and optionally returns a pointer to the final component of the item identifier list.
SHBindToFolderIDListParentEx
Extends the SHBindToFolderIDListParent function by allowing the caller to specify a bind context.
SHBindToObject
Retrieves and binds to a specified object by using the Shell namespace IShellFolder::BindToObject method.
SHBindToParent
Takes a pointer to a fully qualified item identifier list (PIDL), and returns a specified interface pointer on the parent object.
SHBrowseForFolder
Displays a dialog box that enables the user to select a Shell folder.
SHChangeNotification_Lock
Locks the shared memory associated with a Shell change notification event.
SHChangeNotification_Unlock
Unlocks shared memory for a change notification.
SHChangeNotify
Notifies the system of an event that an application has performed. An application should use this function if it performs an action that may affect the Shell.
SHChangeNotifyDeregister
Unregisters the client's window process from receiving SHChangeNotify messages.
SHChangeNotifyRegister
Registers a window to receive notifications from the file system or Shell, if the file system supports notifications.
SHChangeNotifyRegisterThread
Enables asynchronous register and deregister of a thread.
SHCreateAssociationRegistration
Creates an IApplicationAssociationRegistration object based on the stock implementation of the interface provided by Windows.
SHCreateDataObject
Creates a data object in a parent folder.
SHCreateDefaultContextMenu
Creates an object that represents the Shell's default context menu implementation.
SHCreateDefaultExtractIcon
Creates a standard icon extractor, whose defaults can be further configured via the IDefaultExtractIconInit interface.
SHCreateDefaultPropertiesOp
Creates a file operation that sets the default properties on the Shell item that have not already been set.
SHCreateItemFromIDList
Creates and initializes a Shell item object from a PIDL. The resulting shell item object supports the IShellItem interface.
SHCreateItemFromParsingName
Creates and initializes a Shell item object from a parsing name.
SHCreateItemFromRelativeName
Creates and initializes a Shell item object from a relative parsing name.
SHCreateItemInKnownFolder
Creates a Shell item object for a single file that exists inside a known folder.
SHCreateItemWithParent
Create a Shell item, given a parent folder and a child item ID.
SHCreateShellFolderView
Creates a new instance of the default Shell folder view object (DefView).
SHCreateShellFolderViewEx
Creates a new instance of the default Shell folder view object. It is recommended that you use SHCreateShellFolderView rather than this function.
SHCreateShellItem
Creates an IShellItem object.
Note: It is recommended that you use SHCreateItemWithParent or SHCreateItemFromIDList instead of this function.
SHCreateShellItemArray
Creates a Shell item array object.
SHCreateShellItemArrayFromDataObject
Creates a Shell item array object from a data object.
SHCreateShellItemArrayFromIDLists
Creates a Shell item array object from a list of ITEMIDLIST structures.
SHCreateShellItemArrayFromShellItem
Creates an array of one element from a single Shell item.
SHDefExtractIcon
Provides a default handler to extract an icon from a file.
SHDoDragDrop
Executes a drag-and-drop operation. Supports drag source creation on demand, as well as drag images.
Shell_NotifyIcon
Sends a message to the taskbar's status area.
Shell_NotifyIconGetRect
Gets the screen coordinates of the bounding rectangle of a notification icon.
ShellAbout
Displays a ShellAbout dialog box.
ShellDDEInit
Registers the Shell Dynamic Data Exchange (DDE) services in the current process, notifying the system that the current process wishes to host DDE objects.
ShellExecute
Performs an operation on a specified file.
ShellExecuteEx
Performs an operation on a specified file.
SHEmptyRecycleBin
Empties the Recycle Bin on the specified drive.
SHEnumerateUnreadMailAccounts
Enumerates the user accounts that have unread email.
SHEvaluateSystemCommandTemplate
Enforces strict validation of parameters used in a call to CreateProcess or ShellExecute.
SHFileOperation
Copies, moves, renames, or deletes a file system object. This function has been replaced in Windows Vista by IFileOperation.
SHFreeNameMappings
Frees a file name mapping object that was retrieved by the SHFileOperation function.
SHGetDataFromIDList
Retrieves extended property data from a relative identifier list.
SHGetDesktopFolder
Retrieves the IShellFolder interface for the desktop folder, which is the root of the Shell's namespace.
SHGetDiskFreeSpaceEx
Retrieves disk space information for a disk volume.
SHGetDriveMedia
Returns the type of media that is in the given drive.
SHGetFileInfo
Retrieves information about an object in the file system, such as a file, folder, directory, or drive root.
SHGetFolderPathEx
Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This extends SHGetKnownFolderPath by allowing you to set the initial size of the string buffer.
SHGetIconOverlayIndex
Returns the index of the overlay icon in the system image list.
SHGetIDListFromObject
Retrieves the PIDL of an object.
SHGetImageList
Retrieves an image list.
SHGetInstanceExplorer
Retrieves an interface that allows hosted Shell extensions and other components to prevent their host process from closing prematurely. The host process is typically Windows Explorer or Windows Internet Explorer, but this function can also be used by other applications.
SHGetItemFromDataObject
Creates an IShellItem or related object based on an item specified by an IDataObject.
SHGetItemFromObject
Retrieves an IShellItem for an object.
SHGetKnownFolderIDList
Retrieves the path of a known folder as an ITEMIDLIST structure.
SHGetKnownFolderItem
Retrieves an IShellItem object that represents a known folder.
SHGetKnownFolderPath
Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID.
SHGetLocalizedName
Retrieves the localized name of a file in a Shell folder.
SHGetNameFromIDList
Retrieves the display name of an item identified by its IDList.
SHGetNameFromPropertyKey
Retrieves the property's canonical name given its PROPERTYKEY.
SHGetNewLinkInfo
Creates a name for a new shortcut based on the shortcut's proposed target. This function does not create the shortcut, just the name.
SHGetPathFromIDList
Converts an item identifier list to a file system path.
SHGetPathFromIDListEx
Converts an item identifier list to a file system path. This function extends SHGetPathFromIDList by allowing you to set the initial size of the string buffer and declare the options below.
SHGetSettings
Retrieves the current Shell option settings.
SHGetStockIconInfo
Retrieves information about system-defined Shell icons.
SHGetTemporaryPropertyForItem
Retrieves the temporary property for the given item. A temporary property is a read/write store that holds properties only for the lifetime of the IShellItem object, rather than being persisted back into the item.
SHGetUnreadMailCount
Retrieves a specified user's unread message count for any or all email accounts.
SHIsFileAvailableOffline
Determines whether a file or folder is available for offline use. This function also determines whether the file would be opened from the network, from the local Offline Files cache, or from both locations.
SHLoadInProc
Creates an instance of the specified object class from within the context of the Shell's process.
Windows Vista and later: This function has been disabled and returns E_NOTIMPL.
SHLoadNonloadedIconOverlayIdentifiers
Signals the Shell that during the next operation requiring overlay information, it should load icon overlay identifiers that either failed creation or were not present for creation at startup. Identifiers that have already been loaded are not affected.
SHLocalStrDup
Makes a copy of a string in newly allocated memory.
SHMultiFileProperties
Displays a merged property sheet for a set of files. Property values common to all the files are shown while those that differ display the string (multiple values).
SHOpenFolderAndSelectItems
Opens a Windows Explorer window with specified items in a particular folder selected.
SHOpenWithDialog
Displays the Open With dialog box.
ShowShareFolderUI
Displays the Folder Sharing tab on the properties sheet for the specified folder.
SHParseDisplayName
Translates a Shell namespace object's display name into an item identifier list and returns the attributes of the object. This function is the preferred method to convert a string to a PIDL.
SHPathPrepareForWrite
Checks to see if the path exists. This includes remounting mapped network drives, prompting for ejectable media to be reinserted, creating the paths, prompting for the media to be formatted, and providing the appropriate user interfaces, if necessary. Read/write permissions for the medium are not checked.
SHQueryRecycleBin
Retrieves the size of the Recycle Bin and the number of items in it, for a specified drive.
SHQueryUserNotificationState
Checks the state of the computer for the current user to determine whether sending a notification is appropriate.
SHRemoveLocalizedName
Removes the localized name of a file in a Shell folder.
SHRunControlPanel
Opens a Control Panel item.
Note: This function is not supported as of Windows Vista
SHSetDefaultProperties
Applies the default set of properties on a Shell item.
SHSetInstanceExplorer
Provides an interface that allows hosted Shell extensions and other components to prevent their host process from closing prematurely. The host process is typically Windows Explorer or Internet Explorer, but this function can also be used by other applications.
SHSetKnownFolderPath
Redirects a known folder to a new location.
SHSetLocalizedName
Sets the localized name of a file in a Shell folder.
SHSetTemporaryPropertyForItem
Sets a temporary property for the specified item. A temporary property is kept in a read/write store that holds properties only for the lifetime of the IShellItem object, instead of writing them back into the item.
SHSetUnreadMailCount
Stores the current user's unread message count for a specified email account in the registry.
SHTestTokenMembership
Uses CheckTokenMembership to test whether the given token is a member of the local group with the specified RID.
SHUpdateImage
Notifies the Shell that an image in the system image list has changed.
SoftwareUpdateMessageBox
Displays a standard message box that can be used to notify a user that an application has been updated.
StgMakeUniqueName
Creates a unique name for a stream or storage object from a template.
StrStrNIW
Finds the first occurrence of a substring within a string. The comparison is case-insensitive.
StrStrNW
Finds the first occurrence of a substring within a string. The comparison is case-sensitive.
TranslateURL
Applies common translations to a given URL string, creating a new URL string.
UnloadUserProfile
Unloads a user's profile that was loaded by the LoadUserProfile function. The caller must have administrative privileges on the computer. For more information, see the Remarks section of the LoadUserProfile function.
UnregisterAppStateChangeNotification
Cancels a change notification registered through RegisterAppStateChangeNotification.
UnregisterScaleChangeEvent
Unregisters for the scale change event registered through RegisterScaleChangeEvent. This function replaces RevokeScaleChangeNotifications.
URLAssociationDialog
Invokes the unregistered URL protocol dialog box. This dialog box allows the user to select an application to associate with a previously unknown protocol.
Note: Windows XP SP2 or later: This function is no longer supported.
WinExecError
Retrieves the error value generated if the WinExec function cannot run a specified application.
WinHelp
Launches Windows Help (Winhelp.exe) and passes additional data that indicates the nature of the help requested by the application.