xpcom/io/nsILocalFile.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla Communicator client code, released
  16  * March 31, 1998.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1998-1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Doug Turner <dougt@netscape.com>
  25  *   Darin Fisher <darin@netscape.com>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsIFile.idl"
  42
  43 %{C++
  44 #include "prio.h"
  45 #include "prlink.h"
  46 #include <stdio.h>
  47 %}
  48
  49 [ptr] native PRFileDescStar(PRFileDesc);
  50 [ptr] native PRLibraryStar(PRLibrary);
  51 [ptr] native FILE(FILE);
  52
  53 /**
  54  * This interface adds methods to nsIFile that are particular to a file
  55  * that is accessible via the local file system.
  56  *
  57  * It follows the same string conventions as nsIFile.
  58  *
  59  * @status FROZEN
  60  */
  61 [scriptable, uuid(aa610f20-a889-11d3-8c81-000064657374)]
  62 interface nsILocalFile : nsIFile
  63 {
  64     /**
  65      *  initWith[Native]Path
  66      *
  67      *  This function will initialize the nsILocalFile object.  Any
  68      *  internal state information will be reset.
  69      *
  70      *  NOTE: This function has a known bug on the macintosh and
  71      *  other OSes which do not represent file locations as paths.
  72      *  If you do use this function, be very aware of this problem!
  73      *
  74      *   @param filePath
  75      *       A string which specifies a full file path to a
  76      *       location.  Relative paths will be treated as an
  77      *       error (NS_ERROR_FILE_UNRECOGNIZED_PATH).  For
  78      *       initWithNativePath, the filePath must be in the native
  79      *       filesystem charset.
  80      */
  81     void initWithPath(in AString filePath);
  82     [noscript] void initWithNativePath(in ACString filePath);
  83
  84     /**
  85      *  initWithFile
  86      *
  87      *  Initialize this object with another file
  88      *
  89      *   @param aFile
  90      *       the file this becomes equivalent to
  91      */
  92     void initWithFile(in nsILocalFile aFile);
  93
  94     /**
  95      *  followLinks
  96      *
  97      *  This attribute will determine if the nsLocalFile will auto
  98      *  resolve symbolic links.  By default, this value will be false
  99      *  on all non unix systems.  On unix, this attribute is effectively
 100      *  a noop.
 101      */
 102     attribute PRBool followLinks;
 103
 104     /**
 105      * Return the result of PR_Open on the file.  The caller is
 106      * responsible for calling PR_Close on the result.
 107      */
 108     [noscript] PRFileDescStar openNSPRFileDesc(in long flags, in long mode);
 109
 110     /**
 111      * Return the result of fopen on the file.  The caller is
 112      * responsible for calling fclose on the result.
 113      */
 114     [noscript] FILE           openANSIFileDesc(in string mode);
 115
 116     /**
 117      * Return the result of PR_LoadLibrary on the file.  The caller is
 118      * responsible for calling PR_UnloadLibrary on the result.
 119      */
 120     [noscript] PRLibraryStar  load();
 121
 122     readonly attribute PRInt64 diskSpaceAvailable;
 123
 124     /**
 125      *  appendRelative[Native]Path
 126      *
 127      *  Append a relative path to the current path of the nsILocalFile object.
 128      *
 129      *   @param relativeFilePath
 130      *       relativeFilePath is a native relative path. For security reasons,
 131      *       this cannot contain .. or cannot start with a directory separator.
 132      *       For the |appendRelativeNativePath| method, the relativeFilePath
 133      *       must be in the native filesystem charset.
 134      */
 135     void appendRelativePath(in AString relativeFilePath);
 136     [noscript] void appendRelativeNativePath(in ACString relativeFilePath);
 137
 138     /**
 139      *  Accessor to a null terminated string which will specify
 140      *  the file in a persistent manner for disk storage.
 141      *
 142      *  The character set of this attribute is undefined.  DO NOT TRY TO
 143      *  INTERPRET IT AS HUMAN READABLE TEXT!
 144      */
 145     attribute ACString persistentDescriptor;
 146
 147     /**
 148      *  reveal
 149      *
 150      *  Ask the operating system to open the folder which contains
 151      *  this file or folder. This routine only works on platforms which
 152      *  support the ability to open a folder...
 153      */
 154     void reveal();
 155
 156     /**
 157      *  launch
 158      *
 159      *  Ask the operating system to attempt to open the file.
 160      *  this really just simulates "double clicking" the file on your platform.
 161      *  This routine only works on platforms which support this functionality.
 162      */
 163     void launch();
 164
 165     /**
 166      *  getRelativeDescriptor
 167      *
 168      *  Returns a relative file path in an opaque, XP format. It is therefore
 169      *  not a native path.
 170      *
 171      *  The character set of the string returned from this function is
 172      *  undefined.  DO NOT TRY TO INTERPRET IT AS HUMAN READABLE TEXT!
 173      *
 174      *   @param fromFile
 175      *       the file from which the descriptor is relative.
 176      *       There is no defined result if this param is null.
 177      */
 178     ACString getRelativeDescriptor(in nsILocalFile fromFile);
 179
 180     /**
 181      *  setRelativeDescriptor
 182      *
 183      *  Initializes the file to the location relative to fromFile using
 184      *  a string returned by getRelativeDescriptor.
 185      *
 186      *   @param fromFile
 187      *       the file to which the descriptor is relative
 188      *   @param relative
 189      *       the relative descriptor obtained from getRelativeDescriptor
 190      */
 191     void setRelativeDescriptor(in nsILocalFile fromFile, in ACString relativeDesc);
 192 };
 193