1 /* Copyright (c) 2007, 2013 Timothy Wall, Markus Karg, All Rights Reserved 2 * 3 * The contents of this file is dual-licensed under 2 4 * alternative Open Source/Free licenses: LGPL 2.1 or later and 5 * Apache License 2.0. (starting with JNA version 4.0.0). 6 * 7 * You can freely decide which license you want to apply to 8 * the project. 9 * 10 * You may obtain a copy of the LGPL License at: 11 * 12 * http://www.gnu.org/licenses/licenses.html 13 * 14 * A copy is also included in the downloadable source code package 15 * containing JNA, in file "LGPL2.1". 16 * 17 * You may obtain a copy of the Apache License at: 18 * 19 * http://www.apache.org/licenses/ 20 * 21 * A copy is also included in the downloadable source code package 22 * containing JNA, in file "AL2.0". 23 */ 24 package com.sun.jna.platform.win32; 25 26 import com.sun.jna.Native; 27 import com.sun.jna.WString; 28 import com.sun.jna.platform.win32.Guid.GUID; 29 import com.sun.jna.platform.win32.WinDef.DWORD; 30 import com.sun.jna.platform.win32.WinDef.HICON; 31 import com.sun.jna.platform.win32.WinDef.HWND; 32 import com.sun.jna.platform.win32.WinDef.INT_PTR; 33 import com.sun.jna.platform.win32.WinDef.UINT_PTR; 34 import com.sun.jna.platform.win32.WinNT.HANDLE; 35 import com.sun.jna.platform.win32.WinNT.HRESULT; 36 import com.sun.jna.ptr.PointerByReference; 37 import com.sun.jna.win32.StdCallLibrary; 38 import com.sun.jna.win32.W32APIOptions; 39 40 /** 41 * Shell32.dll Interface. 42 */ 43 public interface Shell32 extends ShellAPI, StdCallLibrary { 44 /** The instance **/ 45 Shell32 INSTANCE = Native.load("shell32", Shell32.class, W32APIOptions.DEFAULT_OPTIONS); 46 47 /** 48 * No dialog box confirming the deletion of the objects will be displayed. 49 */ 50 int SHERB_NOCONFIRMATION = 0x00000001; 51 52 /** 53 * No dialog box indicating the progress will be displayed. 54 */ 55 int SHERB_NOPROGRESSUI = 0x00000002; 56 57 /** 58 * No sound will be played when the operation is complete. 59 */ 60 int SHERB_NOSOUND = 0x00000004; 61 62 /** 63 * <p> 64 * <strong>SEE_MASK_NOCLOSEPROCESS</strong> (0x00000040) 65 * </p> 66 * <p> 67 * Use to indicate that the <strong>hProcess</strong> member receives the 68 * process handle. This handle is typically used to allow an application to 69 * find out when a process created with terminates. In some cases, such as 70 * when execution is satisfied through a DDE conversation, no handle will be 71 * returned. The calling application is responsible for closing the handle 72 * when it is no longer needed. 73 * </p> 74 */ 75 int SEE_MASK_NOCLOSEPROCESS = 0x00000040; 76 77 /** 78 * Do not display an error message box if an error occurs. 79 */ 80 int SEE_MASK_FLAG_NO_UI = 0x00000400; 81 82 /** 83 * This function can be used to copy, move, rename, or delete a file system object. 84 * @param fileop 85 * Address of an SHFILEOPSTRUCT structure that contains information this function 86 * needs to carry out the specified operation. 87 * @return 88 * Returns zero if successful, or nonzero otherwise. 89 */ SHFileOperation(SHFILEOPSTRUCT fileop)90 int SHFileOperation(SHFILEOPSTRUCT fileop); 91 92 /** 93 * Takes the CSIDL of a folder and returns the path. 94 * @param hwndOwner 95 * Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, 96 * and a dial-up connection needs to be made to access the folder, a user interface (UI) 97 * prompt will appear in this window. 98 * @param nFolder 99 * A CSIDL value that identifies the folder whose path is to be retrieved. Only real 100 * folders are valid. If a virtual folder is specified, this function will fail. You can 101 * force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with 102 * CSIDL_FLAG_CREATE. 103 * @param hToken 104 * An access token that can be used to represent a particular user. 105 * @param dwFlags 106 * Flags to specify which path is to be returned. 107 * @param pszPath 108 * Pointer to a null-terminated string of length MAX_PATH which will receive the path. 109 * If an error occurs or S_FALSE is returned, this string will be empty. 110 * @return 111 * Returns standard HRESULT codes. 112 */ SHGetFolderPath(HWND hwndOwner, int nFolder, HANDLE hToken, DWORD dwFlags, char[] pszPath)113 HRESULT SHGetFolderPath(HWND hwndOwner, int nFolder, HANDLE hToken, DWORD dwFlags, char[] pszPath); 114 115 /** 116 * Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This function replaces 117 * {@link #SHGetFolderPath}. That older function is now simply a wrapper for SHGetKnownFolderPath. 118 * @param rfid A reference to the KNOWNFOLDERID (in {@link KnownFolders}) that identifies the folder. 119 * @param dwFlags Flags that specify special retrieval options. This value can be 0; otherwise, one or more of the 120 * {@link ShlObj.KNOWN_FOLDER_FLAG} values. 121 * @param hToken Type: HANDLE An access token that represents a particular user. If this parameter is NULL, which is 122 * the most common usage, the function requests the known folder for the current user. Request a specific user's 123 * folder by passing the hToken of that user. This is typically done in the context of a service that has sufficient 124 * privileges to retrieve the token of a given user. That token must be opened with TOKEN_QUERY and 125 * TOKEN_IMPERSONATE rights. In some cases, you also need to include TOKEN_DUPLICATE. In addition to passing the 126 * user's hToken, the registry hive of that specific user must be mounted. See Access Control for further discussion 127 * of access control issues. Assigning the hToken parameter a value of -1 indicates the Default User. This allows 128 * clients of SHGetKnownFolderPath to find folder locations (such as the Desktop folder) for the Default User. The 129 * Default User user profile is duplicated when any new user account is created, and includes special folders such 130 * as Documents and Desktop. Any items added to the Default User folder also appear in any new user account. Note 131 * that access to the Default User folders requires administrator privileges. 132 * @param ppszPath When this method returns, contains the address of a pointer to a null-terminated 133 * Unicode string that specifies the path of the known folder. The calling process is responsible for freeing this 134 * resource once it is no longer needed by calling {@link Ole32#CoTaskMemFree}. The returned path does not include a trailing 135 * backslash. For example, "C:\Users" is returned rather than "C:\Users\". 136 * @return Returns S_OK if successful, or an error value otherwise, including the following: 137 * <ul><li>E_FAIL Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID which 138 * does not have a path (such as a folder marked as KF_CATEGORY_VIRTUAL).</li> 139 * <li>E_INVALIDARG Among other things, this value can indicate that the rfid parameter references a KNOWNFOLDERID 140 * that is not present on the system. Not all KNOWNFOLDERID values are present on all systems. Use 141 * IKnownFolderManager::GetFolderIds to retrieve the set of KNOWNFOLDERID values for the current system.</li></ul> 142 */ SHGetKnownFolderPath(GUID rfid, int dwFlags, HANDLE hToken, PointerByReference ppszPath)143 HRESULT SHGetKnownFolderPath(GUID rfid, int dwFlags, HANDLE hToken, PointerByReference ppszPath); 144 145 /** 146 * Retrieves the IShellFolder interface for the desktop folder, which is the root of the Shell's namespace. 147 * The retrieved COM interface pointer can be used via Com4JNA's ComObject.wrapNativeInterface call 148 * given a suitable interface definition for IShellFolder 149 * @param ppshf A place to put the IShellFolder interface pointer 150 * @return If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. 151 */ SHGetDesktopFolder(PointerByReference ppshf)152 HRESULT SHGetDesktopFolder(PointerByReference ppshf); 153 154 /** 155 * Performs an operation on a specified file. 156 * 157 * @param hwnd 158 * A handle to the owner window used for displaying a UI or error messages. This value can be NULL if the 159 * operation is not associated with a window. 160 * 161 * @param lpOperation 162 * A pointer to a null-terminated string, referred to in this case as a verb, that specifies the action to be 163 * performed. The set of available verbs depends on the particular file or folder. Generally, the actions 164 * available from an object's shortcut menu are available verbs. The following verbs are commonly used: 165 * 166 * edit 167 * Launches an editor and opens the document for editing. If lpFile is not a document file, the function will 168 * fail. 169 * explore 170 * Explores a folder specified by lpFile. 171 * find 172 * Initiates a search beginning in the directory specified by lpDirectory. 173 * open 174 * Opens the item specified by the lpFile parameter. The item can be a file or folder. 175 * print 176 * Prints the file specified by lpFile. If lpFile is not a document file, the function fails. 177 * NULL 178 * In systems prior to Windows 2000, the default verb is used if it is valid and available in the registry. If 179 * not, the "open" verb is used. 180 * In Windows 2000 and later, the default verb is used if available. If not, the "open" verb is used. If neither 181 * verb is available, the system uses the first verb listed in the registry. 182 * 183 * @param lpFile 184 * A pointer to a null-terminated string that specifies the file or object on which to execute the specified verb. 185 * To specify a Shell namespace object, pass the fully qualified parse name. Note that not all verbs are supported 186 * on all objects. For example, not all document types support the "print" verb. If a relative path is used for 187 * the lpDirectory parameter do not use a relative path for lpFile. 188 * 189 * @param lpParameters 190 * If lpFile specifies an executable file, this parameter is a pointer to a null-terminated string that specifies 191 * the parameters to be passed to the application. The format of this string is determined by the verb that is to 192 * be invoked. If lpFile specifies a document file, lpParameters should be NULL. 193 * 194 * @param lpDirectory 195 * A pointer to a null-terminated string that specifies the default (working) directory for the action. If this 196 * value is NULL, the current working directory is used. If a relative path is provided at lpFile, do not use a 197 * relative path for lpDirectory. 198 * 199 * @param nShowCmd 200 * The flags that specify how an application is to be displayed when it is opened. If lpFile specifies a document 201 * file, the flag is simply passed to the associated application. It is up to the application to decide how to 202 * handle it. 203 * 204 * @return 205 * If the function succeeds, it returns a value greater than 32. If the function fails, it returns an error value 206 * that indicates the cause of the failure. The return value is cast as an HINSTANCE for backward compatibility 207 * with 16-bit Windows applications. It is not a true HINSTANCE, however. It can be cast only to an int and 208 * compared to either 32 or the following error codes below. 209 * 210 * NOTE: {@link WinDef.INT_PTR} is used instead of HINSTANCE here, since 211 * the former fits the reutrn type's actual usage more closely. 212 * 213 * 0 The operating system is out of memory or resources. 214 * ERROR_FILE_NOT_FOUND The specified file was not found. 215 * ERROR_PATH_NOT_FOUND The specified path was not found. 216 * ERROR_BAD_FORMAT The .exe file is invalid (non-Win32 .exe or error in .exe image). 217 * SE_ERR_ACCESSDENIED The operating system denied access to the specified file. 218 * SE_ERR_ASSOCINCOMPLETE The file name association is incomplete or invalid. 219 * SE_ERR_DDEBUSY The DDE transaction could not be completed because other DDE transactions were being processed. 220 * SE_ERR_DDEFAIL The DDE transaction failed. 221 * SE_ERR_DDETIMEOUT The DDE transaction could not be completed because the request timed out. 222 * SE_ERR_DLLNOTFOUND The specified DLL was not found. 223 * SE_ERR_FNF The specified file was not found. 224 * SE_ERR_NOASSOC There is no application associated with the given file name extension. This error will also be 225 * returned if you attempt to print a file that is not printable. 226 * SE_ERR_OOM There was not enough memory to complete the operation. 227 * SE_ERR_PNF The specified path was not found. 228 * SE_ERR_SHARE A sharing violation occurred. 229 */ ShellExecute(HWND hwnd, String lpOperation, String lpFile, String lpParameters, String lpDirectory, int nShowCmd)230 INT_PTR ShellExecute(HWND hwnd, String lpOperation, String lpFile, String lpParameters, String lpDirectory, int nShowCmd); 231 232 /** 233 * Retrieves the path of a special folder, identified by its CSIDL. 234 * 235 * @param owner 236 * Reserved. 237 * @param path 238 * 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 239 * characters in size. 240 * @param csidl 241 * A CSIDL that identifies the folder of interest. If a virtual folder is specified, this function will fail. 242 * @param create 243 * 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 244 * zero, the folder is not created. 245 * @return {@code true} if successful; otherwise, {@code false}. 246 */ SHGetSpecialFolderPath(HWND owner, char[] path, int csidl, boolean create)247 boolean SHGetSpecialFolderPath(HWND owner, char[] path, int csidl, boolean create); 248 249 /** 250 * SHAppBarMessage function 251 * 252 * @param dwMessage 253 * Appbar message value to send. This parameter can be one of the following values. 254 * {@link ShellAPI#ABM_NEW} Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. 255 * {@link ShellAPI#ABM_REMOVE} Unregisters an appbar, removing the bar from the system's internal list. 256 * {@link ShellAPI#ABM_QUERYPOS} Requests a size and screen position for an appbar. 257 * {@link ShellAPI#ABM_SETPOS} Sets the size and screen position of an appbar. 258 * {@link ShellAPI#ABM_GETSTATE} Retrieves the autohide and always-on-top states of the Windows taskbar. 259 * {@link 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. 260 * {@link 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. 261 * {@link ShellAPI#ABM_GETAUTOHIDEBAR} Retrieves the handle to the autohide appbar associated with a particular edge of the screen. 262 * {@link ShellAPI#ABM_SETAUTOHIDEBAR} Registers or unregisters an autohide appbar for an edge of the screen. 263 * {@link ShellAPI#ABM_WINDOWPOSCHANGED} Notifies the system when an appbar's position has changed. 264 * {@link ShellAPI#ABM_SETSTATE} Windows XP and later: Sets the state of the appbar's autohide and always-on-top attributes. 265 * 266 * @param pData 267 * 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. 268 * 269 * @return This function returns a message-dependent value. For more information, see the Windows SDK documentation for the specific appbar message sent. 270 * 271 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787951(v=vs.85).aspx">ABM_NEW</a> 272 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787955(v=vs.85).aspx">ABM_REMOVE</a> 273 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787953(v=vs.85).aspx">ABM_QUERYPOS</a> 274 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787959(v=vs.85).aspx">ABM_SETPOS</a> 275 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787947(v=vs.85).aspx">ABM_GETSTATE</a> 276 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787949(v=vs.85).aspx">ABM_GETTASKBARPOS</a> 277 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787943(v=vs.85).aspx">ABM_ACTIVATE</a> 278 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787945(v=vs.85).aspx">ABM_GETAUTOHIDEBAR</a> 279 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787957(v=vs.85).aspx">ABM_SETAUTOHIDEBAR</a> 280 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787963(v=vs.85).aspx">ABM_WINDOWPOSCHANGED</a> 281 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/bb787961(v=vs.85).aspx">ABM_SETSTATE</a> 282 * 283 */ SHAppBarMessage(DWORD dwMessage, APPBARDATA pData)284 UINT_PTR SHAppBarMessage(DWORD dwMessage, APPBARDATA pData); 285 286 /** 287 * Empties the Recycle Bin on the specified drive. 288 * 289 * @param hwnd 290 * A handle to the parent window of any dialog boxes that might 291 * be displayed during the operation.<br> 292 * This parameter can be NULL. 293 * @param pszRootPath 294 * a null-terminated string of maximum length MAX_PATH that 295 * contains the path of the root<br> 296 * drive on which the Recycle Bin is located. This parameter can 297 * contain a string formatted with the drive,<br> 298 * folder, and subfolder names, for example c:\windows\system\, 299 * etc. It can also contain an empty string or<br> 300 * NULL. If this value is an empty string or NULL, all Recycle 301 * Bins on all drives will be emptied. 302 * @param dwFlags 303 * a bitwise combination of SHERB_NOCONFIRMATION, 304 * SHERB_NOPROGRESSUI and SHERB_NOSOUND.<br> 305 * @return Returns S_OK (0) if successful, or a COM-defined error value 306 * otherwise.<br> 307 */ SHEmptyRecycleBin(HANDLE hwnd, String pszRootPath, int dwFlags)308 int SHEmptyRecycleBin(HANDLE hwnd, String pszRootPath, int dwFlags); 309 310 /** 311 * @param lpExecInfo 312 * <p> 313 * Type: <strong>SHELLEXECUTEINFO*</strong> 314 * </p> 315 * <p> 316 * A pointer to a <a href= 317 * "https://msdn.microsoft.com/en-us/library/windows/desktop/bb759784(v=vs.85).aspx"> 318 * <strong xmlns="http://www.w3.org/1999/xhtml">SHELLEXECUTEINFO 319 * </strong></a> structure that contains and receives information 320 * about the application being executed. 321 * </p> 322 * @return 323 * <p> 324 * Returns <strong>TRUE</strong> if successful; otherwise, 325 * <strong>FALSE</strong>. Call <a href= 326 * "https://msdn.microsoft.com/en-us/library/windows/desktop/ms679360(v=vs.85).aspx"> 327 * <strong xmlns="http://www.w3.org/1999/xhtml">GetLastError 328 * </strong></a> for extended error information. 329 * </p> 330 */ ShellExecuteEx(ShellAPI.SHELLEXECUTEINFO lpExecInfo)331 boolean ShellExecuteEx(ShellAPI.SHELLEXECUTEINFO lpExecInfo); 332 333 /** 334 * SHGetSpecialFolderLocation function for getting PIDL reference to My Computer etc 335 * 336 * @param hwndOwner 337 * Reserved. 338 * @param nFolder 339 * A CSIDL value that identifies the folder of interest. 340 * @param ppidl 341 * 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. 342 * 343 * @return If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. 344 * 345 */ SHGetSpecialFolderLocation(WinDef.HWND hwndOwner, int nFolder, PointerByReference ppidl)346 HRESULT SHGetSpecialFolderLocation(WinDef.HWND hwndOwner, int nFolder, PointerByReference ppidl); 347 348 /** 349 * @param lpszFile 350 * Type: LPCTSTR<br> 351 * The name of an executable file, DLL, or icon file from which 352 * icons will be extracted. 353 * @param nIconIndex 354 * Type: int<br> 355 * The zero-based index of the first icon to extract. For 356 * example, if this value is zero, the function extracts the 357 * first icon in the specified file.<br> 358 * If this value is -1 and phiconLarge and phiconSmall are both 359 * NULL, the function returns the total number of icons in the 360 * specified file.<br> 361 * If the file is an executable file or DLL, the return value is 362 * the number of RT_GROUP_ICON resources.<br> 363 * If the file is an .ico file, the return value is 1. If this 364 * value is a negative number and either phiconLarge or 365 * phiconSmall is not NULL, the function begins by extracting the 366 * icon whose resource identifier is equal to the absolute value 367 * of nIconIndex. For example, use -3 to extract the icon whose 368 * resource identifier is 3. 369 * @param phiconLarge 370 * Type: HICON*<br> 371 * An array of icon handles that receives handles to the large 372 * icons extracted from the file. If this parameter is NULL, no 373 * large icons are extracted from the file. 374 * @param phiconSmall 375 * Type: HICON*<br> 376 * An array of icon handles that receives handles to the small 377 * icons extracted from the file. If this parameter is NULL, no 378 * small icons are extracted from the file. 379 * @param nIcons 380 * Type: UINT<br> 381 * The number of icons to be extracted from the file. 382 * @return Type: UINT <br> 383 * If the nIconIndex parameter is -1, the phiconLarge parameter is 384 * NULL, and the phiconSmall parameter is NULL, then the return 385 * value is the number of icons contained in the specified file. 386 * Otherwise, the return value is the number of icons successfully 387 * extracted from the file. 388 * @see <a href="https://msdn.microsoft.com/en-us/library/ms648069(VS.85).aspx">MSDN</a> 389 */ ExtractIconEx(String lpszFile, int nIconIndex, HICON[] phiconLarge, HICON[] phiconSmall, int nIcons)390 int ExtractIconEx(String lpszFile, int nIconIndex, HICON[] phiconLarge, HICON[] phiconSmall, int nIcons); 391 392 /** 393 * Retrieves the application-defined, explicit Application User Model ID (AppUserModelID) for the current process. 394 * 395 * @param ppszAppID 396 * A pointer that receives the address of the AppUserModelID assigned to the process. The caller is responsible for freeing this string with {@link Ole32#CoTaskMemFree} when it is no longer needed. 397 * @return If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. 398 * @see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/dd378419(v=vs.85).aspx">MSDN</a> 399 */ GetCurrentProcessExplicitAppUserModelID(PointerByReference ppszAppID)400 HRESULT GetCurrentProcessExplicitAppUserModelID(PointerByReference ppszAppID); 401 402 /** 403 * 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. 404 * 405 * @param appID 406 * The AppUserModelID to assign to the current process. 407 * @return If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. 408 * @see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/dd378422(v=vs.85).aspx">MSDN</a> 409 */ SetCurrentProcessExplicitAppUserModelID(WString appID)410 HRESULT SetCurrentProcessExplicitAppUserModelID(WString appID); 411 412 } 413 414