nsILocalFile

Implemented by: @mozilla.org/file/local;1. To create an instance, use:

var localFile = Components.classes["@mozilla.org/file/local;1"]
                .createInstance(Components.interfaces.nsILocalFile);

Method overview

Attributes

Constants

Methods

Appends a relative, native character encoding, path to the current path of the nsILocalFile object.

void appendRelativeNativePath(
  in ACString relativeFilePath
);

Parameters

relativeFilePath

A native relative path. For security reasons, this cannot contain '..' or cannot start with a directory separator '.'. Must be in the native file system character set.

Exceptions thrown

NS_ERROR_FILE_UNRECOGNIZED_PATH

Indicates that relativeFilePath incorrectly begins with a path separator character or otherwise contains invalid characters.

appendRelativePath()

Appends a relative native path to the current path of the nsILocalFile object.

void appendRelativePath(
  in AString relativeFilePath
);

Parameters

relativeFilePath

A native relative path. For security reasons, this cannot contain '..' or cannot start with a directory separator '.' .

Exceptions thrown

NS_ERROR_FILE_UNRECOGNIZED_PATH

Indicates that relativeFilePath incorrectly begins with a path separator character or otherwise contains invalid characters.

getRelativeDescriptor()

Returns a relative file path in an opaque, cross platform format. It is therefore not a native path.

ACString getRelativeDescriptor(
  in nsILocalFile fromFile
);

Parameters

fromFile

The file from which the descriptor is relative. There is no defined result if this parameter is null.

Return value

An opaque string value with undefined character encoding. This string is not intended for display to users.

The result returned from this method may be used with setRelativeDescriptor() to initialize a nsILocalFile instance.

initWithFile()

Initializes this object with another file.

void initWithFile(
  in nsILocalFile aFile
);

Parameters

aFile

The file this becomes equivalent to.

Used to set the full path that this nsILocalFile references. All current settings will be reset.

void initWithNativePath(
  in ACString filePath
);

Parameters

filePath

A string that specifies a platform-specific, full path to a file or directory. Must be in the native file system character set.

Exceptions thrown

NS_ERROR_FILE_UNRECOGNIZED_PATH

Indicates that FilePath is not an absolute file path.

initWithPath()

Used to set the full path that this nsILocalFile references. All current settings will be reset.

void initWithPath(
  in AString filePath
);

Parameters

filePath

A string that specifies a platform-specific, full path to a file or directory.

Exceptions thrown

NS_ERROR_FILE_UNRECOGNIZED_PATH

Indicates that FilePath is not an absolute file path.

launch()

Requests that the operating system attempt to open this file.

void launch();

Parameters

None.

Returns the result of PR_LoadLibrary() on the file. The caller is responsible for calling PR_UnloadLibrary() on the result.

PRLibraryStar load();

Parameters

None.

Return value

A pointer to a PRLibrary.

Example

#include "prlink.h"
#include "nsError.h"
#include "nsILocalFile.h"

// Load the DLL corresponding to the given nsILocalFile...

nsresult LoadDLL(nsILocalFile *aLocalFile)
{
  PRLibrary *dll;
  nsresult rv = aLocalFile->Load(&dll);
  if (NS_FAILED(rv))
    return rv;

  // Do something with the library now that it is open...

  PR_FreeLibrary(dll);
  return NS_OK;
}

Returns the result of fopen() on the file. The caller is responsible for calling fclose() on the result.

FILE openANSIFileDesc(
  in string mode
);

Parameters

mode

An ANSI file open mode string, which will be passed to fopen().

Return value

A pointer to an ANSI FILE type.

Example

#include <stdio.h>
#include "nsError.h"
#include "nsILocalFile.h"

// Read the contents of a nsILocalFile...

nsresult ReadLocalFile(nsILocalFile *aLocalFile)
{
  FILE *fp;
  nsresult rv = aLocalFile->OpenANSIFileDesc("r", &fp);
  if (NS_FAILED(rv))
    return rv;

  char buf[512];
  size_t n;
   
  while ((n = fread(buf, sizeof(buf), 1, fp)) > 0)
  {
    // Do something with n-byte block of data from file...
  }

  if (ferror(fp) != 0)
    rv = NS_ERROR_UNEXPECTED;

  fclose(fp);
  return rv;
}

Returns the result of PR_Open() on the file. The caller is responsible for calling PR_Close() on the result.

PRFileDescStar openNSPRFileDesc(
  in long flags,
  in long mode
);

Parameters

flags

The PR_Open() flags from nsprpub/pr/include/prio.h, plus optionally DELETE_ON_CLOSE. DELETE_ON_CLOSE may be implemented by removing the file (by path name) immediately after opening it, so beware of possible races; the file should be exclusively owned by this process.

A bitwise combination of the following open flags:

• PR_RDONLY Open for reading only.
• PR_WRONLY Open for writing only.
• PR_RDWR Open for reading and writing.
• PR_CREATE_FILE If the file does not exist, the file is created. If the file exists, this flag has no effect.
• PR_APPEND The file pointer is set to the end of the file prior to each write.
• PR_TRUNCATE If the file exists, its length is truncated to 0.
• PR_SYNC If set, each write will wait for both the file data and file status to be physically updated.
• PR_EXCL With PR_CREATE_FILE, if the file does not exist, the file is created. If the file already exists, no action and null is returned.
• DELETE_ON_CLOSE File will be deleted when closed.

mode

A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.

Return value

If the file is successfully opened, returns a pointer to the PRFileDesc created for the newly opened file. Returns a null pointer if the open failed.

Example

#include "prio.h"
#include "nsError.h"
#include "nsILocalFile.h"

// Read the contents of a nsILocalFile...

nsresult ReadLocalFile(nsILocalFile *aLocalFile)
{
  PRFileDesc *fd;
  nsresult rv = aLocalFile->OpenNSPRFileDesc(PR_RDONLY, 0, &fd);
  if (NS_FAILED(rv))
    return rv;

  char buf[512];
  PRInt32 n;
   
  while ((n = PR_Read(fd, buf, sizeof(buf))) > 0)
  {
    // Do something with n-byte block of data from file...
  }

  if (n < 0)
    rv = NS_ERROR_UNEXPECTED;

  PR_Close(fd);
  return rv;
}

reveal()

Ask the operating system to open the folder which contains this file or folder. This routine only works on platforms which support the ability to open a folder. See the note in the remarks below.

void reveal();

Parameters

None.

setRelativeDescriptor()

Initializes the file to the location relative to fromFile using a string returned by getRelativeDescriptor().

void setRelativeDescriptor(
  in nsILocalFile fromFile,
  in ACString relativeDesc
);

Parameters

fromFile

The file to which the descriptor is relative.

relativeDesc

The relative descriptor obtained from getRelativeDescriptor().

Remarks

The methods initWithNativePath() and appendRelativeNativePath() take string valued parameters that are encoded using the native character encoding. That means, you cannot deal with files whose name contain characters outside the default code page on Windows even though Windows 2000 or later has no problem with them. Therefore, never use these functions unless you are absolutely sure that the path passed to them is always ASCII-only. See nsIFile for more information on the native character encoding.

See also

• nsIFile