NS_NewNativeLocalFile

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