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 nsIChannel;
  11 interface nsIStreamListener;
  12 interface nsIFile;
  13 interface nsIMIMEInfo;
  14 interface nsIWebProgressListener2;
  15 interface nsIInterfaceRequestor;
  16 webidl BrowsingContext;
  17
  18 /**
  19  * The external helper app service is used for finding and launching
  20  * platform specific external applications for a given mime content type.
  21  */
  22 [scriptable, uuid(1E4F3AE1-B737-431F-A95D-31FA8DA70199)]
  23 interface nsIExternalHelperAppService : nsISupports
  24 {
  25   /**
  26    * Binds an external helper application to a stream listener. The caller
  27    * should pump data into the returned stream listener. When the OnStopRequest
  28    * is issued, the stream listener implementation will launch the helper app
  29    * with this data.
  30    * @param aMimeContentType The content type of the incoming data
  31    * @param aChannel The channel corresponding to the incoming data
  32    * @param aContentContext Used in processing content document refresh
  33    *  headers after target content is downloaded.
  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 nsIChannel aChannel,
  43                                in nsIInterfaceRequestor aContentContext,
  44                                in boolean aForceSave,
  45                                [optional] in nsIInterfaceRequestor aWindowContext);
  46
  47   /**
  48    * Binds an external helper application to a stream listener. The caller
  49    * should pump data into the returned stream listener. When the OnStopRequest
  50    * is issued, the stream listener implementation will launch the helper app
  51    * with this data.
  52    * Replaces doContent for native code, and uses BrowsingContext.
  53    *
  54    * @param aMimeContentType The content type of the incoming data
  55    * @param aChannel The channel corresponding to the incoming data
  56    * @param aContentContext The BrowsingContext that the channel was initiated
  57    *  by. Used for closing the window if we opened one specifically for this download.
  58    * @param aForceSave True to always save this content to disk, regardless of
  59    *  nsIMIMEInfo and other such influences.
  60    * @param aWindowContext Used in parenting helper app dialogs, usually
  61    *  points to the parent browser window. This parameter may be null,
  62    *  in which case dialogs will be parented to aContentContext.
  63    * @return A nsIStreamListener which the caller should pump the data into.
  64    */
  65   nsIStreamListener createListener (in ACString aMimeContentType,
  66                                                    in nsIChannel aChannel,
  67                                                    in BrowsingContext aContentContext,
  68                                                    in boolean aForceSave,
  69                                                    [optional] in nsIInterfaceRequestor aWindowContext);
  70
  71   /**
  72    * Returns true if data from a URL with this extension combination
  73    * is to be decoded from aEncodingType prior to saving or passing
  74    * off to helper apps, false otherwise.
  75    */
  76   boolean applyDecodingForExtension(in AUTF8String aExtension,
  77                                     in ACString aEncodingType);
  78
  79 };
  80
  81 /**
  82  * This is a private interface shared between external app handlers and the platform specific
  83  * external helper app service
  84  */
  85 [scriptable, uuid(6613e2e7-feab-4e3a-bb1f-b03200d544ec)]
  86 interface nsPIExternalAppLauncher : nsISupports
  87 {
  88   /**
  89    * mscott --> eventually I should move this into a new service so other
  90    * consumers can add temporary files they want deleted on exit.
  91    * @param aTemporaryFile A temporary file we should delete on exit.
  92    */
  93   void deleteTemporaryFileOnExit(in nsIFile aTemporaryFile);
  94   /**
  95    * Delete a temporary file created inside private browsing mode when
  96    * the private browsing mode has ended.
  97    */
  98   void deleteTemporaryPrivateFileWhenPossible(in nsIFile aTemporaryFile);
  99 };
 100
 101 /**
 102  * A helper app launcher is a small object created to handle the launching
 103  * of an external application.
 104  *
 105  * Note that cancelling the load via the nsICancelable interface will release
 106  * the reference to the launcher dialog.
 107  */
 108 [scriptable, uuid(acf2a516-7d7f-4771-8b22-6c4a559c088e)]
 109 interface nsIHelperAppLauncher : nsICancelable
 110 {
 111   /**
 112    * The mime info object associated with the content type this helper app
 113    * launcher is currently attempting to load
 114    */
 115   readonly attribute nsIMIMEInfo MIMEInfo;
 116
 117   /**
 118    * The source uri
 119    */
 120   readonly attribute nsIURI source;
 121
 122   /**
 123    * The suggested name for this file
 124    */
 125   readonly attribute AString suggestedFileName;
 126
 127   /**
 128    * Saves the final destination of the file.
 129    * NOTE: This will release the reference to the nsIHelperAppLauncherDialog.
 130    */
 131   void promptForSaveDestination();
 132
 133   /**
 134    * Tell the launcher that we will want to open the file.
 135    * NOTE: This will release the reference to the nsIHelperAppLauncherDialog.
 136    * @param aHandleInternally TRUE if we should handle opening this internally.
 137    * @param aNewFileLocation a preferred location choosen through the File Picker.
 138    * Null if going through the fast save without File Picker.
 139    */
 140   void setDownloadToLaunch(in boolean aHandleInternally, in nsIFile aFile);
 141
 142
 143   /**
 144    * Use the MIMEInfo associated with us to open a file that is already local.
 145    * Will no-op if `source` is not a local file.
 146    */
 147   void launchLocalFile();
 148
 149   /**
 150    * Callback invoked by nsIHelperAppLauncherDialog::promptForSaveToFileAsync
 151    * after the user has chosen a file through the File Picker (or dismissed it).
 152    * @param aFile The file that was chosen by the user (or null if dialog was dismissed).
 153    * @param aDialogWasShown Optional boolean - false by default. Pass true if a
 154    *  dialog was opened in the process of reaching this file result. If true, we
 155    *  suppress the opening of the downloads panel to avoid redundancy.
 156    */
 157   void saveDestinationAvailable(in nsIFile aFile, [optional] in boolean aDialogWasShown);
 158
 159   /**
 160    * The following methods are used by the progress dialog to get or set
 161    * information on the current helper app launcher download.
 162    * This reference will be released when the download is finished (after the
 163    * listener receives the STATE_STOP notification).
 164    */
 165   void setWebProgressListener(in nsIWebProgressListener2 aWebProgressListener);
 166
 167   /**
 168    * The file we are saving to
 169    */
 170   readonly attribute nsIFile targetFile;
 171
 172   /**
 173    * The executable-ness of the target file
 174    */
 175   readonly attribute boolean targetFileIsExecutable;
 176
 177   /**
 178    * Time when the download started
 179    */
 180   readonly attribute PRTime timeDownloadStarted;
 181
 182   /**
 183    * The download content length, or -1 if the length is not available.
 184    */
 185   readonly attribute int64_t contentLength;
 186
 187   /**
 188    * The browsingContext ID of the launcher's source
 189    */
 190   readonly attribute uint64_t browsingContextId;
 191 };