NS_NewLocalFile

Summary

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

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

Parameters

aPath: [in] A UTF-16 string object that specifies an absolute filesystem path. 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_NewLocalFile 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_NewLocalFile.

Remarks

On UNIX systems, the prefix "~/" is supported as a shorthand for the user's home directory.

Example Code

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

Note: GCC requires the -fshort-wchar option to compile this example since PRUnichar is an unsigned short. This example should compile by default under MSVC.

nsEmbedString is used to convert the UCS-2 character array to an object that can be passed as a const nsAString& parameter.

History

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