Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

SHGetKnownFolderPath (shell32)
 
.
Summary

C# Signature:

[DllImport("shell32.dll")]
static extern int SHGetKnownFolderPath(
    [MarshalAs(UnmanagedType.LPStruct)] Guid rfid,
    uint dwFlags,
    IntPtr hToken,
    out IntPtr ppszPath); // must be freed with Marshal.FreeCoTaskMem

C# Signature with marshaling:

[DllImport("shell32.dll", CharSet = CharSet.Unicode, ExactSpelling = true, PreserveSig = false)]
static extern string SHGetKnownFolderPath(
    [MarshalAs(UnmanagedType.LPStruct)] Guid rfid,
    uint dwFlags,
    IntPtr hToken = default);

VB Signature:

<DllImport("shell32.dll")> _
Shared Function SHGetKnownFolderPath(
    <MarshalAs(UnmanagedType.LPStruct)> ByVal rfid As Guid,
    ByVal dwFlags As UInteger,
    ByVal hToken As IntPtr,
    ByRef ppszPath As IntPtr ' must be freed with Marshal.FreeCoTaskMem
    ) As Integer
End Function

VB Signature with marshaling:

<DllImport("shell32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True, PreserveSig:=False)>
Shared Function SHGetKnownFolderPath(
    <MarshalAs(UnmanagedType.LPStruct)> ByVal rfid As Guid,
    ByVal dwFlags As UInteger,
    ByVal hToken As IntPtr
    ) As String
End Function

User-Defined Types:

The list of values for the rfid Guid are available on KNOWNFOLDERID.

Alternative Managed API:

Notes:

  • If you do not use the marshaling version, you convert the returned ppszPath to a string with Marshal.PtrStringToUni. You must always call Marshal.FreeCoTaskMem on it afterwards, even if the method returns a failure code.
  • If you use the marshaling version, which automatically throws exceptions if the method returns a failure code, the failure code to exception mapping is available here: https://docs.microsoft.com/en-us/dotnet/framework/interop/how-to-map-hresults-and-exceptions
  • Not all folders are available on every system (for example, the playlists folder). Check the returned failure code or exception.
  • This returns the internal / actual file system path. The folder name displayed in the File Explorer may be localized, e.g. the Playlists folder showing as "Musikwiedergabelisten" on a German system. To retrieve the localized name, instantiate an IShellItem with SHGetKnownFolderItem, and call its GetDisplayName method.

Sample Code (C#):

// C#
using System.Runtime.InteropServices;

public static string? GetKnownFolderPath(Guid folderGuid)
{
    IntPtr ppszPath = default;
    try
    {
        int hr = SHGetKnownFolderPath(folderGuid, 0, IntPtr.Zero, out ppszPath);
        Marshal.ThrowExceptionForHR(hr); // alternatively, check success with hr >= 0
        return Marshal.PtrToStringUni(ppszPath);
    }
    finally
    {
        Marshal.FreeCoTaskMem(ppszPath);
    }
}

Sample Code with marshaling (C#):

// C#
public static string GetKnownFolderPath(Guid folderGuid)
{
    return SHGetKnownFolderPath(folderGuid, 0);
}

Sample Code (VB.NET):

' VB.NET
Public Shared Function GetKnownFolderPath(ByVal folderGuid As Guid) As String
    Dim ppszPath As IntPtr
    Try
        Dim hr As Integer = SHGetKnownFolderPath(folderGuid, 0, IntPtr.Zero, ppszPath)
        Marshal.ThrowExceptionForHR(hr) ' alternatively, check success with hr >= 0
        Return Marshal.PtrToStringUni(ppszPath)
    Finally
        Marshal.FreeCoTaskMem(ppszPath)
    End Try
End Function

Sample Code with marshaling (VB.NET):

' VB.NET
Public Shared Function GetKnownFolderPath(ByVal folderGuid As Guid) As String
    Return SHGetKnownFolderPath(folderGuid, 0, IntPtr.Zero)
End Function

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version
Revisions