Java Native Access Platform 5.14.0 · com.sun.jna.platform.win32.Shell32

Modifier and Type	Field and Description
public static final Shell32	INSTANCE The instance
public static final int	SEE_MASK_FLAG_NO_UI Do not display an error message box if an error occurs.
public static final int	SEE_MASK_NOCLOSEPROCESS SEE_MASK_NOCLOSEPROCESS (0x00000040) Use to indicate that the hProcess member receives the process handle.
public static final int	SHERB_NOCONFIRMATION No dialog box confirming the deletion of the objects will be displayed.
public static final int	SHERB_NOPROGRESSUI No dialog box indicating the progress will be displayed.
public static final int	SHERB_NOSOUND No sound will be played when the operation is complete.

Method Summary

Modifier and Type	Method and Description
public Pointer	Returns: A pointer to an array of `LPWSTR` values, similar to `argv`. If the function fails, the return value is `null`. To get extended error information, call `Kernel32#GetLastError`. CommandLineToArgvW allocates a block of contiguous memory for pointers to the argument strings, and for the argument strings themselves; the calling application must free the memory used by the argument list when it is no longer needed. To free the memory, use a single call to the `Kernel32#LocalFree` function. CommandLineToArgvW(WString A Unicode string that contains the full command line. If this parameter is an empty string the function returns the path to the current executable file. lpCmdLine, IntByReference Pointer to an `int` that receives the number of array elements returned, similar to `argc`. pNumArgs) 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.
public int	Returns: Type: UINT If the nIconIndex parameter is -1, the phiconLarge parameter is NULL, and the phiconSmall parameter is NULL, then the return value is the number of icons contained in the specified file. Otherwise, the return value is the number of icons successfully extracted from the file. ExtractIconEx(String Type: LPCTSTR The name of an executable file, DLL, or icon file from which icons will be extracted. lpszFile, int Type: int The zero-based index of the first icon to extract. For example, if this value is zero, the function extracts the first icon in the specified file. If this value is -1 and phiconLarge and phiconSmall are both NULL, the function returns the total number of icons in the specified file. If the file is an executable file or DLL, the return value is the number of RT_GROUP_ICON resources. If the file is an .ico file, the return value is 1. If this value is a negative number and either phiconLarge or phiconSmall is not NULL, the function begins by extracting the icon whose resource identifier is equal to the absolute value of nIconIndex. For example, use -3 to extract the icon whose resource identifier is 3. nIconIndex, WinDef.HICON[] Type: HICON* An array of icon handles that receives handles to the large icons extracted from the file. If this parameter is NULL, no large icons are extracted from the file. phiconLarge, WinDef.HICON[] Type: HICON* An array of icon handles that receives handles to the small icons extracted from the file. If this parameter is NULL, no small icons are extracted from the file. phiconSmall, int Type: UINT The number of icons to be extracted from the file. nIcons)
public WinNT.HRESULT	Returns: If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. GetCurrentProcessExplicitAppUserModelID(PointerByReference A pointer that receives the address of the AppUserModelID assigned to the process. The caller is responsible for freeing this string with `Ole32#CoTaskMemFree` when it is no longer needed. ppszAppID) Retrieves the application-defined, explicit Application User Model ID (AppUserModelID) for the current process.
public WinNT.HRESULT	Returns: If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. SetCurrentProcessExplicitAppUserModelID(WString The AppUserModelID to assign to the current process. appID) Specifies a unique application-defined Application User Model ID (AppUserModelID) that identifies the current process to the taskbar.
public WinDef.UINT_PTR	Returns: This function returns a message-dependent value. For more information, see the Windows SDK documentation for the specific appbar message sent. SHAppBarMessage(WinDef.DWORD Appbar message value to send. This parameter can be one of the following values. `ShellAPI#ABM_NEW` Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. `ShellAPI#ABM_REMOVE` Unregisters an appbar, removing the bar from the system's internal list. `ShellAPI#ABM_QUERYPOS` Requests a size and screen position for an appbar. `ShellAPI#ABM_SETPOS` Sets the size and screen position of an appbar. `ShellAPI#ABM_GETSTATE` Retrieves the autohide and always-on-top states of the Windows taskbar. `ShellAPI#ABM_GETTASKBARPOS` Retrieves the bounding rectangle of the Windows taskbar. Note that this applies only to the system taskbar. Other objects, particularly toolbars supplied with third-party software, also can be present. As a result, some of the screen area not covered by the Windows taskbar might not be visible to the user. To retrieve the area of the screen not covered by both the taskbar and other app bars -- the working area available to your application --, use the GetMonitorInfo function. `ShellAPI#ABM_ACTIVATE` Notifies the system to activate or deactivate an appbar. The lParam member of the APPBARDATA pointed to by pData is set to TRUE to activate or FALSE to deactivate. `ShellAPI#ABM_GETAUTOHIDEBAR` Retrieves the handle to the autohide appbar associated with a particular edge of the screen. `ShellAPI#ABM_SETAUTOHIDEBAR` Registers or unregisters an autohide appbar for an edge of the screen. `ShellAPI#ABM_WINDOWPOSCHANGED` Notifies the system when an appbar's position has changed. `ShellAPI#ABM_SETSTATE` Windows XP and later: Sets the state of the appbar's autohide and always-on-top attributes. dwMessage, ShellAPI.APPBARDATA A pointer to an APPBARDATA structure. The content of the structure on entry and on exit depends on the value set in the dwMessage parameter. See the individual message pages for specifics. pData) SHAppBarMessage function
public WinDef.INT_PTR	Returns: If the function succeeds, it returns a value greater than 32. If the function fails, it returns an error value that indicates the cause of the failure. The return value is cast as an HINSTANCE for backward compatibility with 16-bit Windows applications. It is not a true HINSTANCE, however. It can be cast only to an int and compared to either 32 or the following error codes below. Note `WinDef.INT_PTR` is used instead of HINSTANCE here, since the former fits the reutrn type's actual usage more closely. 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 DLL 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. This error will also be returned if you attempt to print a file that is not printable. 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. ShellExecute(WinDef.HWND A handle to the owner window used for displaying a UI or error messages. This value can be NULL if the operation is not associated with a window. hwnd, String A pointer to a null-terminated string, referred to in this case as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. The following verbs are commonly used: edit Launches an editor and opens the document for editing. If lpFile is not a document file, the function will fail. explore Explores a folder specified by lpFile. find Initiates a search beginning in the directory specified by lpDirectory. open Opens the item specified by the lpFile parameter. The item can be a file or folder. print Prints the file specified by lpFile. If lpFile is not a document file, the function fails. NULL In systems prior to Windows 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used. In Windows 2000 and later, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry. lpOperation, String A pointer to a null-terminated string that specifies the file or object on which to execute the specified verb. To specify a Shell namespace object, pass the fully qualified parse name. Note that not all verbs are supported on all objects. For example, not all document types support the "print" verb. If a relative path is used for the lpDirectory parameter do not use a relative path for lpFile. lpFile, String If lpFile specifies an executable file, this parameter is a pointer to a null-terminated string that specifies the parameters to be passed to the application. The format of this string is determined by the verb that is to be invoked. If lpFile specifies a document file, lpParameters should be NULL. lpParameters, String A pointer to a null-terminated string that specifies the default (working) directory for the action. If this value is NULL, the current working directory is used. If a relative path is provided at lpFile, do not use a relative path for lpDirectory. lpDirectory, int The flags that specify how an application is to be displayed when it is opened. If lpFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it. nShowCmd) Performs an operation on a specified file.
public boolean	Returns: Returns TRUE if successful; otherwise, FALSE. Call GetLastError for extended error information. ShellExecuteEx(ShellAPI.SHELLEXECUTEINFO Type: SHELLEXECUTEINFO* A pointer to a SHELLEXECUTEINFO structure that contains and receives information about the application being executed. lpExecInfo)
public int	Returns: Returns S_OK (0) if successful, or a COM-defined error value otherwise. SHEmptyRecycleBin(WinNT.HANDLE A handle to the parent window of any dialog boxes that might be displayed during the operation. This parameter can be NULL. hwnd, String a null-terminated string of maximum length MAX_PATH that contains the path of the root drive on which the Recycle Bin is located. This parameter can contain a string formatted with the drive, folder, and subfolder names, for example c:\windows\system\, etc. 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. pszRootPath, int a bitwise combination of SHERB_NOCONFIRMATION, SHERB_NOPROGRESSUI and SHERB_NOSOUND. dwFlags) Empties the Recycle Bin on the specified drive.
public int	Returns: Returns zero if successful, or nonzero otherwise. SHFileOperation(ShellAPI.SHFILEOPSTRUCT Address of an SHFILEOPSTRUCT structure that contains information this function needs to carry out the specified operation. fileop) This function can be used to copy, move, rename, or delete a file system object.
public WinNT.HRESULT	Returns: If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. SHGetDesktopFolder(PointerByReference A place to put the IShellFolder interface pointer ppshf) Retrieves the IShellFolder interface for the desktop folder, which is the root of the Shell's namespace.
public WinNT.HRESULT	Returns: Returns standard HRESULT codes. SHGetFolderPath(WinDef.HWND Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a user interface (UI) prompt will appear in this window. hwndOwner, int A CSIDL value that identifies the folder whose path is to be retrieved. Only real folders are valid. If a virtual folder is specified, this function will fail. You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with CSIDL_FLAG_CREATE. nFolder, WinNT.HANDLE An access token that can be used to represent a particular user. hToken, WinDef.DWORD Flags to specify which path is to be returned. dwFlags, char[] Pointer to a null-terminated string of length MAX_PATH which will receive the path. If an error occurs or S_FALSE is returned, this string will be empty. pszPath) Takes the CSIDL of a folder and returns the path.
public WinNT.HRESULT	Returns: Returns S_OK if successful, or an error value otherwise, including the following: E_FAIL Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID which does not have a path (such as a folder marked as KF_CATEGORY_VIRTUAL). E_INVALIDARG Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID that is not present on the system. Not all KNOWNFOLDERID values are present on all systems. Use IKnownFolderManager::GetFolderIds to retrieve the set of KNOWNFOLDERID values for the current system. SHGetKnownFolderPath(Guid.GUID A reference to the KNOWNFOLDERID (in `KnownFolders`) that identifies the folder. rfid, int Flags that specify special retrieval options. This value can be 0; otherwise, one or more of the `ShlObj.KNOWN_FOLDER_FLAG` values. dwFlags, WinNT.HANDLE Type: HANDLE An access token that represents a particular user. If this parameter is NULL, which is the most common usage, the function requests the known folder for the current user. Request a specific user's folder by passing the hToken of that user. This is typically done in the context of a service that has sufficient privileges to retrieve the token of a given user. That token must be opened with TOKEN_QUERY and TOKEN_IMPERSONATE rights. In some cases, you also need to include TOKEN_DUPLICATE. In addition to passing the user's hToken, the registry hive of that specific user must be mounted. See Access Control for further discussion of access control issues. Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHGetKnownFolderPath to find folder locations (such as the Desktop folder) for the Default User. The Default User user profile is duplicated when any new user account is created, and includes special folders such as Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note that access to the Default User folders requires administrator privileges. hToken, PointerByReference When this method returns, contains the address of a pointer to a null-terminated Unicode string that specifies the path of the known folder. The calling process is responsible for freeing this resource once it is no longer needed by calling `Ole32#CoTaskMemFree`. The returned path does not include a trailing backslash. For example, "C:\Users" is returned rather than "C:\Users\". ppszPath) Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID.
public WinNT.HRESULT	Returns: If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. SHGetSpecialFolderLocation(WinDef.HWND Reserved. hwndOwner, int A CSIDL value that identifies the folder of interest. nFolder, PointerByReference A PIDL specifying the folder's location relative to the root of the namespace (the desktop). It is the responsibility of the calling application to free the returned IDList by using CoTaskMemFree. ppidl) SHGetSpecialFolderLocation function for getting PIDL reference to My Computer etc
public boolean	Returns: `true` if successful; otherwise, `false`. SHGetSpecialFolderPath(WinDef.HWND Reserved. owner, char[] A pointer to a null-terminated string that receives the drive and path of the specified folder. This buffer must be at least MAX_PATH characters in size. path, int A CSIDL that identifies the folder of interest. If a virtual folder is specified, this function will fail. csidl, boolean Indicates whether the folder should be created if it does not already exist. If this value is nonzero, the folder is created. If this value is zero, the folder is not created. create) Retrieves the path of a special folder, identified by its CSIDL.

INSTANCE	back to summary
public static final Shell32 INSTANCE The instance

SEE_MASK_FLAG_NO_UI	back to summary
public static final int SEE_MASK_FLAG_NO_UI Do not display an error message box if an error occurs.

SEE_MASK_NOCLOSEPROCESS	back to summary
public static final int SEE_MASK_NOCLOSEPROCESS SEE_MASK_NOCLOSEPROCESS (0x00000040) Use to indicate that the hProcess member receives the process handle. This handle is typically used to allow an application to find out when a process created with terminates. In some cases, such as when execution is satisfied through a DDE conversation, no handle will be returned. The calling application is responsible for closing the handle when it is no longer needed.

SHERB_NOCONFIRMATION	back to summary
public static final int SHERB_NOCONFIRMATION No dialog box confirming the deletion of the objects will be displayed.

SHERB_NOPROGRESSUI	back to summary
public static final int SHERB_NOPROGRESSUI No dialog box indicating the progress will be displayed.

SHERB_NOSOUND	back to summary
public static final int SHERB_NOSOUND No sound will be played when the operation is complete.

Method Detail

CommandLineToArgvW back to summary

CommandLineToArgvW	back to summary
public Pointer CommandLineToArgvW(WString lpCmdLine, IntByReference pNumArgs) 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. Parameters lpCmdLine:WString A Unicode string that contains the full command line. If this parameter is an empty string the function returns the path to the current executable file. pNumArgs:IntByReference Pointer to an `int` that receives the number of array elements returned, similar to `argc`. Returns:Pointer A pointer to an array of `LPWSTR` values, similar to `argv`. If the function fails, the return value is `null`. To get extended error information, call `Kernel32#GetLastError`. CommandLineToArgvW allocates a block of contiguous memory for pointers to the argument strings, and for the argument strings themselves; the calling application must free the memory used by the argument list when it is no longer needed. To free the memory, use a single call to the `Kernel32#LocalFree` function.

public Pointer CommandLineToArgvW(WString lpCmdLine, IntByReference pNumArgs)

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.

Parameters

lpCmdLine:WString: A Unicode string that contains the full command line. If this parameter is an empty string the function returns the path to the current executable file.
pNumArgs:IntByReference: Pointer to an int that receives the number of array elements returned, similar to argc.

Returns:Pointer

A pointer to an array of LPWSTR values, similar to argv. If the function fails, the return value is null. To get extended error information, call Kernel32#GetLastError.
CommandLineToArgvW allocates a block of contiguous memory for pointers to the argument strings, and for the argument strings themselves; the calling application must free the memory used by the argument list when it is no longer needed. To free the memory, use a single call to the Kernel32#LocalFree function.

ExtractIconEx	back to summary
public int ExtractIconEx(String lpszFile, int nIconIndex, WinDef.HICON[] phiconLarge, WinDef.HICON[] phiconSmall, int nIcons) Parameters lpszFile:String Type: LPCTSTR The name of an executable file, DLL, or icon file from which icons will be extracted. nIconIndex:int Type: int The zero-based index of the first icon to extract. For example, if this value is zero, the function extracts the first icon in the specified file. If this value is -1 and phiconLarge and phiconSmall are both NULL, the function returns the total number of icons in the specified file. If the file is an executable file or DLL, the return value is the number of RT_GROUP_ICON resources. If the file is an .ico file, the return value is 1. If this value is a negative number and either phiconLarge or phiconSmall is not NULL, the function begins by extracting the icon whose resource identifier is equal to the absolute value of nIconIndex. For example, use -3 to extract the icon whose resource identifier is 3. phiconLarge:WinDef.HICON[] Type: HICON* An array of icon handles that receives handles to the large icons extracted from the file. If this parameter is NULL, no large icons are extracted from the file. phiconSmall:WinDef.HICON[] Type: HICON* An array of icon handles that receives handles to the small icons extracted from the file. If this parameter is NULL, no small icons are extracted from the file. nIcons:int Type: UINT The number of icons to be extracted from the file. Returns:int Type: UINT If the nIconIndex parameter is -1, the phiconLarge parameter is NULL, and the phiconSmall parameter is NULL, then the return value is the number of icons contained in the specified file. Otherwise, the return value is the number of icons successfully extracted from the file. See Also MSDN

ExtractIconEx

back to summary

public int ExtractIconEx(String lpszFile, int nIconIndex, WinDef.HICON[] phiconLarge, WinDef.HICON[] phiconSmall, int nIcons)

Parameters

lpszFile:String: Type: LPCTSTR
The name of an executable file, DLL, or icon file from which icons will be extracted.
nIconIndex:int: Type: int
The zero-based index of the first icon to extract. For example, if this value is zero, the function extracts the first icon in the specified file.
If this value is -1 and phiconLarge and phiconSmall are both NULL, the function returns the total number of icons in the specified file.
If the file is an executable file or DLL, the return value is the number of RT_GROUP_ICON resources.
If the file is an .ico file, the return value is 1. If this value is a negative number and either phiconLarge or phiconSmall is not NULL, the function begins by extracting the icon whose resource identifier is equal to the absolute value of nIconIndex. For example, use -3 to extract the icon whose resource identifier is 3.
phiconLarge:WinDef.HICON[]: Type: HICON*
An array of icon handles that receives handles to the large icons extracted from the file. If this parameter is NULL, no large icons are extracted from the file.
phiconSmall:WinDef.HICON[]: Type: HICON*
An array of icon handles that receives handles to the small icons extracted from the file. If this parameter is NULL, no small icons are extracted from the file.
nIcons:int: Type: UINT
The number of icons to be extracted from the file.

Returns:int

Type: UINT
If the nIconIndex parameter is -1, the phiconLarge parameter is NULL, and the phiconSmall parameter is NULL, then the return value is the number of icons contained in the specified file. Otherwise, the return value is the number of icons successfully extracted from the file.

See Also

MSDN

GetCurrentProcessExplicitAppUserModelID back to summary

GetCurrentProcessExplicitAppUserModelID	back to summary
public WinNT.HRESULT GetCurrentProcessExplicitAppUserModelID(PointerByReference ppszAppID) Retrieves the application-defined, explicit Application User Model ID (AppUserModelID) for the current process. Parameters ppszAppID:PointerByReference A pointer that receives the address of the AppUserModelID assigned to the process. The caller is responsible for freeing this string with `Ole32#CoTaskMemFree` when it is no longer needed. Returns:WinNT.HRESULT If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. See Also MSDN

public WinNT.HRESULT GetCurrentProcessExplicitAppUserModelID(PointerByReference ppszAppID)

Retrieves the application-defined, explicit Application User Model ID (AppUserModelID) for the current process.

Parameters

ppszAppID:PointerByReference: A pointer that receives the address of the AppUserModelID assigned to the process. The caller is responsible for freeing this string with Ole32#CoTaskMemFree when it is no longer needed.

Returns:WinNT.HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

See Also

MSDN

SetCurrentProcessExplicitAppUserModelID	back to summary
public WinNT.HRESULT SetCurrentProcessExplicitAppUserModelID(WString appID) Specifies a unique application-defined Application User Model ID (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. Parameters appID:WString The AppUserModelID to assign to the current process. Returns:WinNT.HRESULT If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. See Also MSDN

SetCurrentProcessExplicitAppUserModelID

back to summary

public WinNT.HRESULT SetCurrentProcessExplicitAppUserModelID(WString appID)

Specifies a unique application-defined Application User Model ID (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.

Parameters

appID:WString: The AppUserModelID to assign to the current process.

Returns:WinNT.HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

See Also

MSDN

SHAppBarMessage back to summary

SHAppBarMessage	back to summary
public WinDef.UINT_PTR SHAppBarMessage(WinDef.DWORD dwMessage, ShellAPI.APPBARDATA pData) SHAppBarMessage function Parameters dwMessage:WinDef.DWORD Appbar message value to send. This parameter can be one of the following values. `ShellAPI#ABM_NEW` Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. `ShellAPI#ABM_REMOVE` Unregisters an appbar, removing the bar from the system's internal list. `ShellAPI#ABM_QUERYPOS` Requests a size and screen position for an appbar. `ShellAPI#ABM_SETPOS` Sets the size and screen position of an appbar. `ShellAPI#ABM_GETSTATE` Retrieves the autohide and always-on-top states of the Windows taskbar. `ShellAPI#ABM_GETTASKBARPOS` Retrieves the bounding rectangle of the Windows taskbar. Note that this applies only to the system taskbar. Other objects, particularly toolbars supplied with third-party software, also can be present. As a result, some of the screen area not covered by the Windows taskbar might not be visible to the user. To retrieve the area of the screen not covered by both the taskbar and other app bars -- the working area available to your application --, use the GetMonitorInfo function. `ShellAPI#ABM_ACTIVATE` Notifies the system to activate or deactivate an appbar. The lParam member of the APPBARDATA pointed to by pData is set to TRUE to activate or FALSE to deactivate. `ShellAPI#ABM_GETAUTOHIDEBAR` Retrieves the handle to the autohide appbar associated with a particular edge of the screen. `ShellAPI#ABM_SETAUTOHIDEBAR` Registers or unregisters an autohide appbar for an edge of the screen. `ShellAPI#ABM_WINDOWPOSCHANGED` Notifies the system when an appbar's position has changed. `ShellAPI#ABM_SETSTATE` Windows XP and later: Sets the state of the appbar's autohide and always-on-top attributes. pData:ShellAPI.APPBARDATA A pointer to an APPBARDATA structure. The content of the structure on entry and on exit depends on the value set in the dwMessage parameter. See the individual message pages for specifics. Returns:WinDef.UINT_PTR This function returns a message-dependent value. For more information, see the Windows SDK documentation for the specific appbar message sent. See Also ABM_NEW, ABM_REMOVE, ABM_QUERYPOS, ABM_SETPOS, ABM_GETSTATE, ABM_GETTASKBARPOS, ABM_ACTIVATE, ABM_GETAUTOHIDEBAR, ABM_SETAUTOHIDEBAR, ABM_WINDOWPOSCHANGED, ABM_SETSTATE

public WinDef.UINT_PTR SHAppBarMessage(WinDef.DWORD dwMessage, ShellAPI.APPBARDATA pData)

SHAppBarMessage function

Parameters

dwMessage:WinDef.DWORD: Appbar message value to send. This parameter can be one of the following values. ShellAPI#ABM_NEW Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. ShellAPI#ABM_REMOVE Unregisters an appbar, removing the bar from the system's internal list. ShellAPI#ABM_QUERYPOS Requests a size and screen position for an appbar. ShellAPI#ABM_SETPOS Sets the size and screen position of an appbar. ShellAPI#ABM_GETSTATE Retrieves the autohide and always-on-top states of the Windows taskbar. ShellAPI#ABM_GETTASKBARPOS Retrieves the bounding rectangle of the Windows taskbar. Note that this applies only to the system taskbar. Other objects, particularly toolbars supplied with third-party software, also can be present. As a result, some of the screen area not covered by the Windows taskbar might not be visible to the user. To retrieve the area of the screen not covered by both the taskbar and other app bars -- the working area available to your application --, use the GetMonitorInfo function. ShellAPI#ABM_ACTIVATE Notifies the system to activate or deactivate an appbar. The lParam member of the APPBARDATA pointed to by pData is set to TRUE to activate or FALSE to deactivate. ShellAPI#ABM_GETAUTOHIDEBAR Retrieves the handle to the autohide appbar associated with a particular edge of the screen. ShellAPI#ABM_SETAUTOHIDEBAR Registers or unregisters an autohide appbar for an edge of the screen. ShellAPI#ABM_WINDOWPOSCHANGED Notifies the system when an appbar's position has changed. ShellAPI#ABM_SETSTATE Windows XP and later: Sets the state of the appbar's autohide and always-on-top attributes.
pData:ShellAPI.APPBARDATA: A pointer to an APPBARDATA structure. The content of the structure on entry and on exit depends on the value set in the dwMessage parameter. See the individual message pages for specifics.

Returns:WinDef.UINT_PTR

This function returns a message-dependent value. For more information, see the Windows SDK documentation for the specific appbar message sent.

ShellExecute back to summary

ShellExecute	back to summary
public WinDef.INT_PTR ShellExecute(WinDef.HWND hwnd, String lpOperation, String lpFile, String lpParameters, String lpDirectory, int nShowCmd) Performs an operation on a specified file. Parameters hwnd:WinDef.HWND A handle to the owner window used for displaying a UI or error messages. This value can be NULL if the operation is not associated with a window. lpOperation:String A pointer to a null-terminated string, referred to in this case as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. The following verbs are commonly used: edit Launches an editor and opens the document for editing. If lpFile is not a document file, the function will fail. explore Explores a folder specified by lpFile. find Initiates a search beginning in the directory specified by lpDirectory. open Opens the item specified by the lpFile parameter. The item can be a file or folder. print Prints the file specified by lpFile. If lpFile is not a document file, the function fails. NULL In systems prior to Windows 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used. In Windows 2000 and later, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry. lpFile:String A pointer to a null-terminated string that specifies the file or object on which to execute the specified verb. To specify a Shell namespace object, pass the fully qualified parse name. Note that not all verbs are supported on all objects. For example, not all document types support the "print" verb. If a relative path is used for the lpDirectory parameter do not use a relative path for lpFile. lpParameters:String If lpFile specifies an executable file, this parameter is a pointer to a null-terminated string that specifies the parameters to be passed to the application. The format of this string is determined by the verb that is to be invoked. If lpFile specifies a document file, lpParameters should be NULL. lpDirectory:String A pointer to a null-terminated string that specifies the default (working) directory for the action. If this value is NULL, the current working directory is used. If a relative path is provided at lpFile, do not use a relative path for lpDirectory. nShowCmd:int The flags that specify how an application is to be displayed when it is opened. If lpFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it. Returns:WinDef.INT_PTR If the function succeeds, it returns a value greater than 32. If the function fails, it returns an error value that indicates the cause of the failure. The return value is cast as an HINSTANCE for backward compatibility with 16-bit Windows applications. It is not a true HINSTANCE, however. It can be cast only to an int and compared to either 32 or the following error codes below. Note `WinDef.INT_PTR` is used instead of HINSTANCE here, since the former fits the reutrn type's actual usage more closely. 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 DLL 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. This error will also be returned if you attempt to print a file that is not printable. 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.

public WinDef.INT_PTR ShellExecute(WinDef.HWND hwnd, String lpOperation, String lpFile, String lpParameters, String lpDirectory, int nShowCmd)

Performs an operation on a specified file.

Parameters

hwnd:WinDef.HWND: A handle to the owner window used for displaying a UI or error messages. This value can be NULL if the operation is not associated with a window.
lpOperation:String: A pointer to a null-terminated string, referred to in this case as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. The following verbs are commonly used: edit Launches an editor and opens the document for editing. If lpFile is not a document file, the function will fail. explore Explores a folder specified by lpFile. find Initiates a search beginning in the directory specified by lpDirectory. open Opens the item specified by the lpFile parameter. The item can be a file or folder. print Prints the file specified by lpFile. If lpFile is not a document file, the function fails. NULL In systems prior to Windows 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used. In Windows 2000 and later, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry.
lpFile:String: A pointer to a null-terminated string that specifies the file or object on which to execute the specified verb. To specify a Shell namespace object, pass the fully qualified parse name. Note that not all verbs are supported on all objects. For example, not all document types support the "print" verb. If a relative path is used for the lpDirectory parameter do not use a relative path for lpFile.
lpParameters:String: If lpFile specifies an executable file, this parameter is a pointer to a null-terminated string that specifies the parameters to be passed to the application. The format of this string is determined by the verb that is to be invoked. If lpFile specifies a document file, lpParameters should be NULL.
lpDirectory:String: A pointer to a null-terminated string that specifies the default (working) directory for the action. If this value is NULL, the current working directory is used. If a relative path is provided at lpFile, do not use a relative path for lpDirectory.
nShowCmd:int: The flags that specify how an application is to be displayed when it is opened. If lpFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it.

Returns:WinDef.INT_PTR

If the function succeeds, it returns a value greater than 32. If the function fails, it returns an error value that indicates the cause of the failure. The return value is cast as an HINSTANCE for backward compatibility with 16-bit Windows applications. It is not a true HINSTANCE, however. It can be cast only to an int and compared to either 32 or the following error codes below.

Note

WinDef.INT_PTR is used instead of HINSTANCE here, since the former fits the reutrn type's actual usage more closely. 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 DLL 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. This error will also be returned if you attempt to print a file that is not printable. 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.

ShellExecuteEx	back to summary
public boolean ShellExecuteEx(ShellAPI.SHELLEXECUTEINFO lpExecInfo) Parameters lpExecInfo:ShellAPI.SHELLEXECUTEINFO Type: SHELLEXECUTEINFO* A pointer to a SHELLEXECUTEINFO structure that contains and receives information about the application being executed. Returns:boolean Returns TRUE if successful; otherwise, FALSE. Call GetLastError for extended error information.

SHEmptyRecycleBin	back to summary
public int SHEmptyRecycleBin(WinNT.HANDLE hwnd, String pszRootPath, int dwFlags) Empties the Recycle Bin on the specified drive. Parameters hwnd:WinNT.HANDLE A handle to the parent window of any dialog boxes that might be displayed during the operation. This parameter can be NULL. pszRootPath:String a null-terminated string of maximum length MAX_PATH that contains the path of the root drive on which the Recycle Bin is located. This parameter can contain a string formatted with the drive, folder, and subfolder names, for example c:\windows\system\, etc. 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:int a bitwise combination of SHERB_NOCONFIRMATION, SHERB_NOPROGRESSUI and SHERB_NOSOUND. Returns:int Returns S_OK (0) if successful, or a COM-defined error value otherwise.

SHEmptyRecycleBin

back to summary

public int SHEmptyRecycleBin(WinNT.HANDLE hwnd, String pszRootPath, int dwFlags)

Empties the Recycle Bin on the specified drive.

Parameters

hwnd:WinNT.HANDLE: A handle to the parent window of any dialog boxes that might be displayed during the operation.
This parameter can be NULL.
pszRootPath:String: a null-terminated string of maximum length MAX_PATH that contains the path of the root
drive on which the Recycle Bin is located. This parameter can contain a string formatted with the drive,
folder, and subfolder names, for example c:\windows\system\, etc. 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:int: a bitwise combination of SHERB_NOCONFIRMATION, SHERB_NOPROGRESSUI and SHERB_NOSOUND.

Returns:int

Returns S_OK (0) if successful, or a COM-defined error value otherwise.

SHFileOperation	back to summary
public int SHFileOperation(ShellAPI.SHFILEOPSTRUCT fileop) This function can be used to copy, move, rename, or delete a file system object. Parameters fileop:ShellAPI.SHFILEOPSTRUCT Address of an SHFILEOPSTRUCT structure that contains information this function needs to carry out the specified operation. Returns:int Returns zero if successful, or nonzero otherwise.

SHFileOperation

back to summary

public int SHFileOperation(ShellAPI.SHFILEOPSTRUCT fileop)

This function can be used to copy, move, rename, or delete a file system object.

Parameters

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

Returns:int

Returns zero if successful, or nonzero otherwise.

SHGetDesktopFolder	back to summary
public WinNT.HRESULT SHGetDesktopFolder(PointerByReference ppshf) Retrieves the IShellFolder interface for the desktop folder, which is the root of the Shell's namespace. The retrieved COM interface pointer can be used via Com4JNA's ComObject.wrapNativeInterface call given a suitable interface definition for IShellFolder Parameters ppshf:PointerByReference A place to put the IShellFolder interface pointer Returns:WinNT.HRESULT If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SHGetDesktopFolder

back to summary

public WinNT.HRESULT SHGetDesktopFolder(PointerByReference ppshf)

Retrieves the IShellFolder interface for the desktop folder, which is the root of the Shell's namespace. The retrieved COM interface pointer can be used via Com4JNA's ComObject.wrapNativeInterface call given a suitable interface definition for IShellFolder

Parameters

ppshf:PointerByReference: A place to put the IShellFolder interface pointer

Returns:WinNT.HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SHGetFolderPath	back to summary
public WinNT.HRESULT SHGetFolderPath(WinDef.HWND hwndOwner, int nFolder, WinNT.HANDLE hToken, WinDef.DWORD dwFlags, char[] pszPath) Takes the CSIDL of a folder and returns the path. Parameters hwndOwner:WinDef.HWND Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a user interface (UI) prompt will appear in this window. nFolder:int A CSIDL value that identifies the folder whose path is to be retrieved. Only real folders are valid. If a virtual folder is specified, this function will fail. You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with CSIDL_FLAG_CREATE. hToken:WinNT.HANDLE An access token that can be used to represent a particular user. dwFlags:WinDef.DWORD Flags to specify which path is to be returned. pszPath:char[] Pointer to a null-terminated string of length MAX_PATH which will receive the path. If an error occurs or S_FALSE is returned, this string will be empty. Returns:WinNT.HRESULT Returns standard HRESULT codes.

SHGetFolderPath

back to summary

public WinNT.HRESULT SHGetFolderPath(WinDef.HWND hwndOwner, int nFolder, WinNT.HANDLE hToken, WinDef.DWORD dwFlags, char[] pszPath)

Takes the CSIDL of a folder and returns the path.

Parameters

hwndOwner:WinDef.HWND: Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a user interface (UI) prompt will appear in this window.
nFolder:int: A CSIDL value that identifies the folder whose path is to be retrieved. Only real folders are valid. If a virtual folder is specified, this function will fail. You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with CSIDL_FLAG_CREATE.
hToken:WinNT.HANDLE: An access token that can be used to represent a particular user.
dwFlags:WinDef.DWORD: Flags to specify which path is to be returned.
pszPath:char[]: Pointer to a null-terminated string of length MAX_PATH which will receive the path. If an error occurs or S_FALSE is returned, this string will be empty.

Returns:WinNT.HRESULT

Returns standard HRESULT codes.

SHGetKnownFolderPath back to summary

SHGetKnownFolderPath	back to summary
public WinNT.HRESULT SHGetKnownFolderPath(Guid.GUID rfid, int dwFlags, WinNT.HANDLE hToken, PointerByReference ppszPath) Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This function replaces `SHGetFolderPath`. That older function is now simply a wrapper for SHGetKnownFolderPath. Parameters rfid:Guid.GUID A reference to the KNOWNFOLDERID (in `KnownFolders`) that identifies the folder. dwFlags:int Flags that specify special retrieval options. This value can be 0; otherwise, one or more of the `ShlObj.KNOWN_FOLDER_FLAG` values. hToken:WinNT.HANDLE Type: HANDLE An access token that represents a particular user. If this parameter is NULL, which is the most common usage, the function requests the known folder for the current user. Request a specific user's folder by passing the hToken of that user. This is typically done in the context of a service that has sufficient privileges to retrieve the token of a given user. That token must be opened with TOKEN_QUERY and TOKEN_IMPERSONATE rights. In some cases, you also need to include TOKEN_DUPLICATE. In addition to passing the user's hToken, the registry hive of that specific user must be mounted. See Access Control for further discussion of access control issues. Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHGetKnownFolderPath to find folder locations (such as the Desktop folder) for the Default User. The Default User user profile is duplicated when any new user account is created, and includes special folders such as Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note that access to the Default User folders requires administrator privileges. ppszPath:PointerByReference When this method returns, contains the address of a pointer to a null-terminated Unicode string that specifies the path of the known folder. The calling process is responsible for freeing this resource once it is no longer needed by calling `Ole32#CoTaskMemFree`. The returned path does not include a trailing backslash. For example, "C:\Users" is returned rather than "C:\Users\". Returns:WinNT.HRESULT Returns S_OK if successful, or an error value otherwise, including the following: E_FAIL Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID which does not have a path (such as a folder marked as KF_CATEGORY_VIRTUAL). E_INVALIDARG Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID that is not present on the system. Not all KNOWNFOLDERID values are present on all systems. Use IKnownFolderManager::GetFolderIds to retrieve the set of KNOWNFOLDERID values for the current system.

public WinNT.HRESULT SHGetKnownFolderPath(Guid.GUID rfid, int dwFlags, WinNT.HANDLE hToken, PointerByReference ppszPath)

Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This function replaces SHGetFolderPath. That older function is now simply a wrapper for SHGetKnownFolderPath.

Parameters

rfid:Guid.GUID: A reference to the KNOWNFOLDERID (in KnownFolders) that identifies the folder.
dwFlags:int: Flags that specify special retrieval options. This value can be 0; otherwise, one or more of the ShlObj.KNOWN_FOLDER_FLAG values.
hToken:WinNT.HANDLE: Type: HANDLE An access token that represents a particular user. If this parameter is NULL, which is the most common usage, the function requests the known folder for the current user. Request a specific user's folder by passing the hToken of that user. This is typically done in the context of a service that has sufficient privileges to retrieve the token of a given user. That token must be opened with TOKEN_QUERY and TOKEN_IMPERSONATE rights. In some cases, you also need to include TOKEN_DUPLICATE. In addition to passing the user's hToken, the registry hive of that specific user must be mounted. See Access Control for further discussion of access control issues. Assigning the hToken parameter a value of -1 indicates the Default User. This allows clients of SHGetKnownFolderPath to find folder locations (such as the Desktop folder) for the Default User. The Default User user profile is duplicated when any new user account is created, and includes special folders such as Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note that access to the Default User folders requires administrator privileges.
ppszPath:PointerByReference: When this method returns, contains the address of a pointer to a null-terminated Unicode string that specifies the path of the known folder. The calling process is responsible for freeing this resource once it is no longer needed by calling Ole32#CoTaskMemFree. The returned path does not include a trailing backslash. For example, "C:\Users" is returned rather than "C:\Users\".

Returns:WinNT.HRESULT

Returns S_OK if successful, or an error value otherwise, including the following:

E_FAIL Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID which does not have a path (such as a folder marked as KF_CATEGORY_VIRTUAL).
E_INVALIDARG Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID that is not present on the system. Not all KNOWNFOLDERID values are present on all systems. Use IKnownFolderManager::GetFolderIds to retrieve the set of KNOWNFOLDERID values for the current system.

SHGetSpecialFolderLocation	back to summary
public WinNT.HRESULT SHGetSpecialFolderLocation(WinDef.HWND hwndOwner, int nFolder, PointerByReference ppidl) SHGetSpecialFolderLocation function for getting PIDL reference to My Computer etc Parameters hwndOwner:WinDef.HWND Reserved. nFolder:int A CSIDL value that identifies the folder of interest. ppidl:PointerByReference A PIDL specifying the folder's location relative to the root of the namespace (the desktop). It is the responsibility of the calling application to free the returned IDList by using CoTaskMemFree. Returns:WinNT.HRESULT If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SHGetSpecialFolderLocation

back to summary

public WinNT.HRESULT SHGetSpecialFolderLocation(WinDef.HWND hwndOwner, int nFolder, PointerByReference ppidl)

SHGetSpecialFolderLocation function for getting PIDL reference to My Computer etc

Parameters

hwndOwner:WinDef.HWND: Reserved.
nFolder:int: A CSIDL value that identifies the folder of interest.
ppidl:PointerByReference: A PIDL specifying the folder's location relative to the root of the namespace (the desktop). It is the responsibility of the calling application to free the returned IDList by using CoTaskMemFree.

Returns:WinNT.HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SHGetSpecialFolderPath back to summary

SHGetSpecialFolderPath	back to summary
public boolean SHGetSpecialFolderPath(WinDef.HWND owner, char[] path, int csidl, boolean create) Retrieves the path of a special folder, identified by its CSIDL. Parameters owner:WinDef.HWND Reserved. path:char[] A pointer to a null-terminated string that receives the drive and path of the specified folder. This buffer must be at least MAX_PATH characters in size. csidl:int A CSIDL that identifies the folder of interest. If a virtual folder is specified, this function will fail. create:boolean Indicates whether the folder should be created if it does not already exist. If this value is nonzero, the folder is created. If this value is zero, the folder is not created. Returns:boolean `true` if successful; otherwise, `false`.

public boolean SHGetSpecialFolderPath(WinDef.HWND owner, char[] path, int csidl, boolean create)

Retrieves the path of a special folder, identified by its CSIDL.

Parameters

owner:WinDef.HWND: Reserved.
path:char[]: A pointer to a null-terminated string that receives the drive and path of the specified folder. This buffer must be at least MAX_PATH characters in size.
csidl:int: A CSIDL that identifies the folder of interest. If a virtual folder is specified, this function will fail.
create:boolean: Indicates whether the folder should be created if it does not already exist. If this value is nonzero, the folder is created. If this value is zero, the folder is not created.

Returns:boolean

true if successful; otherwise, false.

public Interface Shell32

Field Summary

Method Summary

Field Detail

Method Detail