xpcom/io/nsILocalFileWin.idl

   1 /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 #include "nsIFile.idl"
   8
   9 %{C++
  10 struct PRFileDesc;
  11 %}
  12
  13 [ptr] native PRFileDescStar(PRFileDesc);
  14
  15 [scriptable, builtinclass, uuid(e7a3a954-384b-4aeb-a5f7-55626b0de9be)]
  16 interface nsILocalFileWin : nsIFile
  17 {
  18     /**
  19      *  initWithCommandLine
  20      *
  21      *  Initialize this object based on the main app path of a commandline
  22      *  handler.
  23      *
  24      *   @param aCommandLine
  25      *       the commandline to parse an app path out of.
  26      */
  27     void initWithCommandLine(in AString aCommandLine);
  28    /**
  29     * getVersionInfoValue
  30     *
  31     * Retrieve a metadata field from the file's VERSIONINFO block.
  32     * Throws NS_ERROR_FAILURE if no value is found, or the value is empty.
  33     *
  34     * @param   aField         The field to look up.
  35     *
  36     */
  37     AString getVersionInfoField(in string aField);
  38
  39     /**
  40      * The canonical path of the file, which avoids short/long
  41      * pathname inconsistencies. The nsIFile persistent
  42      * descriptor is not guaranteed to be canonicalized (it may
  43      * persist either the long or the short path name). The format of
  44      * the canonical path will vary with the underlying file system:
  45      * it will typically be the short pathname on filesystems that
  46      * support both short and long path forms.
  47      */
  48     [noscript] readonly attribute AString canonicalPath;
  49
  50     /**
  51      * Get or set whether this file is marked read-only.
  52      *
  53      * Throws NS_ERROR_FILE_INVALID_PATH for an invalid file.
  54      * Throws NS_ERROR_FAILURE if the set or get fails.
  55      */
  56     attribute bool readOnly;
  57
  58     /**
  59      * Setting this to true will prepend the prefix "\\?\" to all parsed file
  60      * paths which match ^[A-Za-z]:\\.* (regex) syntax.
  61      *
  62      * There are two known issues (and potentially more) which can be resolved
  63      * by the prefix:
  64      * - In the Windows API, the maximum length for a path is MAX_PATH in
  65      *   general. However, Windows API has many functions that also have Unicode
  66      *   versions to permit an extended-length path for a maximum total path
  67      *   length of 32,767 characters.
  68      *
  69      * - A path component which ends with a dot is not allowed for Windows
  70      *   API.
  71      *
  72      * If either of these issues are expected to be common in your code, you
  73      * should set this flag to true. (You should probably not have to set this
  74      * flag to true.)
  75      */
  76     attribute boolean useDOSDevicePathSyntax;
  77
  78     /**
  79      * Identical to nsIFile::openNSPRFileDesc except it also uses the
  80      * FILE_SHARE_DELETE flag.
  81     */
  82     [noscript] PRFileDescStar openNSPRFileDescShareDelete(in long flags,
  83                                                           in long mode);
  84
  85     /**
  86      * Return the Windows-specific file attributes of this file.
  87      */
  88     [noscript] unsigned long getWindowsFileAttributes();
  89
  90     /**
  91      * Set or clear the Windows specific file attributes of this file.
  92      *
  93      * @param aSetAttrs   Attribute to set on the file.
  94      * @param aClearAttrs Attributes to clear on the file.
  95      */
  96     [noscript] void setWindowsFileAttributes(in unsigned long aSetAttrs,
  97                                              in unsigned long aClearAttrs);
  98 };