GenXdev.Windows

1.272.2025

Functions/GenXdev.Windows/Get-KnownFolderPath.ps1

                                <##############################################################################

Part of PowerShell module : GenXdev.Windows

Original cmdlet filename  : Get-KnownFolderPath.ps1

Original author           : René Vaessen / GenXdev

Version                   : 1.272.2025

################################################################################

MIT License

Copyright 2021-2025 GenXdev

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

################################################################################>

###############################################################################

<#

.SYNOPSIS

Gets the path of a Windows known folder using the Windows Shell32 API.

.DESCRIPTION

Retrieves the path of a specified Windows known folder using the Shell32 API's

SHGetKnownFolderPath function. This method is more reliable than using

environment variables as it works consistently across different Windows versions

and language settings. Supports all standard Windows known folders like

Documents, Downloads, AppData etc.

.PARAMETER KnownFolder

Specifies the name of the Windows known folder to retrieve. Must be one of the

predefined folder names like 'Documents', 'Downloads', etc. The function will

return the full path to this folder.

.EXAMPLE

Get-KnownFolderPath -KnownFolder 'Documents'

Returns: C:\Users\Username\Documents

.EXAMPLE

folder Downloads

Returns: C:\Users\Username\Downloads using the alias

.EXAMPLE

cd (folder Desktop)

Changes to the Desktop folder using the alias

#>

