gecko-dev/xpcom/io/nsIFile.idl
brendan%mozilla.org a791fb2253 Fixes to use atomic rename(2) if possible in nsLocalFile::MoveTo (33098, r=?),
plus a bunch of other fixes and cleanups:

- Fix comment misstatements of fact in nsIFile.idl, improve style slightly.
- Fix typo in comment in nsILocalFile.idl.
- Avoid gratuitous nsCString and nsXPIDLCString copy-constructions, which
  entail malloc'ing, in nsLocalFileUnix.cpp's CopyTo and GetParent methods.
  But do use nsXPIDLCString instead of raw nsMemory::Alloc/Free.
- Get rid of unnecessary mLL_II2L and mLL_L2II macros, use "prlong.h" API only.
  Also use the LL_* macros consistently in case a Unix lacking long long type
  support wants to use this code.
* BTW, the "Date" methods should be renamed to use "Time" instead -- after all
  PRTime is the type, and traditionally "time" refers to the time-number, a
  scalar independent of one's position on the surface of the earth, while
  "date" refers to a struct full of locale-specific information derived from
  time and some "environment" variables such as DST.  Can we rename these
  nsIFile methods before Mozilla 0.9 / Netscape 6?
- Use CHECK_mPath consistently and first, before any assertions relating to
  arguments (which logically come after the 'this' parameter CHECK_mPath is
  making assertions about).
- Use nsCOMPtr for singly-inheriting implementations of XPCOM interfaces, to
  avoid scary-when-scaled 0-refcnt instances from being handled (these all
  got a ref via QI or equivalent soon enough, but you never know).  This also
  removed some naked deletes.
- Canonize all paths copied into mPath to lack trailing slashes, so we don't
  need to strip trailing slashes elsewhere, in higher-frequency methods (you
  set path less often than you get it or a substring of it).
- ssize_t for strlen return values.
- Since shaver used a function pointer to consolidate creat/mkdir logic, but
  didn't fold the necessary close of the new fd returned by non-failing creat
  into the pointed-at function, I did that.
- AppendRelativePath forbids .. as a component (bounded by / or beginning or
  end of string on either side), not just in the middle of fragment (so that
  foo..bar is not an illegal relative pathname -- it should not be).  BTW,
  what the heck is the difference between NS_ERROR_FILE_UNRECOGNIZED_PATH and
  ...INVALID_PATH?
- SetLeafName was overallocating the new pathname buffer by failing to subtract
  the old leafname's length.
- CopyTo was failing to return an NSRESULT_FOR_ERRNO(), it just called that
  macro on a line by itself -- eek!  It also contained redundant if (newFD
  == nsnull) {...} cleanup code, it did a useless PR_GetFileInfo call, and it
  leaked FDs on read or write error.
- Implemented CopyToFollowingLinks as a forwarded call to CopyTo, Unix does
  not support "copying" a symlink via normal file i/o.  Should we instead
  lstat in CopyTo and if a link is the source of the copy, do readlink and
  then symlink?
- Fixed the readlink method (GetTarget) to null-terminate the link string in
  the out parameter (readlink does not do that for you).
- Lots of little nsnull vs. NULL vs. 0, == and != applied to boolean or null
  literals, white-space, indentation, bracing, comment, and sloppy code order
  (e.g., declaring an initialized variable that's not used till after early
  returns) fixes.  Also invert some return logic so that NS_OK is the normal,
  least indented, final return.
2000-09-19 00:22:41 +00:00

