Functions

Functions


This section describes the Microsoft® Windows® shell functions.

SHAddToRecentDocs
SHAppBarMessage
SHBrowseForFolder
SHChangeNotify
Shell_NotifyIcon
ShellAbout
ShellExecute
ShellExecuteEx
SHEmptyRecycleBin
SHFileOperation
SHFreeNameMappings
SHGetDataFromIDList
SHGetDesktopFolder
SHGetFileInfo
SHGetInstanceExplorer
SHGetMalloc
SHGetPathFromIDList
SHGetSettings
SHGetSpecialFolderLocation
SHGetSpecialFolderPath
SHLoadInProc
SHQueryRecycleBin

SHAddToRecentDocs

WINSHELLAPI void WINAPI SHAddToRecentDocs(
    UINT uFlags, 
    LPCVOID pv
); 

Adds a document to the shell's list of recently used documents or clears all documents from the list. The user gains access to the list through the Start menu of the Windows taskbar.

uFlags
Flag that indicates the meaning of the pv parameter. This flag can be one of the following values:
SHARD_PATH The pv parameter contains the address of a path string.
SHARD_PIDL The pv parameter contains the address of an item identifier list (PIDL) that identifies a file object. PIDLs that identify nonfile objects are not allowed.
pv
Address of a character buffer that contains the path and file name of the document, or the address of an ITEMIDLIST structure that contains an item identifier list that uniquely identifies the document. If this parameter is NULL, the function clears all documents from the list.

SHAppBarMessage

WINSHELLAPI UINT APIENTRY SHAppBarMessage(
    DWORD dwMessage, 
    PAPPBARDATA pData
); 

Sends an appbar message to the system.

dwMessage
Appbar message value to send. This parameter can be one of the following values:
ABM_ACTIVATE Notifies the system that an appbar has been activated.
ABM_GETAUTOHIDEBAR Retrieves the handle to the autohide appbar associated with a particular edge of the screen.
ABM_GETSTATE Retrieves the autohide and always-on-top states of the Windows taskbar.
ABM_GETTASKBARPOS Retrieves the bounding rectangle of the Windows taskbar.
ABM_NEW Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar.
ABM_QUERYPOS Requests a size and screen position for an appbar.
ABM_REMOVE Unregisters an appbar, removing the bar from the system's internal list.
ABM_SETAUTOHIDEBAR Registers or unregisters an autohide appbar for an edge of the screen.
ABM_SETPOS Sets the size and screen position of an appbar.
ABM_WINDOWPOSCHANGED Notifies the system when an appbar's position has changed.
pData
Address of an APPBARDATA structure. The content of the structure depends on the value set in the dwMessage parameter.

SHBrowseForFolder

WINSHELLAPI LPITEMIDLIST WINAPI SHBrowseForFolder(
    LPBROWSEINFO lpbi
); 

Displays a dialog box that enables the user to select a shell folder.

lpbi
Address of a BROWSEINFO structure that contains information used to display the dialog box.

The calling application is responsible for freeing the returned item identifier list by using the shell's task allocator.

SHChangeNotify

WINSHELLAPI void WINAPI SHChangeNotify(
    LONG wEventId, 
    UINT uFlags, 
    LPCVOID dwItem1, 
    LPCVOID dwItem2
);		

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.

