Shell Functions

[This function is no longer implemented.]

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.

CIShutdown

Shuts down the content indexer and closes all open catalogs.

Note  This function is not supported as of Windows 8.
 

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.

DllGetVersion

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 an 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.