uriloader/exthandler/nsIExternalHelperAppService.idl

   1 /* -*- Mode: C++; tab-width: 3; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsICancelable.idl"
   8
   9 interface nsIURI;
  10 interface nsIRequest;
  11 interface nsIStreamListener;
  12 interface nsIFile;
  13 interface nsIMIMEInfo;
  14 interface nsIWebProgressListener2;
  15 interface nsIInterfaceRequestor;
  16
  17 /**
  18  * The external helper app service is used for finding and launching
  19  * platform specific external applications for a given mime content type.
  20  */
  21 [scriptable, uuid(1E4F3AE1-B737-431F-A95D-31FA8DA70199)]
  22 interface nsIExternalHelperAppService : nsISupports
  23 {
  24   /**
  25    * Binds an external helper application to a stream listener. The caller
  26    * should pump data into the returned stream listener. When the OnStopRequest
  27    * is issued, the stream listener implementation will launch the helper app
  28    * with this data.
  29    * @param aMimeContentType The content type of the incoming data
  30    * @param aRequest The request corresponding to the incoming data
  31    * @param aContentContext Used in processing content document refresh
  32    *  headers after target content is downloaded. Note in e10s land
  33    *  this is likely a CPOW that points to a window in the child process.
  34    * @param aForceSave True to always save this content to disk, regardless of
  35    *  nsIMIMEInfo and other such influences.
  36    * @param aWindowContext Used in parenting helper app dialogs, usually
  37    *  points to the parent browser window. This parameter may be null,
  38    *  in which case dialogs will be parented to aContentContext.
  39    * @return A nsIStreamListener which the caller should pump the data into.
  40    */
  41   nsIStreamListener doContent (in ACString aMimeContentType,
  42                                in nsIRequest aRequest,
  43                                in nsIInterfaceRequestor aContentContext,
  44                                in boolean aForceSave,
  45                                [optional] in nsIInterfaceRequestor aWindowContext);
  46
  47   /**
  48    * Returns true if data from a URL with this extension combination
  49    * is to be decoded from aEncodingType prior to saving or passing
  50    * off to helper apps, false otherwise.
  51    */
  52   boolean applyDecodingForExtension(in AUTF8String aExtension,
  53                                     in ACString aEncodingType);
  54
  55 };
  56
  57 /**
  58  * This is a private interface shared between external app handlers and the platform specific
  59  * external helper app service
  60  */
  61 [scriptable, uuid(6613e2e7-feab-4e3a-bb1f-b03200d544ec)]
  62 interface nsPIExternalAppLauncher : nsISupports
  63 {
  64   /**
  65    * mscott --> eventually I should move this into a new service so other
  66    * consumers can add temporary files they want deleted on exit.
  67    * @param aTemporaryFile A temporary file we should delete on exit.
  68    */
  69   void deleteTemporaryFileOnExit(in nsIFile aTemporaryFile);
  70   /**
  71    * Delete a temporary file created inside private browsing mode when
  72    * the private browsing mode has ended.
  73    */
  74   void deleteTemporaryPrivateFileWhenPossible(in nsIFile aTemporaryFile);
  75 };
  76
  77 /**
  78  * A helper app launcher is a small object created to handle the launching
  79  * of an external application.
  80  *
  81  * Note that cancelling the load via the nsICancelable interface will release
  82  * the reference to the launcher dialog.
  83  */
  84 [scriptable, uuid(acf2a516-7d7f-4771-8b22-6c4a559c088e)]
  85 interface nsIHelperAppLauncher : nsICancelable
  86 {
  87   /**
  88    * The mime info object associated with the content type this helper app
  89    * launcher is currently attempting to load
  90    */
  91   readonly attribute nsIMIMEInfo MIMEInfo;
  92
  93   /**
  94    * The source uri
  95    */
  96   readonly attribute nsIURI source;
  97
  98   /**
  99    * The suggested name for this file
 100    */
 101   readonly attribute AString suggestedFileName;
 102
 103   /**
 104    * Saves the final destination of the file. Does not actually perform the
 105    * save.
 106    * NOTE: This will release the reference to the
 107    * nsIHelperAppLauncherDialog.
 108    */
 109   void saveToDisk(in nsIFile aNewFileLocation, in boolean aRememberThisPreference);
 110
 111   /**
 112    * Remembers that aApplication should be used to launch this content. Does
 113    * not actually launch the application.
 114    * NOTE: This will release the reference to the nsIHelperAppLauncherDialog.
 115    * @param aApplication nsIFile corresponding to the location of the application to use.
 116    * @param aRememberThisPreference TRUE if we should remember this choice.
 117    */
 118   void launchWithApplication(in nsIFile aApplication, in boolean aRememberThisPreference);
 119
 120   /**
 121    * Callback invoked by nsIHelperAppLauncherDialog::promptForSaveToFileAsync
 122    * after the user has chosen a file through the File Picker (or dismissed it).
 123    * @param aFile The file that was chosen by the user (or null if dialog was dismissed).
 124    */
 125   void saveDestinationAvailable(in nsIFile aFile);
 126
 127   /**
 128    * The following methods are used by the progress dialog to get or set
 129    * information on the current helper app launcher download.
 130    * This reference will be released when the download is finished (after the
 131    * listener receives the STATE_STOP notification).
 132    */
 133   void setWebProgressListener(in nsIWebProgressListener2 aWebProgressListener);
 134
 135   /**
 136    * The file we are saving to
 137    */
 138   readonly attribute nsIFile targetFile;
 139
 140   /**
 141    * The executable-ness of the target file
 142    */
 143   readonly attribute boolean targetFileIsExecutable;
 144
 145   /**
 146    * Time when the download started
 147    */
 148   readonly attribute PRTime timeDownloadStarted;
 149
 150   /**
 151    * The download content length, or -1 if the length is not available.
 152    */
 153   readonly attribute int64_t contentLength;
 154 };