wEventId
Describes the event that has occurred. Typically, only one event is specified at a time. If more than one event is specified, the values contained in the dwItem1 and dwItem2 parameters must be the same, respectively, for all specified events. This parameter can be one or more of the following values:
SHCNE_ALLEVENTS All events have occurred.
SHCNE_ASSOCCHANGED A file type association has changed. SHCNF_IDLIST must be specified in the uFlags parameter. dwItem1 and dwItem2 are not used and must be NULL.
SHCNE_ATTRIBUTES The attributes of an item or folder have changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item or folder that has changed. dwItem2 is not used and should be NULL.
SHCNE_CREATE A nonfolder item has been created. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item that was created. dwItem2 is not used and should be NULL.
SHCNE_DELETE A nonfolder item has been deleted. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item that was deleted. dwItem2 is not used and should be NULL.
SHCNE_DRIVEADD A drive has been added. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that was added. dwItem2 is not used and should be NULL.
SHCNE_DRIVEADDGUI A drive has been added and the shell should create a new window for the drive. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that was added. dwItem2 is not used and should be NULL.
SHCNE_DRIVEREMOVED A drive has been removed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that was removed. dwItem2 is not used and should be NULL.
SHCNE_EXTENDED_EVENT Not currently used.
SHCNE_FREESPACE The amount of free space on a drive has changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive on which the free space changed. dwItem2 is not used and should be NULL.
SHCNE_MEDIAINSERTED Storage media has been inserted into a drive. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that contains the new media. dwItem2 is not used and should be NULL.
SHCNE_MEDIAREMOVED Storage media has been removed from a drive. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive from which the media was removed. dwItem2 is not used and should be NULL.
SHCNE_MKDIR A folder has been created. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that was created. dwItem2 is not used and should be NULL.
SHCNE_NETSHARE A folder on the local computer is being shared via the network. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that is being shared. dwItem2 is not used and should be NULL.
SHCNE_NETUNSHARE A folder on the local computer is no longer being shared via the network. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that is no longer being shared. dwItem2 is not used and should be NULL.
SHCNE_RENAMEFOLDER The name of a folder has changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the previous PIDL or name of the folder. dwItem2 contains the new PIDL or name of the folder.
SHCNE_RENAMEITEM The name of a nonfolder item has changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the previous PIDL or name of the item. dwItem2 contains the new PIDL or name of the item.
SHCNE_RMDIR A folder has been removed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that was removed. dwItem2 is not used and should be NULL.
SHCNE_SERVERDISCONNECT The computer has disconnected from a server. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the server from which the computer was disconnected. dwItem2 is not used and should be NULL.
SHCNE_UPDATEDIR The contents of an existing folder have changed, but the folder still exists and has not been renamed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that has changed. dwItem2 is not used and should be NULL. If a folder has been created, deleted, or renamed, use SHCNE_MKDIR, SHCNE_RMDIR, or SHCNE_RENAMEFOLDER, respectively, instead.
SHCNE_UPDATEIMAGE An image in the system image list has changed. SHCNF_DWORD must be specified in uFlags. dwItem1 contains the index in the system image list that has changed. dwItem2 is not used and should be NULL.
SHCNE_UPDATEITEM An existing nonfolder item has changed, but the item still exists and has not been renamed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item that has changed. dwItem2 is not used and should be NULL. If a nonfolder item has been created, deleted, or renamed, use SHCNE_CREATE, SHCNE_DELETE, or SHCNE_RENAMEITEM, respectively, instead.

The following values specify combinations of other events:
SHCNE_DISKEVENTS Specifies a combination of all of the disk event identifiers.
SHCNE_GLOBALEVENT Specifies a combination of all of the global event identifiers.

The following value modifies other event values and cannot be used alone:
SHCNE_INTERRUPT The specified event occurred as a result of a system interrupt.

uFlags
Flags that indicate the meaning of the dwItem1 and dwItem2 parameters. The uFlags parameter must be one of the following values:
SHCNF_DWORD The dwItem1 and dwItem2 parameters are DWORD values.
SHCNF_IDLIST dwItem1 and dwItem2 are the addresses of ITEMIDLIST structures that represent the item(s) affected by the change. Each ITEMIDLIST must be relative to the desktop folder.
SHCNF_PATH dwItem1 and dwItem2 are the addresses of NULL-terminated strings that contain the full path names of the items affected by the change.
SHCNF_PRINTER dwItem1 and dwItem2 are the addresses of NULL-terminated strings that represent the friendly names of the printer(s) affected by the change.

The following flags modify other data-type flags and cannot be used by themselves:
SHCNF_FLUSH The function should not return until the notification has been delivered to all affected components.
SHCNF_FLUSHNOWAIT The function should begin delivering notifications to all affected components but should return as soon as the notification process has begun.

dwItem1
First event-dependent value.
dwItem2
Second event-dependent value.

Shell_NotifyIcon

WINSHELLAPI BOOL WINAPI Shell_NotifyIcon(
    DWORD dwMessage, 
    PNOTIFYICONDATA pnid
);	

Sends a message to the system to add, modify, or delete an icon from the taskbar status area.

dwMessage
Message value to send. This parameter can be one of these values:
NIM_ADD Adds an icon to the status area.
NIM_DELETE Deletes an icon from the status area.
NIM_MODIFY Modifies an icon in the status area.
pnid
Address of a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage.