function Get-KnownFolderPath {

    [CmdletBinding()]

    [Alias('folder')]

    param (

        ########################################################################

        [Parameter(

            Mandatory = $true,

            Position = 0,

            HelpMessage = 'The Windows known folder name to get the path for'

        )]

        [ValidateSet('3DObjects', 'AddNewPrograms', 'AdminTools', 'AppUpdates',

            'CDBurning', 'ChangeRemovePrograms', 'CommonAdminTools',

            'CommonOEMLinks', 'CommonPrograms', 'CommonStartMenu',

            'CommonStartup', 'CommonTemplates', 'ComputerFolder',

            'ConflictFolder', 'ConnectionsFolder', 'Contacts',

            'ControlPanelFolder', 'Cookies', 'Desktop', 'Documents', 'Downloads',

            'Favorites', 'Fonts', 'Games', 'GameTasks', 'History',

            'InternetCache', 'InternetFolder', 'Links', 'LocalAppData',

            'LocalAppDataLow', 'LocalizedResourcesDir', 'Music', 'NetHood',

            'NetworkFolder', 'OriginalImages', 'PhotoAlbums', 'Pictures',

            'Playlists', 'PrintersFolder', 'PrintHood', 'Profile',

            'ProgramData', 'ProgramFiles', 'ProgramFilesX64', 'ProgramFilesX86',

            'ProgramFilesCommon', 'ProgramFilesCommonX64',

            'ProgramFilesCommonX86', 'Programs', 'Public', 'PublicDesktop',

            'PublicDocuments', 'PublicDownloads', 'PublicGameTasks',

            'PublicMusic', 'PublicPictures', 'PublicVideos', 'QuickLaunch',

            'Recent', 'RecycleBinFolder', 'ResourceDir', 'RoamingAppData',

            'SampleMusic', 'SamplePictures', 'SamplePlaylists', 'SampleVideos',

            'SavedGames', 'SavedSearches', 'SEARCH_CSC', 'SEARCH_MAPI',

            'SearchHome', 'SendTo', 'SidebarDefaultParts', 'SidebarParts',

            'StartMenu', 'Startup', 'SyncManagerFolder', 'SyncResultsFolder',

            'SyncSetupFolder', 'System', 'SystemX86', 'Templates',

            'TreeProperties', 'UserProfiles', 'UsersFiles', 'Videos',

            'Windows')]

        [string]$KnownFolder

        ########################################################################

    )

    begin {

        # define known folder guids for windows shell32 api

        $knownFolders = @{

            '3DObjects'             = '31C0DD25-9439-4F12-BF41-7FF4EDA38722';

            'AddNewPrograms'        = 'de61d971-5ebc-4f02-a3a9-6c82895e5c04';

            'AdminTools'            = '724EF170-A42D-4FEF-9F26-B60E846FBA4F';

            'AppUpdates'            = 'a305ce99-f527-492b-8b1a-7e76fa98d6e4';

            'CDBurning'             = '9E52AB10-F80D-49DF-ACB8-4330F5687855';

            'ChangeRemovePrograms'  = 'df7266ac-9274-4867-8d55-3bd661de872d';

            'CommonAdminTools'      = 'D0384E7D-BAC3-4797-8F14-CBA229B392B5';

            'CommonOEMLinks'        = 'C1BAE2D0-10DF-4334-BEDD-7AA20B227A9D';

            'CommonPrograms'        = '0139D44E-6AFE-49F2-8690-3DAFCAE6FFB8';

            'CommonStartMenu'       = 'A4115719-D62E-491D-AA7C-E74B8BE3B067';

            'CommonStartup'         = '82A5EA35-D9CD-47C5-9629-E15D2F714E6E';

            'CommonTemplates'       = 'B94237E7-57AC-4347-9151-B08C6C32D1F7';

            'ComputerFolder'        = '0AC0837C-BBF8-452A-850D-79D08E667CA7';

            'ConflictFolder'        = '4bfefb45-347d-4006-a5be-ac0cb0567192';

            'ConnectionsFolder'     = '6F0CD92B-2E97-45D1-88FF-B0D186B8DEDD';

            'Contacts'              = '56784854-C6CB-462b-8169-88E350ACB882';

            'ControlPanelFolder'    = '82A74AEB-AEB4-465C-A014-D097EE346D63';

            'Cookies'               = '2B0F765D-C0E9-4171-908E-08A611B84FF6';

            'Desktop'               = 'B4BFCC3A-DB2C-424C-B029-7FE99A87C641';

            'Documents'             = 'FDD39AD0-238F-46AF-ADB4-6C85480369C7';

            'Downloads'             = '374DE290-123F-4565-9164-39C4925E467B';

            'Favorites'             = '1777F761-68AD-4D8A-87BD-30B759FA33DD';

            'Fonts'                 = 'FD228CB7-AE11-4AE3-864C-16F3910AB8FE';

            'Games'                 = 'CAC52C1A-B53D-4edc-92D7-6B2E8AC19434';

            'GameTasks'             = '054FAE61-4DD8-4787-80B6-090220C4B700';

            'History'               = 'D9DC8A3B-B784-432E-A781-5A1130A75963';

            'InternetCache'         = '352481E8-33BE-4251-BA85-6007CAEDCF9D';

            'InternetFolder'        = '4D9F7874-4E0C-4904-967B-40B0D20C3E4B';

            'Links'                 = 'bfb9d5e0-c6a9-404c-b2b2-ae6db6af4968';

            'LocalAppData'          = 'F1B32785-6FBA-4FCF-9D55-7B8E7F157091';

            'LocalAppDataLow'       = 'A520A1A4-1780-4FF6-BD18-167343C5AF16';

            'LocalizedResourcesDir' = '2A00375E-224C-49DE-B8D1-440DF7EF3DDC';

            'Music'                 = '4BD8D571-6D19-48D3-BE97-422220080E43';

            'NetHood'               = 'C5ABBF53-E17F-4121-8900-86626FC2C973';

            'NetworkFolder'         = 'D20BEEC4-5CA8-4905-AE3B-BF251EA09B53';

            'OriginalImages'        = '2C36C0AA-5812-4b87-BFD0-4CD0DFB19B39';

            'PhotoAlbums'           = '69D2CF90-FC33-4FB7-9A0C-EBB0F0FCB43C';

            'Pictures'              = '33E28130-4E1E-4676-835A-98395C3BC3BB';

            'Playlists'             = 'DE92C1C7-837F-4F69-A3BB-86E631204A23';

            'PrintersFolder'        = '76FC4E2D-D6AD-4519-A663-37BD56068185';

            'PrintHood'             = '9274BD8D-CFD1-41C3-B35E-B13F55A758F4';

            'Profile'               = '5E6C858F-0E22-4760-9AFE-EA3317B67173';

            'ProgramData'           = '62AB5D82-FDC1-4DC3-A9DD-070D1D495D97';

            'ProgramFiles'          = '905e63b6-c1bf-494e-b29c-65b732d3d21a';

            'ProgramFilesX64'       = '6D809377-6AF0-444b-8957-A3773F02200E';

            'ProgramFilesX86'       = '7C5A40EF-A0FB-4BFC-874A-C0F2E0B9FA8E';

            'ProgramFilesCommon'    = 'F7F1ED05-9F6D-47A2-AAAE-29D317C6F066';

            'ProgramFilesCommonX64' = '6365D5A7-0F0D-45E5-87F6-0DA56B6A4F7D';

            'ProgramFilesCommonX86' = 'DE974D24-D9C6-4D3E-BF91-F4455120B917';

            'Programs'              = 'A77F5D77-2E2B-44C3-A6A2-ABA601054A51';

            'Public'                = 'DFDF76A2-C82A-4D63-906A-5644AC457385';

            'PublicDesktop'         = 'C4AA340D-F20F-4863-AFEF-F87EF2E6BA25';

            'PublicDocuments'       = 'ED4824AF-DCE4-45A8-81E2-FC7965083634';

            'PublicDownloads'       = '3D644C9B-1FB8-4f30-9B45-F670235F79C0';

            'PublicGameTasks'       = 'DEBF2536-E1A8-4c59-B6A2-414586476AEA';

            'PublicMusic'           = '3214FAB5-9757-4298-BB61-92A9DEAA44FF';

            'PublicPictures'        = 'B6EBFB86-6907-413C-9AF7-4FC2ABF07CC5';

            'PublicVideos'          = '2400183A-6185-49FB-A2D8-4A392A602BA3';

            'QuickLaunch'           = '52a4f021-7b75-48a9-9f6b-4b87a210bc8f';

            'Recent'                = 'AE50C081-EBD2-438A-8655-8A092E34987A';

            'RecycleBinFolder'      = 'B7534046-3ECB-4C18-BE4E-64CD4CB7D6AC';

            'ResourceDir'           = '8AD10C31-2ADB-4296-A8F7-E4701232C972';

            'RoamingAppData'        = '3EB685DB-65F9-4CF6-A03A-E3EF65729F3D';

            'SampleMusic'           = 'B250C668-F57D-4EE1-A63C-290EE7D1AA1F';

            'SamplePictures'        = 'C4900540-2379-4C75-844B-64E6FAF8716B';

            'SamplePlaylists'       = '15CA69B3-30EE-49C1-ACE1-6B5EC372AFB5';

            'SampleVideos'          = '859EAD94-2E85-48AD-A71A-0969CB56A6CD';

            'SavedGames'            = '4C5C32FF-BB9D-43b0-B5B4-2D72E54EAAA4';

            'SavedSearches'         = '7d1d3a04-debb-4115-95cf-2f29da2920da';

            'SEARCH_CSC'            = 'ee32e446-31ca-4aba-814f-a5ebd2fd6d5e';

            'SEARCH_MAPI'           = '98ec0e18-2098-4d44-8644-66979315a281';

            'SearchHome'            = '190337d1-b8ca-4121-a639-6d472d16972a';

            'SendTo'                = '8983036C-27C0-404B-8F08-102D10DCFD74';

            'SidebarDefaultParts'   = '7B396E54-9EC5-4300-BE0A-2482EBAE1A26';

            'SidebarParts'          = 'A75D362E-50FC-4fb7-AC2C-A8BEAA314493';

            'StartMenu'             = '625B53C3-AB48-4EC1-BA1F-A1EF4146FC19';

            'Startup'               = 'B97D20BB-F46A-4C97-BA10-5E3608430854';

            'SyncManagerFolder'     = '43668BF8-C14E-49B2-97C9-747784D784B7';

            'SyncResultsFolder'     = '289a9a43-be44-4057-a41b-587a76d7e7f9';

            'SyncSetupFolder'       = '0F214138-B1D3-4a90-BBA9-27CBC0C5389A';

            'System'                = '1AC14E77-02E7-4E5D-B744-2EB1AE5198B7';

            'SystemX86'             = 'D65231B0-B2F1-4857-A4CE-A8E7C6EA7D27';

            'Templates'             = 'A63293E8-664E-48DB-A079-DF759E0509F7';

            'TreeProperties'        = '5b3749ad-b49f-49c1-83eb-15370fbd4882';

            'UserProfiles'          = '0762D272-C50A-4BB0-A382-697DCD729B80';

            'UsersFiles'            = 'f3ce0f7c-4901-4acc-8648-d5d44b04ef8f';

            'Videos'                = '18989B1D-99B5-455B-841C-AB7C74E4DDFC';

            'Windows'               = 'F38BF404-1D43-42F2-9305-67DE0B28FC23';

        }

        # check if the windows api type is already defined in the current session

        $type = ([System.Management.Automation.PSTypeName]'Win32.Shell32API').Type

        if (-not $type) {

            Microsoft.PowerShell.Utility\Write-Verbose (

                'Defining Windows Shell32 API function'

            )

            # define the p/invoke signature for shgetknownfolderpath

            $signature = @'

[DllImport("shell32.dll")]

public extern static int SHGetKnownFolderPath(

    ref Guid folderId,

    uint flags,

    IntPtr token,

    [MarshalAs(UnmanagedType.LPWStr)] out string pszPath);

'@

            # add the shell32 api function definition as a new .net type

            $type = Microsoft.PowerShell.Utility\Add-Type `

                -MemberDefinition $signature `

                -Namespace 'Win32' `

                -Name 'Shell32API' `

                -PassThru

        }

    }

    process {

        Microsoft.PowerShell.Utility\Write-Verbose (

            "Getting path for known folder: $KnownFolder"

        )

        # convert the guid string to a guid object

        $folderGuid = Microsoft.PowerShell.Utility\New-Object Guid `

            $KnownFolders[$KnownFolder]

        # create a reference variable to store the output path

        [string]$path = $null

        # call the windows api to retrieve the folder path

        $code = $type::SHGetKnownFolderPath([ref]$folderGuid, 0, 0, [ref]$path)

        # check if the api call was successful and return the path

        if ($code -eq 0) {

            return $path

        }

        Microsoft.PowerShell.Utility\Write-Verbose (

            "Failed to get path for: $KnownFolder (code: $code)"

        )

        return $null

    }

    end {

    }

}