mozilla
Your Search Results

    NS_NewNativeLocalFile

    « XPCOM API Reference

    Summary

    The NS_NewNativeLocalFile function creates an instance of nsILocalFile that provides a platform independent representation of a file path.

    #include "nsXPCOM.h"
    #include "nsILocalFile.h"
     
    nsresult NS_NewNativeLocalFile(
      const nsACString& aPath,
      PRBool aFollowLinks,
      nsILocalFile** aResult
    );
    

    Parameters

    aPath
    [in] A string object that specifies an absolute filesystem path. This string should be encoded using ASCII or the multibyte character coding corresponding to the native filesystem. This path does not need to reference an existing file. It is an error to pass a relative filesystem path.
    aFollowLinks
    [in] This attribute will determine if the nsILocalFile instance will automatically resolve symbolic links. This parameter has no effect on UNIX systems. On Windows, passing true causes shortcuts to be automatically resolved, and on MacOS, passing true causes finder aliases to be automatically resolved.
    aResult
    [out] A reference to the newly created nsILocalFile instance.

    Return Values

    The NS_NewNativeLocalFile function returns NS_OK if successful. Otherwise, it returns an error code.

    NS_ERROR_FILE_UNRECOGNIZED_PATH
    Indicates that the specified path is invalid. This error is returned if a relative file path is passed to NS_NewNativeLocalFile.

    Remarks

    On UNIX systems, the prefix "~/" is supported as a shorthand for the user's home directory. If you use this function on Windows 2000 or later, you would not be able to handle file names containing characters outside the default code page even though the OS has no problem dealing with them. Do not use this function (on Windows) unless it is guaranteed that the full path involved is always ASCII.

    Example Code

    // Create a local file that references c:\foo.txt
    nsresult rv;
    nsCOMPtr<nsILocalFile> file;
    rv = NS_NewNativeLocalFile(nsEmbedCString("c:\\foo.txt"), PR_FALSE,
                               getter_AddRefs(file));
    if (NS_FAILED(rv))
      return rv;
    

    Here, nsEmbedCString is used to convert the ASCII string literal to an object that can be passed as a const nsACString& parameter.

    History

    This function was finalized for Mozilla 1.0. See bug 129279 for details.

    See Also

    nsILocalFile, nsIFile

    Document Tags and Contributors

    Contributors to this page: Sheppy, Nickolay, Jshin, DarinFisher
    Last updated by: Sheppy,