uriloader/exthandler/nsIExternalHelperAppService.idl

   1 /* -*- Mode: C++; tab-width: 3; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications, Inc.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Scott MacGregor <mscott@netscape.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsICancelable.idl"
  41
  42 interface nsIURI;
  43 interface nsIRequest;
  44 interface nsIStreamListener;
  45 interface nsIFile;
  46 interface nsIMIMEInfo;
  47 interface nsIWebProgressListener2;
  48 interface nsIInterfaceRequestor;
  49
  50 /**
  51  * The external helper app service is used for finding and launching
  52  * platform specific external applications for a given mime content type.
  53  */
  54 [scriptable, uuid(9e456297-ba3e-42b1-92bd-b7db014268cb)]
  55 interface nsIExternalHelperAppService : nsISupports
  56 {
  57   /**
  58    * Binds an external helper application to a stream listener. The caller
  59    * should pump data into the returned stream listener. When the OnStopRequest
  60    * is issued, the stream listener implementation will launch the helper app
  61    * with this data.
  62    * @param aMimeContentType The content type of the incoming data
  63    * @param aRequest The request corresponding to the incoming data
  64    * @param aWindowContext Use GetInterface to retrieve properties like the
  65    *                       dom window or parent window...
  66    *                       The service might need this in order to bring up dialogs.
  67    * @param aForceSave True to always save this content to disk, regardless of
  68    *                   nsIMIMEInfo and other such influences.
  69    * @return A nsIStreamListener which the caller should pump the data into.
  70    */
  71   nsIStreamListener doContent (in ACString aMimeContentType, in nsIRequest aRequest,
  72                                in nsIInterfaceRequestor aWindowContext,
  73                                in boolean aForceSave);
  74
  75   /**
  76    * Returns true if data from a URL with this extension combination
  77    * is to be decoded from aEncodingType prior to saving or passing
  78    * off to helper apps, false otherwise.
  79    */
  80   boolean applyDecodingForExtension(in AUTF8String aExtension,
  81                                     in ACString aEncodingType);
  82
  83 };
  84
  85 /**
  86  * This is a private interface shared between external app handlers and the platform specific
  87  * external helper app service
  88  */
  89 [scriptable, uuid(d0b5d7d3-9565-403d-9fb5-e5089c4567c6)]
  90 interface nsPIExternalAppLauncher : nsISupports
  91 {
  92   /**
  93    * mscott --> eventually I should move this into a new service so other
  94    * consumers can add temporary files they want deleted on exit.
  95    * @param aTemporaryFile A temporary file we should delete on exit.
  96    */
  97   void deleteTemporaryFileOnExit(in nsIFile aTemporaryFile);
  98 };
  99
 100 /**
 101  * A helper app launcher is a small object created to handle the launching
 102  * of an external application.
 103  *
 104  * Note that cancelling the load via the nsICancelable interface will release
 105  * the reference to the launcher dialog.
 106  */
 107 [scriptable, uuid(d9a19faf-497b-408c-b995-777d956b72c0)]
 108 interface nsIHelperAppLauncher : nsICancelable
 109 {
 110   /**
 111    * The mime info object associated with the content type this helper app
 112    * launcher is currently attempting to load
 113    */
 114   readonly attribute nsIMIMEInfo MIMEInfo;
 115
 116   /**
 117    * The source uri
 118    */
 119   readonly attribute nsIURI source;
 120
 121   /**
 122    * The suggested name for this file
 123    */
 124   readonly attribute AString suggestedFileName;
 125
 126   /**
 127    * Called when we want to just save the content to a particular file.
 128    * NOTE: This will release the reference to the nsIHelperAppLauncherDialog.
 129    * @param aNewFileLocation Location where the content should be saved
 130    */
 131   void saveToDisk(in nsIFile aNewFileLocation, in boolean aRememberThisPreference);
 132
 133   /**
 134    * Use aApplication to launch with this content.
 135    * NOTE: This will release the reference to the nsIHelperAppLauncherDialog.
 136    * @param aApplication nsIFile corresponding to the location of the application to use.
 137    * @param aRememberThisPreference TRUE if we should remember this choice.
 138    */
 139   void launchWithApplication(in nsIFile aApplication, in boolean aRememberThisPreference);
 140
 141   /**
 142    * The following methods are used by the progress dialog to get or set
 143    * information on the current helper app launcher download.
 144    * This reference will be released when the download is finished (after the
 145    * listener receives the STATE_STOP notification).
 146    */
 147   void setWebProgressListener(in nsIWebProgressListener2 aWebProgressListener);
 148
 149   /**
 150    * when the stand alone progress window actually closes, it calls this method
 151    * so we can release any local state...
 152    */
 153   void closeProgressWindow();
 154
 155   /**
 156    * The file we are saving to
 157    */
 158   readonly attribute nsIFile targetFile;
 159
 160   /**
 161    * The executable-ness of the target file
 162    */
 163   readonly attribute boolean targetFileIsExecutable;
 164
 165   /**
 166    * Time when the download started
 167    */
 168   readonly attribute PRTime timeDownloadStarted;
 169
 170   /**
 171    * The download content length, or -1 if the length is not available.
 172    */
 173   readonly attribute PRInt64 contentLength;
 174 };