Added Shell32.SHGetKnownFolderPath and corresponding constants

CHANGES.md

@@ -12,6 +12,7 @@ Features
 * Added Winspool monitor sample and updated Kernel32, WinBase, Winspool - [@wolftobias](https://github.com/wolftobias).
 * Added Some minor changes to MS Office samples Test and small changes to the MS Office samples Bug Fixes - [@wolftobias](https://github.com/wolftobias).
 * [#333](https://github.com/twall/jna/pull/333): Added `CoTaskMemAlloc`, `CoTaskMemRealloc` and `CoTaskMemFree` to `com.sun.jna.platform.win32.Ole32` - [@msteiger](https://github.com/msteiger).
+* [#334](https://github.com/twall/jna/pull/334): Added `com.sun.jna.platform.win32.Shell32.SHGetKnownFolderPath` and `KnownFolders` GUID constants - [@msteiger](https://github.com/msteiger).
 
 Bug Fixes
 ---------

contrib/platform/src/com/sun/jna/platform/win32/Shell32.java

@@ -13,6 +13,7 @@
 package com.sun.jna.platform.win32;
 
 import com.sun.jna.Native;
+import com.sun.jna.platform.win32.Guid.GUID;
 import com.sun.jna.platform.win32.WinDef.DWORD;
 import com.sun.jna.platform.win32.WinDef.HWND;
 import com.sun.jna.platform.win32.WinDef.INT_PTR;
@@ -65,6 +66,36 @@ public interface Shell32 extends ShellAPI, StdCallLibrary {
     HRESULT SHGetFolderPath(HWND hwndOwner, int nFolder, HANDLE hToken, DWORD dwFlags, 
     		char[] pszPath);
 
+    /**
+     * Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This function replaces
+     * {@link #SHGetFolderPath}. That older function is now simply a wrapper for SHGetKnownFolderPath.
+     * @param rfid A reference to the KNOWNFOLDERID (in {@link KnownFolders}) that identifies the folder.
+     * @param dwFlags Flags that specify special retrieval options. This value can be 0; otherwise, one or more of the
+     *        {@link ShlObj.KNOWN_FOLDER_FLAG} values.
+     * @param hToken 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.
+     * @param ppszPath 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 {@link Ole32#CoTaskMemFree}. The returned path does not include a trailing
+     *        backslash. For example, "C:\Users" is returned rather than "C:\Users\".
+     * @return Returns S_OK if successful, or an error value otherwise, including the following: 
+     *        <li>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).</li> 
+     *        <li>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.</li>
+     */
+    HRESULT SHGetKnownFolderPath(GUID rfid, int dwFlags, HANDLE hToken, PointerByReference ppszPath);
+
     /**
      * 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

contrib/platform/src/com/sun/jna/platform/win32/Shell32Util.java

@@ -13,9 +13,13 @@
 package com.sun.jna.platform.win32;
 
 import com.sun.jna.Native;
+import com.sun.jna.platform.win32.Guid.GUID;
 import com.sun.jna.platform.win32.WinDef.DWORD;
 import com.sun.jna.platform.win32.WinDef.HWND;
+import com.sun.jna.platform.win32.WinDef.LPVOID;
+import com.sun.jna.platform.win32.WinNT.HANDLE;
 import com.sun.jna.platform.win32.WinNT.HRESULT;
+import com.sun.jna.ptr.PointerByReference;
 
 /**
  * Shell32 Utility API.
@@ -56,6 +60,34 @@ public static String getFolderPath(HWND hwnd, int nFolder, DWORD dwFlags) {
 	public static String getFolderPath(int nFolder) {
 		return getFolderPath(null, nFolder, ShlObj.SHGFP_TYPE_CURRENT);
 	}
+
+    /**
+     * Retrieves the full path of a known folder identified by the folder's KNOWNFOLDERID. This function replaces 
+     * {@link #getFolderPath}. That older function is now simply a wrapper for getKnownFolderPath
+     * @param guid the KNOWNFOLDERS GUID as defined in {@link KnownFolders}
+     * @return the path of the known folder. The returned path does not include a trailing backslash. For example,
+     *        "C:\Users" is returned rather than "C:\Users\".
+     * @throws Win32Exception if the guid references a KNOWNFOLDERID which does not have a path (such as a folder marked
+     *        as KF_CATEGORY_VIRTUAL) or that the KNOWNFOLDERID is not present on the system. Not all KNOWNFOLDERID values are
+     *        present on all systems.
+     */
+    public static String getKnownFolderPath(GUID guid) throws Win32Exception
+    {
+        int flags = ShlObj.KNOWN_FOLDER_FLAG.NONE.getFlag();
+        PointerByReference outPath = new PointerByReference();
+        HANDLE token = null;
+        HRESULT hr = Shell32.INSTANCE.SHGetKnownFolderPath(guid, flags, token, outPath);
+
+        if (!W32Errors.SUCCEEDED(hr.intValue()))
+        {
+            throw new Win32Exception(hr);
+        }
+
+        String result = outPath.getValue().getWideString(0);
+        Ole32.INSTANCE.CoTaskMemFree(new LPVOID(outPath.getPointer().getLong(0)));
+
+        return result;
+    }
 
 	/**
      * Retrieves the path of a special folder, identified by its CSIDL.

contrib/platform/src/com/sun/jna/platform/win32/ShlObj.java

@@ -81,4 +81,102 @@ public interface ShlObj {
     int CSIDL_COMMON_OEM_LINKS = 0x003a; // Links to All Users OEM specific apps
     int CSIDL_CDBURN_AREA = 0x003b; // USERPROFILE\Local Settings\Application Data\Microsoft\CD Burning
     int CSIDL_COMPUTERSNEARME = 0x003d; // Computers Near Me (computered from Workgroup membership)
+
+    /**
+     * KnownFolder flags as used by SHGetKnownFolderPath, SHGetKnownFolderIDList and others.
+     * Microsoft Windows SDK 7.0A.
+     */
+    public enum KNOWN_FOLDER_FLAG
+    {
+        /**
+         * None
+         */
+        NONE(0x00000000),
+
+        /**
+         * Build a simple IDList (PIDL) This value can be used when you want to retrieve the file system path but do not
+         * specify this value if you are retrieving the localized display name of the folder because it might not
+         * resolve correctly.
+         */
+        SIMPLE_IDLIST(0x00000100),
+
+        /**
+         * Gets the folder's default path independent of the current location of its parent. KF_FLAG_DEFAULT_PATH must
+         * also be set.
+         */
+        NOT_PARENT_RELATIVE(0x00000200),
+
+        /**
+         * Gets the default path for a known folder. If this flag is not set, the function retrieves the current-and
+         * possibly redirected-path of the folder. The execution of this flag includes a verification of the folder's
+         * existence unless KF_FLAG_DONT_VERIFY is set.
+         */
+        DEFAULT_PATH(0x00000400),
+
+        /**
+         * Initializes the folder using its Desktop.ini settings. If the folder cannot be initialized, the function
+         * returns a failure code and no path is returned. This flag should always be combined with KF_FLAG_CREATE.
+         */
+        INIT(0x00000800),
+
+        /**
+         * Gets the true system path for the folder, free of any aliased placeholders such as %USERPROFILE%, returned by
+         * SHGetKnownFolderIDList and IKnownFolder::GetIDList. This flag has no effect on paths returned by
+         * SHGetKnownFolderPath and IKnownFolder::GetPath. By default, known folder retrieval functions and methods
+         * return the aliased path if an alias exists.
+         */
+        NO_ALIAS(0x00001000),
+
+        /**
+         * Stores the full path in the registry without using environment strings. If this flag is not set, portions of
+         * the path may be represented by environment strings such as %USERPROFILE%. This flag can only be used with
+         * SHSetKnownFolderPath and IKnownFolder::SetPath.
+         */
+        DONT_UNEXPAND(0x00002000),
+
+        /**
+         * Do not verify the folder's existence before attempting to retrieve the path or IDList. If this flag is not
+         * set, an attempt is made to verify that the folder is truly present at the path. If that verification fails
+         * due to the folder being absent or inaccessible, the function returns a failure code and no path is returned.
+         * If the folder is located on a network, the function might take a longer time to execute. Setting this flag
+         * can reduce that lag time.
+         */
+        DONT_VERIFY(0x00004000),
+
+        /**
+         * Forces the creation of the specified folder if that folder does not already exist. The security provisions
+         * predefined for that folder are applied. If the folder does not exist and cannot be created, the function
+         * returns a failure code and no path is returned. This value can be used only with the following functions and
+         * methods: 
+         * <li>SHGetKnownFolderPath</li> 
+         * <li>SHGetKnownFolderIDList</li> 
+         * <li>IKnownFolder::GetIDList</li>
+         * <li>IKnownFolder::GetPath</li> 
+         * <li>IKnownFolder::GetShellItem</li>
+         */
+        CREATE(0x00008000),
+        /**
+         * Introduced in Windows 7: When running inside an app container, or when providing an app container token, this
+         * flag prevents redirection to app container folders. Instead, it retrieves the path that would be returned
+         * where it not running inside an app container.
+         */
+        NO_APPCONTAINER_REDIRECTION(0x00010000),
+
+        /**
+         * Introduced in Windows 7. Return only aliased PIDLs. Do not use the file system path.
+         */
+        ALIAS_ONLY(0x80000000);
+
+        private int flag;
+
+        KNOWN_FOLDER_FLAG(int flag)
+        {
+            this.flag = flag;
+        }
+
+        public int getFlag()
+        {
+            return flag;
+        }
+    }
 }

contrib/platform/test/com/sun/jna/platform/win32/Shell32Test.java

@@ -15,10 +15,14 @@
 import junit.framework.TestCase;
 
 import com.sun.jna.Native;
+import com.sun.jna.platform.win32.Guid.GUID;
 import com.sun.jna.platform.win32.ShellAPI.APPBARDATA;
 import com.sun.jna.platform.win32.WinDef.DWORD;
+import com.sun.jna.platform.win32.WinDef.LPVOID;
 import com.sun.jna.platform.win32.WinDef.RECT;
 import com.sun.jna.platform.win32.WinDef.UINT_PTR;
+import com.sun.jna.platform.win32.WinNT.HANDLE;
+import com.sun.jna.platform.win32.WinNT.HRESULT;
 import com.sun.jna.ptr.PointerByReference;
 
 
@@ -127,4 +131,16 @@ public void testResizeDesktopFromTop() throws InterruptedException {
 
     }
 
+    public void testSHGetKnownFolderPath()
+    {
+        int flags = ShlObj.KNOWN_FOLDER_FLAG.NONE.getFlag();
+        PointerByReference outPath = new PointerByReference();
+        HANDLE token = null;
+        GUID guid = KnownFolders.FOLDERID_Fonts;
+        HRESULT hr = Shell32.INSTANCE.SHGetKnownFolderPath(guid, flags, token, outPath);
+
+        Ole32.INSTANCE.CoTaskMemFree(new LPVOID(outPath.getPointer().getLong(0)));
+
+        assertTrue(W32Errors.SUCCEEDED(hr.intValue()));
+    }
 }

contrib/platform/test/com/sun/jna/platform/win32/Shell32UtilTest.java

@@ -35,4 +35,42 @@ public void testGetFolderPath() {
 	public final void testGetSpecialFolderPath() {
         assertFalse(Shell32Util.getSpecialFolderPath(ShlObj.CSIDL_APPDATA, false).isEmpty());
     }
+
+    public void testGetKnownFolderPath()
+    {
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Fonts));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Desktop));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Startup));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Programs));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_StartMenu));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Recent));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_SendTo));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Documents));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Favorites));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_NetHood));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_PrintHood));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Templates));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_CommonStartup));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_CommonAdminTools));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_CDBurning));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Music));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_SavedGames));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_SavedSearches));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_AdminTools));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_ProgramFiles));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_ProgramData));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_ProgramFilesCommon));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_ProgramFilesCommonX86));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Programs));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Windows));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Public));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_PublicDesktop));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Links));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_LocalAppData));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_Libraries));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_RoamingAppData));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_UserProfiles));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_UserProgramFiles));
+        assertNotNull(Shell32Util.getKnownFolderPath(KnownFolders.FOLDERID_UserProgramFilesCommon));
+    }
 }