pjs/xpcom/io/nsIFile.idl

/* -*- 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.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */

// 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"

[scriptable, uuid(c8c0a080-0868-11d3-915f-d9d889d48e3c)]
interface nsIFile : nsISupports
{

	/**
	 *	 Different path types that nsIFile can parse.
	 *
     *   NATIVE_PATH is a **native** path.  For example, on windows 
	 *   this would be "c:\\foo\\bar" and on the mac it would be 
	 *   "Macintosh HD:foo:bar"
     *
	 *   UNIX_PATH is a unix style path.  If you are running on unix 
	 *   this is the same as InitWithNativePath.  This strings look like
	 *   "/Development/MPW/SysErrs.err"
	 *
	 *   NSPR_PATH is a NSPR style path.  NSPR expects a UNIX path on unix 
	 *   and Macintosh, but a native path on windows.  If you want to create 
	 *   a nsIFile form a string that comes back from NSPR, use this call
	 */

	const unsigned long NATIVE_PATH = 0;
	const unsigned long UNIX_PATH = 1;
	const unsigned long NSPR_PATH = 2;

    /**
	 *	 Initialization routines.  These functions shall be called to 
	 *   setup the nsIFile.  
	 */
	void Init([const] in string filePath, in unsigned long pathType);
	
	/**
	 *  Create() will create a new file, directory or symlink in the file system.  
	 *  Any nodes that have not been created or resolved, will be.
	 * 
	 *  type -       TODO
	 *  attributes - 
	 */
	void Create([const] in string type, [const] in string attributes);
	
	/**
	 *  Append() will create concatenate a relative path to this nsIFile.  It
	 *  is used for constructing the nsIFile of a descendant.  If this object is 
	 *  already Created, it must be either a directory or symlink to a directory. 
     *  Append() will do what nsString does, it will tag the |node| at the end
	 *  of what the nsIFile already has stuff in it.  It will also do
     *  non-terminal symlink resolution.
	 *
	 *  pathType is only meaningful if |node| is a compound path (eg. "foo/bar/i/am/")
	 */
	void Append([const] in string node, in unsigned long pathType);

	/**
	 *	 Accessor to the file name (the leaf name not the full file path) of the file itself.   
	 */
	readonly attribute string FileName;
	
	/**
	 *	Accessor to the full file path.  The use of the Path is strongly discouraged 
	 *  The problem affects platforms (Macintosh) in which a path does not fully
	 *  specify a file, because two volumes can have the same name.  This is solved 
	 *  by holding a "private" native data.  This data is lost when you convert to  
	 *  a string.
	 */
	string GetPath(in unsigned long pathType);
	
	/**
	 *  This will rename the file on disk.  This function will
	 *  not move file objects.  If the file can not be renamed 
	 *  an error code will be returned.      
	 */
	void Rename([const] in string newName);
	
	/**
	 *  This will copy this file (if created) to the specified 
	 *  newParentDir.  Permissions will try to be mantained.
	 */
	void CopyTo([const] in nsIFile newParentDir);
	
	/**
	 *  This will move (copy then delete) this file (if created) 
	 *  to the specified newParentDir.  Permissions will try 
	 *  to be mantained.  If the MoveTo failes, this will not
	 *  be deleted.
	 */
	void MoveTo([const] in nsIFile newParentDir);
	
	/**
	 *  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 Execute([const] in string args);
	
	/**
	 *  This will try to delete this file.  The 'recursive' flag
	 *  must be PR_TRUE to delete directories which are not empty.
	 */
	void Delete(in boolean recursive);

	/**
	 *  This will resolve the terminal node of the nsIFile.
	 */
	void ResolveSymlink(void);

	/**
	 *  Will determine if the inFile equals this.
	 */

	/**
	 *  Attributes of nsIFile.
	 */
	attribute unsigned long LastModificationDate;
		
	readonly attribute unsigned long Permissions;
	readonly attribute unsigned long FileSize;
	readonly attribute unsigned long DiskSpaceAvailable;

	readonly attribute nsIFile Parent;
	
	boolean IsExists();
	boolean IsWriteable();
	boolean IsReadable();
	boolean IsDirectory();
	boolean IsFile();
	boolean IsHidden();
	boolean IsSymlink();
	
	bool IsEqual([const] in nsIFile inFile);
};