1/* -*- Mode: C++; 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#include "nsIProtocolHandler.idl" 7 8interface nsIFile; 9interface nsIURIMutator; 10 11[scriptable, uuid(1fb25bd5-4354-4dcd-8d97-621b7b3ed2e4)] 12interface nsIFileProtocolHandler : nsIProtocolHandler 13{ 14 /** 15 * This method constructs a new file URI 16 * 17 * @param aFile nsIFile 18 * @return reference to a new nsIURI object 19 */ 20 nsIURI newFileURI(in nsIFile aFile); 21 22 /** 23 * This method constructs a new file URI, and returns a URI mutator 24 * that has not yet been finalized, allowing the URI to be changed without 25 * being cloned. 26 * 27 * @param aFile nsIFile 28 * @return reference to a new nsIURIMutator object 29 */ 30 nsIURIMutator newFileURIMutator(in nsIFile file); 31 32 /** 33 * Converts the nsIFile to the corresponding URL string. NOTE: under 34 * some platforms this is a lossy conversion (e.g., Mac Carbon build). 35 * If the nsIFile is a local file, then the result will be a file:// 36 * URL string. 37 * 38 * The resulting string may contain URL-escaped characters. 39 * NOTE: Callers should use getURLSpecFromActualFile or 40 * getURLSpecFromDirFile if possible, for performance reasons. 41 */ 42 AUTF8String getURLSpecFromFile(in nsIFile file); 43 44 /** 45 * Converts the nsIFile to the corresponding URL string. Should 46 * only be called on files which are not directories. Otherwise 47 * identical to getURLSpecFromFile, but is usually more efficient. 48 * WARNING: This restriction may not be enforced at runtime! 49 */ 50 AUTF8String getURLSpecFromActualFile(in nsIFile file); 51 52 /** 53 * Converts the nsIFile to the corresponding URL string. Should 54 * only be called on files which are directories. Otherwise 55 * identical to getURLSpecFromFile, but is usually more efficient. 56 * WARNING: This restriction may not be enforced at runtime! 57 */ 58 AUTF8String getURLSpecFromDir(in nsIFile file); 59 60 /** 61 * Converts the URL string into the corresponding nsIFile if possible. 62 * A local file will be created if the URL string begins with file://. 63 */ 64 nsIFile getFileFromURLSpec(in AUTF8String url); 65 66 /** 67 * Takes a local file and tries to interpret it as an internet shortcut 68 * (e.g. .url files on windows). 69 * @param file The local file to read 70 * @return The URI the file refers to 71 * 72 * @throw NS_ERROR_NOT_AVAILABLE if the OS does not support such files. 73 * @throw NS_ERROR_NOT_AVAILABLE if this file is not an internet shortcut. 74 */ 75 nsIURI readURLFile(in nsIFile file); 76 77 /** 78 * Takes a local file and tries to interpret it as a shell link file 79 * (.lnk files on Windows) 80 * @param file The local file to read 81 * @return The URI the file refers to 82 * 83 * @throw NS_ERROR_NOT_AVAILABLE if the OS does not support such files. 84 * @throw NS_ERROR_NOT_AVAILABLE if this file is not a shell link. 85 */ 86 nsIURI readShellLink(in nsIFile file); 87}; 88