342 lines
11 KiB
Plaintext

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
* The contents of this file are subject to the Netscape Public
* License Version 1.1 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.mozilla.org/NPL/
*
* Software distributed under the License is distributed on an "AS
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
* implied. See the License for the specific language governing
* rights and limitations under the License.
*
* The Original Code is Mozilla Communicator client code,
* released March 31, 1998.
*
* The Initial Developer of the Original Code is Netscape Communications
* Corporation. Portions created by Netscape are
* Copyright (C) 1998-1999 Netscape Communications Corporation. All
* Rights Reserved.
*
* Contributor(s):
* Doug Turner <dougt@netscape.com>
* Christopher Blizzard <blizzard@mozilla.org>
*/
// This is the only correct cross-platform way to specify a file.
// Strings are not such a way. If you grew up on windows or unix, you
// may think they are. Welcome to reality.
#include "nsISupports.idl"
interface nsISimpleEnumerator;
[scriptable, uuid(c8c0a080-0868-11d3-915f-d9d889d48e3c)]
interface nsIFile : nsISupports
{
/**
* Create Types
*
* NORMAL_FILE_TYPE - A normal file.
* DIRECTORY_TYPE - A directory/folder.
*/
const unsigned long NORMAL_FILE_TYPE = 0;
const unsigned long DIRECTORY_TYPE = 1;
/**
* appendPath
*
* This function is used for constructing a descendant of the
* current nsIFile.
*
* @param relativePath
* A string which is intented to be a child node of the
* nsIFile.
*/
void append([const] in string node);
void appendUnicode([const] in wstring node);
/**
* Normalize the pathName (e.g. removing .. and . components on Unix).
*/
void normalize();
/**
* create
*
* This function will create a new file or directory in the
* file system. Any nodes that have not been created or
* resolved, will be. If the file or directory already
* exists create() will return NS_ERROR_FILE_ALREADY_EXISTS.
*
* @param type
* This specifies the type of file system object
* to be made. The only two types at this time
* are file and directory which are defined above.
* If the type is unrecongnized, we will return an
* error (NS_ERROR_FILE_UNKNOWN_TYPE).
*
* @param permissions
* The unix style octal permissions. This may
* be ignored on systems that do not need to do
* permissions.
*/
void create(in unsigned long type, in unsigned long permissions);
/**
* Accessor to the leaf name of the file itself.
*/
attribute string leafName;
attribute wstring unicodeLeafName;
/**
* copyTo
*
* This will copy this file to the specified newParentDir.
* If a newName is specified, the file will be renamed.
* If 'this' is not created we will return an error
* (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
*
* copyTo will NOT resolve aliases/shortcuts during the copy.
*
* @param newParentDir
* This param is the destination directory. If the
* newParentDir is null, copyTo() will use the parent
* directory of this file. If the newParentDir is not
* null and is not a directory, an error will be
* returned (NS_ERROR_FILE_DESTINATION_NOT_DIR)
*
* @param newName
* This param allows you to specify a new name for
* the file to be copied. This param may be null, in
* which case the current leaf name will be used.
*
*/
void copyTo(in nsIFile newParentDir, [const] in string newName);
void copyToUnicode(in nsIFile newParentDir, [const] in wstring newName);
/**
* copyToFollowingLinks
*
* This function is identical to copyTo except it, as
* the name implies, follows symbolic links. Some OSes
* such as Unix and Linux always follow symbolic links
* when copying.
*/
void copyToFollowingLinks(in nsIFile newParentDir, [const] in string newName);
void copyToFollowingLinksUnicode(in nsIFile newParentDir, [const] in wstring newName);
/**
* moveTo
*
* This will move this file to the specified newParentDir.
* If a newName is specified, the file will be renamed.
* If 'this' is not created we will return an error
* (NS_ERROR_FILE_TARGET_DOES_NOT_EXIST).
*
* moveTo will NOT resolve aliases/shortcuts during the copy.
* moveTo will do the right thing and allow copies across
* volumes.
*
* @param newParentDir
* This param is the destination directory. If the
* newParentDir is null, moveTo() will rename the file
* within its current directory. If the newParentDir is
* not null and does not name a directory, an error will
* be returned (NS_ERROR_FILE_DESTINATION_NOT_DIR)
*
* @param newName
* This param allows you to specify a new name for
* the file to be moved. This param may be null, in
* which case the current leaf name will be used.
*
*/
void moveTo(in nsIFile newParentDir, [const] in string newName);
void moveToUnicode(in nsIFile newParentDir, [const] in wstring newName);
/**
* This will try to execute this file. It will not block for
* execution. 'args' will be passed through on the command line
* if the OS supports that.
*/
void spawn([array, size_is(count)] in string args, in unsigned long count);
/**
* This will try to delete this file. The 'recursive' flag
* must be PR_TRUE to delete directories which are not empty.
*
* This will not resolve any symlinks.
*/
void delete(in boolean recursive);
/**
* Attributes of nsIFile.
*/
attribute unsigned long permissions;
attribute unsigned long permissionsOfLink;
/**
* File Times are to be in milliseconds from
* midnight (00:00:00), January 1, 1970 Greenwich Mean
* Time (GMT).
*/
attribute PRInt64 lastModificationDate;
attribute PRInt64 lastModificationDateOfLink;
/**
* WARNING! On the Mac getting/setting the file size with nsIFile
* only deals with the size of the data fork. If you need to
* know the size of the combined data and resource forks use the
* GetFileSizeWithResFork() method defined in nsILocalFileMac.h
*/
attribute PRInt64 fileSize;
readonly attribute PRInt64 fileSizeOfLink;
/**
* target & path
*
* Accessor to the string path. These strings are
* not guaranteed to be a usable path to pass to NSPR
* or the C stdlib. There are problems that affect
* platforms on which a path does not fully specify a
* file, because two volumes can have the same name.
* This is solved by holding "private", native data in
* the nsIFile implementation. This native data is lost
* when you convert to a string.
*
* DO NOT PASS TO USE WITH NSPR OR STDLIB.
*
* target:
* Find out what the symlink points at. Will give error
* (NS_ERROR_FILE_INVALID_PATH) if not a symlink.
*
* path:
* Find out what the nsIFile points at.
*/
readonly attribute string target;
readonly attribute wstring unicodeTarget;
readonly attribute string path;
readonly attribute wstring unicodePath;
boolean exists();
boolean isWritable();
boolean isReadable();
boolean isExecutable();
boolean isHidden();
boolean isDirectory();
boolean isFile();
boolean isSymlink();
/**
* Not a regular file, not a directory, not a symlink.
*/
boolean isSpecial();
/**
* createUnique
*
* This function will create a new file or directory in the
* file system. Any nodes that have not been created or
* resolved, will be. If this file already exists, we try
* variations on the leaf name "suggestedName" until we find
* one that did not already exist.
*
* If the search for nonexistent files takes too long
* (thousands of the variants already exist), we give up and
* return NS_ERROR_FILE_TOO_BIG.
*
* @param type
* This specifies the type of file system object
* to be made. The only two types at this time
* are file and directory which are defined above.
* If the type is unrecongnized, we will return an
* error (NS_ERROR_FILE_UNKNOWN_TYPE).
*
* @param permissions
* The unix style octal permissions. This may
* be ignored on systems that do not need to do
* permissions.
*/
void createUnique(in string suggestedName, in unsigned long type, in unsigned long permissions);
/**
* clone()
*
* This function will allocate and initialize a nsIFile object to the
* exact location of the |this| nsIFile.
*
* @param file
* A nsIFile which this object will be initialize
* with.
*
*/
nsIFile clone();
/**
* Will determine if the inFile equals this.
*/
boolean equals(in nsIFile inFile);
/**
* Will determine if inFile is a descendant of this file
* If |recur| is true, look in subdirectories too
*/
boolean contains(in nsIFile inFile, in boolean recur);
/**
* Parent will be null when this is at the top of the volume.
*/
readonly attribute nsIFile parent;
/**
* Returns an enumeration of the elements in a directory. Each
* element in the enumeration is an nsIFile.
*
* @return NS_ERROR_FILE_NOT_DIRECTORY if the current nsIFile does
* not specify a directory.
*/
readonly attribute nsISimpleEnumerator directoryEntries;
/**
* Accesses the file: url for the nsIFile. Setting this causes the path
* to be reset.
*/
attribute string URL;
};
%{C++
#define NS_FILE_CONTRACTID "@mozilla.org/file;1"
#define NS_FILE_CLASSNAME "File Specification"
////////////////////////////////////////////////////////////////////////////////
// Special Directories
#include "nsIServiceManager.h"
#include "nsIProperties.h"
#include "nsCOMPtr.h"
#define NS_DIRECTORY_SERVICE_CID {0xf00152d0,0xb40b,0x11d3,{0x8c, 0x9c, 0x00, 0x00, 0x64, 0x65, 0x73, 0x74}}
inline nsresult
NS_GetSpecialDirectory(const char* specialDirName, nsIFile* *result)
{
nsresult rv;
static NS_DEFINE_CID(kDirectoryServiceCID, NS_DIRECTORY_SERVICE_CID);
NS_WITH_SERVICE(nsIProperties, serv, kDirectoryServiceCID, &rv);
if (NS_FAILED(rv)) return rv;
nsCOMPtr<nsISupports> dir;
rv = serv->Get(specialDirName, NS_GET_IID(nsIFile), getter_AddRefs(dir));
if (NS_FAILED(rv)) return rv;
*result = (nsIFile*)dir.get();
if (*result)
NS_ADDREF(*result);
return NS_OK;
}
%}