ShellAbout

int ShellAbout (
   HWND hWnd,
   LPCTSTR szApp, 
   LPCTSTR szOtherStuff, 
   HICON hIcon
);	

Displays a ShellAbout dialog box.

hWnd
Window handle to a parent window. This parameter can be NULL.
szApp
Displays text in the title bar of the ShellAbout dialog box and on the first line of the dialog box after the text "Microsoft". If the text contains a separator (#) dividing it into two parts, the function displays the first part in the title bar and the second part on the first line after the text "Microsoft".
szOtherStuff
Displays text in the dialog box after the version and copyright information.
hIcon
Icon that the function displays in the dialog box. If this parameter is NULL, the function displays the Microsoft® Windows® or Windows NT® icon.

Note that the ShellAbout function dialog box uses text and a default icon that are specific to either Windows or Windows NT.

An example of a ShellAbout dialog box can be seen by selecting the About Program Manager command in Program Manager.

SHEmptyRecycleBin

SHSTDAPI SHEmptyRecycleBin(
    HWND hwnd, 
    LPCTSTR pszRootPath, 
    DWORD dwFlags
);		

Empties the recycle bin on the specified drive.

hwnd
Handle to the parent window of any dialog boxes that might be displayed during the operation. This parameter can be NULL.
pszRootPath
Address of a NULL-terminated string that contains the path of the root drive on which the recycle bin is located. This parameter can contain the address of a string formatted with the drive, folder, and subfolder names (c:\windows\system . . .). It can also contain an empty string or NULL. If this value is an empty string or NULL, all recycle bins on all drives will be emptied.
dwFlags
One or more of the following values:
SHERB_NOCONFIRMATION No dialog confirming the deletion of the objects will be displayed.
SHERB_NOPROGRESSUI No dialog indicating the progress will be displayed.
SHERB_NOSOUND No sound will be played when the operation is complete.

See also SHQueryRecycleBin

ShellExecute

HINSTANCE ShellExecute(
    HWND hwnd, 
    LPCTSTR lpOperation,
    LPCTSTR lpFile, 
    LPCTSTR lpParameters, 
    LPCTSTR lpDirectory,
    INT nShowCmd
);	

Opens or prints a specified file.

hwnd
Window handle to a parent window. This window receives any message boxes that an application produces. For example, an application may report an error by producing a message box.
lpOperation
Address of a null-terminated string that specifies the operation to perform. The following operation strings are valid:
"open" The function opens the file specified by the lpFile parameter. The file can be an executable file or a document file. It can also be a folder.
"print" The function prints the file specified by lpFile. The file should be a document file. If the file is an executable file, the function opens the file, as if "open" had been specified.
"explore" The function explores the folder specified by lpFile.

This parameter can be NULL. In that case, the function opens the file specified by lpFile.

lpFile
Address of a null-terminated string that specifies the file to open or print or the folder to open or explore. The function can open an executable file or a document file. The function can print a document file.
lpParameters
If the lpFile parameter specifies an executable file, lpParameters is an address to a null-terminated string that specifies the parameters to be passed to the application.
If lpFile specifies a document file, lpParameters should be NULL.
lpDirectory
Address of a null-terminated string that specifies the default directory.
nShowCmd
If lpFile specifies an executable file, nShowCmd specifies how the application is to be shown when it is opened. This parameter can be one of the following values:
SW_HIDE Hides the window and activates another window.
SW_MAXIMIZE Maximizes the specified window.
SW_MINIMIZE Minimizes the specified window and activates the next top-level window in the z-order.
SW_RESTORE Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application. An application should call ShowWindow with this flag to set the initial show state of its main window.
SW_SHOWMAXIMIZED Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE Displays the window as a minimized window. The active window remains active.
SW_SHOWNA Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

If lpFile specifies a document file, nShowCmd should be zero.

You can use this function to open or explore a shell folder. To open a folder, use either of the following calls:

ShellExecute(handle, NULL, path_to_folder, NULL, NULL, SW_SHOWNORMAL);

or

ShellExecute(handle, "open", path_to_folder, NULL, NULL, SW_SHOWNORMAL);

To explore a folder, use the following call:

ShellExecute(handle, "explore", path_to_folder, NULL, NULL, SW_SHOWNORMAL);

If lpOperation is NULL, the function opens the file specified by lpFile. If lpOperation is "open" or "explore", the function will attempt to open or explorer the folder.

To obtain information about the application that is launched as a result of calling ShellExecute, use ShellExecuteEx.

ShellExecuteEx

WINSHELLAPI BOOL WINAPI ShellExecuteEx(
    LPSHELLEXECUTEINFO lpExecInfo
);	

Performs an action on a file.

lpExecInfo
Address of a SHELLEXECUTEINFO structure that contains and receives information about the application being executed.

If the function succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to the instance handle to the application that the function started. If the function fails, hInstApp is one of the SE_ERR_ error values indicating the cause of the failure. (An instance handle will always be greater than 32 and an error value less than 32.) Note that the SE_ERR_ error values are for compatibility with the ShellExecute function; use the GetLastError function to retrieve error information.

The error values returned by GetLastError correspond to the SE_ERR_ values and may be one of the following:
ERROR_FILE_NOT_FOUND The specified file was not found.
ERROR_PATH_NOT_FOUND The specified path was not found.
ERROR_DDE_FAIL The DDE transaction failed.
ERROR_NO_ASSOCIATION There is no application associated with the given file name extension.
ERROR_ACCESS_DENIED Access to the specified file is denied.
ERROR_DLL_NOT_FOUND One of the library files necessary to run the application can't be found.
ERROR_CANCELLED The function prompted the user for the location of the application, but the user canceled the request.
ERROR_NOT_ENOUGH_MEMORY There is not enough memory to perform the specified action.
ERROR_SHARING_VIOLATION A sharing violation occurred.

SHFileOperation

WINSHELLAPI int WINAPI SHFileOperation(
    LPSHFILEOPSTRUCT lpFileOp	
);	

Copies, moves, renames, or deletes a file system object.

lpFileOp
Address of an SHFILEOPSTRUCT structure that contains information this function needs to carry out the specified operation.

SHFreeNameMappings

WINSHELLAPI void WINAPI SHFreeNameMappings(;
    HANDLE hNameMappings	
);	

Frees a file name mapping object that was retrieved by the SHFileOperation function.

hNameMappings
Handle to the file name mapping object to be freed.

SHGetDataFromIDList

HRESULT ShGetDataFromIDList(
    LPSHELLFOLDER psf,
    LPCITEMIDLIST pidl,
    int nFormat,
    PVOID pv,
    int cb
);	

Retrieves extended property data from a relative identifier list.

psf
Address of the parent IShellFolder interface.
pidl
Address of an ITEMIDLIST structure that identifies the subfolder relative to the folder specified in psf.
nFormat
Specifies the format in which the data is being requested. This must be one of the following formats:
SHGDFIL_FINDDATA Format used for file system objects. The pv parameter is the address of a WIN32_FIND_DATA structure.
SHGDFIL_NETRESOURCE Format used for network resources. The pv parameter is the address of a NETRESOURCE structure.
SHGDFIL_DESCRIPTIONID Format used for network resources. The pv parameter is the address of an SHDESCRIPTIONID structure.
pv
Address of a buffer that receives the requested data. The format of this buffer is determined by nFormat.

If nFormat is SHGDFIL_NETRESOURCE, there are two possible cases. If the buffer is large enough, the net resource's string information (fields for the network name, local name, provider, and comments) will be placed into the buffer. If the buffer is not large enough, only the net resource structure will be placed into the buffer and the string information pointers will be NULL.

cb
Size of the buffer at pv, in bytes.

E_INVALIDARG is returned if the psf, pidl, pv, or cb parameters do not match the nFormat parameter, or if nFormat is not one of the specific SHGDFIL_ values shown above.

SHGetDesktopFolder

WINSHELLAPI HRESULT WINAPI SHGetDesktopFolder(
    LPSHELLFOLDER *ppshf	
);	

Retrieves the IShellFolder interface for the desktop folder, which is the root of the shell's namespace.

ppshf
Address that receives an IShellFolder interface pointer for the desktop folder. The calling application is responsible for eventually freeing the interface by calling its Release method.

SHGetFileInfo

WINSHELLAPI DWORD WINAPI SHGetFileInfo(
    LPCTSTR pszPath, 	
    DWORD dwFileAttributes, 	
    SHFILEINFO FAR *psfi, 	
    UINT cbFileInfo, 	
    UINT uFlags	
);	

Retrieves information about an object in the file system, such as a file, a folder, a directory, or a drive root.

pszPath
Address of a buffer that contains the path and file name. Both absolute and relative paths are valid.

If the uFlags parameter includes the SHGFI_PIDL flag, this parameter must be the address of an ITEMIDLIST (PIDL) structure that contains the list of item identifiers that uniquely identifies the file within the shell's namespace. The PIDL must be a fully qualified PIDL. Relative PIDLs are not allowed.

If the uFlags parameter includes the SHGFI_USEFILEATTRIBUTES flag, this parameter does not have to be a valid file name. The function will proceed as if the file exists with the specified name and with the file attributes passed in the dwFileAttributes parameter. This allows you to obtain information about a file type by passing just the extension for pszPath and passing FILE_ATTRIBUTE_NORMAL in dwFileAttributes.

This string can use either short (the 8.3 form) or long file names.

dwFileAttributes
Combination of one or more file attribute flags (FILE_ATTRIBUTE_ values). If uFlags does not include the SHGFI_USEFILEATTRIBUTES flag, this parameter is ignored.
psfi
Address of a SHFILEINFO structure to receive the file information.
cbFileInfo
Size, in bytes, of the SHFILEINFO structure pointed to by the psfi parameter.
uFlags
Flags that specify the file information to retrieve. This parameter can be a combination of the following values:
SHGFI_ATTR_SPECIFIED Modifies SHGFI_ATTRIBUTES. Indicates that the dwAttributes member of the SHFILEINFO structure at psfi contains the specific attributes that are desired. These attributes will be passed to IShellFolder::GetAttributesOf. If this flag is not specified, 0xFFFFFFFF will be passed to GetAttributesOf, requesting all attributes. This flag cannot be specified with the SHGFI_ICON flag.
SHGFI_ATTRIBUTES Retrieve the item attributes. The attributes are copied to the dwAttributes member of the structure specified in the psfi parameter. These are the same attributes that are obtained from IShellFolder::GetAttributesOf.
SHGFI_DISPLAYNAME Retrieve the display name for the file. The name is copied to the szDisplayName member of the structure specified in psfi. The returned display name uses the long file name, if there is one, rather than the 8.3 form of the file name.
SHGFI_EXETYPE Retrieve the type of the executable file if pszPath identifies an executable file. This flag cannot be specified with any other flags.
SHGFI_ICON Retrieve the handle to the icon that represents the file and the index of the icon within the system image list. The handle is copied to the hIcon member of the structure specified by psfi, and the index is copied to the iIcon member. The return value is the handle to the system image list.
SHGFI_ICONLOCATION Retrieve the name of the file that contains the icon representing the file. The name is copied to the szDisplayName member of the structure specified in psfi.
SHGFI_LARGEICON Modify SHGFI_ICON, causing the function to retrieve the file's large icon.
SHGFI_LINKOVERLAY Modify SHGFI_ICON, causing the function to add the link overlay to the file's icon.
SHGFI_OPENICON Modify SHGFI_ICON, causing the function to retrieve the file's open icon. A container object displays an open icon to indicate that the container is open.
SHGFI_PIDL Indicate that pszPath is the address of an ITEMIDLIST structure rather than a path name.
SHGFI_SELECTED Modify SHGFI_ICON, causing the function to blend the file's icon with the system highlight color.
SHGFI_SHELLICONSIZE Modify SHGFI_ICON, causing the function to retrieve a shell-sized icon. If this flag is not specified the function sizes the icon according to the system metric values.
SHGFI_SMALLICON Modify SHGFI_ICON, causing the function to retrieve the file's small icon.
SHGFI_SYSICONINDEX Retrieve the index of the icon within the system image list. The index is copied to the iIcon member of the structure specified by psfi. The return value is the handle to the system image list.
SHGFI_TYPENAME Retrieve the string that describes the file's type. The string is copied to the szTypeName member of the structure specified in psfi.
SHGFI_USEFILEATTRIBUTES Indicates that the function should not attempt to access the file specified by pszPath. Rather, it should act as if the file specified by pszPath exists with the file attributes passed in dwFileAttributes. This flag cannot be combined with the SHGFI_ATTRIBUTES, SHGFI_EXETYPE, or SHGFI_PIDL flags.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.