pinvoke.net: Edit: shlwapi.pathrelativepathto

@msdn=http://search.microsoft.com/search/results.aspx?qu=$$$
@pinvoke=http://pinvoke.net/$$$.htm

Summary: Creates a relative path from one file or folder to another.

!!!!C# Signature:
 [DllImport("shlwapi.dll", CharSet=CharSet.Auto)]
 static extern bool PathRelativePathTo(
         [Out] StringBuilder pszPath,
         [In] string pszFrom,
         [In] FileAttributes dwAttrFrom,
         [In] string pszTo,
         [In] FileAttributes dwAttrTo
 );
!!!!VB Signature:
 <DllImport("shlwapi.dll", CharSet:=CharSet.Auto)> _
 Public Shared Function PathRelativePathTo( _
     ByVal pszPath As StringBuilder, _
     ByVal pszFrom As String, _
     ByVal dwAttrFrom As Integer, _
     ByVal pszTo As String, _
     ByVal dwAttrTo As Integer) As Boolean
 End Function

!!!!VB Signature 2:
    ''' <summary>
    ''' Creates a relative path from one file or folder to another.
    ''' </summary>
    ''' <param name="pszPath">Receives the relative path</param>
    ''' <param name="pszFrom">Contains the path that defines the start of the relative path</param>
    ''' <param name="dwAttrFrom">The file attributes of <paramref name="pszFrom" />. If this value contains Directory, <paramref name="pszFrom" /> is assumed to be a directory; otherwise, <paramref name="pszFrom" /> is assumed to be a file</param>
    ''' <param name="pszTo">Contains the path that defines the endpoint of the relative path</param>
    ''' <param name="dwAttrTo">The file attributes of <paramref name="pszTo" />. If this value contains Directory, <paramref name="pszTo" /> is assumed to be a directory; otherwise, <paramref name="pszTo" /> is assumed to be a file</param>
    ''' <returns>TRUE if successful, or FALSE otherwise</returns>
    ''' <remarks>
    ''' This function takes a pair of paths and generates a relative path from one to the other. 
    ''' The paths do not have to be fully qualified, but they must have a common prefix, or the function will fail and return FALSE.
    ''' For example, let the starting point, pszFrom, be "c:\FolderA\FolderB\FolderC", and the ending point, pszTo, be "c:\FolderA\FolderD\FolderE". PathRelativePathTo will return the relative path from pszFrom to pszTo as: "..\..\FolderD\FolderE". You will get the same result if you set pszFrom to "\FolderA\FolderB\FolderC" and pszTo to "\FolderA\FolderD\FolderE". On the other hand, "c:\FolderA\FolderB" and "a:\FolderA\FolderD do not share a common prefix, and the function will fail. Note that "\\" is not considered a prefix and is ignored. If you set pszFrom to "\\FolderA\FolderB", and pszTo to "\\FolderC\FolderD", the function will fail.
    ''' </remarks>
    <DllImport("shlwapi.dll", CharSet:=CharSet.Auto)> _
    Public Shared Function PathRelativePathTo( _
        ByVal pszPath As StringBuilder, _
        ByVal pszFrom As String, _
        ByVal dwAttrFrom As Microsoft.VisualBasic.FileAttribute, _
        ByVal pszTo As String, _
        ByVal dwAttrTo As Microsoft.VisualBasic.FileAttribute) As Boolean
    End Function
!!!!User-Defined Types:
None.

!!!!Notes:
None.

!!!!Tips & Tricks:
The Microsoft.VisualBasic.FileAttribute enumeration can be used to specify the file attribute

!!!!Sample Code:
 const Int32 MAX_PATH = 260;
 StringBuilder str = new StringBuilder(MAX_PATH);
 Boolean bRet = PathRelativePathTo( 
         str,
         @"c:\a\b\path", FileAttributes.Directory,
         @"c:\a\x\y\file", FileAttributes.Normal
         );
 // Result: str.ToString() == @"..\..\x\y\file"
!!!!Alternative Managed API:
    public static string GetRelativePath(FileSystemInfo path1, FileSystemInfo path2) {
      if (path1 == null) throw new ArgumentNullException("path1");
      if (path2 == null) throw new ArgumentNullException("path2");

Func<FileSystemInfo, string> getFullName = delegate(FileSystemInfo path) {
        string fullName = path.FullName;

if (path is DirectoryInfo) {
          if (fullName[fullName.Length - 1] != Path.DirectorySeparatorChar) {
            fullName += Path.DirectorySeparatorChar;
          }
        }
        return fullName;
      };

string path1FullName = getFullName(path1);
      string path2FullName = getFullName(path2);

Uri uri1 = new Uri(path1FullName);
      Uri uri2 = new Uri(path2FullName);
      Uri relativeUri = uri1.MakeRelativeUri(uri2);

return Uri.UnescapeDataString(relativeUri.OriginalString);
    }
Do you know one?  Please contribute it!

Documentation: MSDN http://msdn.microsoft.com/en-us/library/bb773740(VS.85).aspx