
This section describes the Microsoft® Windows® shell functions.
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.
| 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. |
WINSHELLAPI UINT APIENTRY SHAppBarMessage(
DWORD dwMessage,
PAPPBARDATA pData
);
Sends an appbar message to the system.
| 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. |
WINSHELLAPI LPITEMIDLIST WINAPI SHBrowseForFolder(
LPBROWSEINFO lpbi
);
Displays a dialog box that enables the user to select a shell folder.
The calling application is responsible for freeing the returned item identifier list by using the shell's task allocator.
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.
| 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. |
| 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. |
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.
| 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. |
int ShellAbout ( HWND hWnd, LPCTSTR szApp, LPCTSTR szOtherStuff, HICON hIcon );
Displays a ShellAbout dialog box.
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.
SHSTDAPI SHEmptyRecycleBin(
HWND hwnd,
LPCTSTR pszRootPath,
DWORD dwFlags
);
Empties the recycle bin on the specified drive.
| 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
HINSTANCE ShellExecute(
HWND hwnd,
LPCTSTR lpOperation,
LPCTSTR lpFile,
LPCTSTR lpParameters,
LPCTSTR lpDirectory,
INT nShowCmd
);
Opens or prints a specified file.
| 0 | The operating system is out of memory or resources. |
| ERROR_FILE_NOT_FOUND | The specified file was not found. |
| ERROR_PATH_NOT_FOUND | The specified path was not found. |
| ERROR_BAD_FORMAT | The .exe file is invalid (non-Win32® .exe or error in .exe image). |
| SE_ERR_ACCESSDENIED | The operating system denied access to the specified file. |
| SE_ERR_ASSOCINCOMPLETE | The file name association is incomplete or invalid. |
| SE_ERR_DDEBUSY | The DDE transaction could not be completed because other DDE transactions were being processed. |
| SE_ERR_DDEFAIL | The DDE transaction failed. |
| SE_ERR_DDETIMEOUT | The DDE transaction could not be completed because the request timed out. |
| SE_ERR_DLLNOTFOUND | The specified dynamic-link library was not found. |
| SE_ERR_FNF | The specified file was not found. |
| SE_ERR_NOASSOC | There is no application associated with the given file name extension. |
| SE_ERR_OOM | There was not enough memory to complete the operation. |
| SE_ERR_PNF | The specified path was not found. |
| SE_ERR_SHARE | A sharing violation occurred. |
| "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.
| 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.
WINSHELLAPI BOOL WINAPI ShellExecuteEx(
LPSHELLEXECUTEINFO lpExecInfo
);
Performs an action on a file.
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. |
WINSHELLAPI int WINAPI SHFileOperation(
LPSHFILEOPSTRUCT lpFileOp
);
Copies, moves, renames, or deletes a file system object.
WINSHELLAPI void WINAPI SHFreeNameMappings(;
HANDLE hNameMappings
);
Frees a file name mapping object that was retrieved by the SHFileOperation function.
HRESULT ShGetDataFromIDList(
LPSHELLFOLDER psf,
LPCITEMIDLIST pidl,
int nFormat,
PVOID pv,
int cb
);
Retrieves extended property data from a relative identifier list.
| 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. |
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.
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.
WINSHELLAPI HRESULT WINAPI SHGetDesktopFolder(
LPSHELLFOLDER *ppshf
);
Retrieves the IShellFolder interface for the desktop folder, which is the root of the shell's namespace.
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.
| Value | Executable File Type |
| 0 | Nonexecutable file or an error condition |
| LOWORD = NE or PE and HIWORD = 3.0, 3.5, or 4.0 | Windows application |
| LOWORD = MZ and HIWORD = 0 | MS-DOS .exe, .com, or .bat file |
| LOWORD = PE and HIWORD = 0 | Win32 console application |
If uFlags contains SHGFI_SYSICONINDEX, the return value is the handle to the system image list that contains the large icon images. If SHGFI_SMALLICON is included with SHGFI_SYSICONINDEX, the return value is the handle to the image list that contains the small icon images.
If uFlags does not contain SHGFI_EXETYPE or SHGFI_SYSICONINDEX, the return value is nonzero if successful, or zero otherwise.
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.
| 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.