gecko-dev/uriloader/exthandler/nsIExternalHelperAppService.idl

/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Mozilla browser.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications, Inc.  Portions created by Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Scott MacGregor <mscott@netscape.com>
 */

/* The external helper app service is used for finding and launching
   platform specific external applications for a given mime content type.
 */

#include "nsISupports.idl"

interface nsIURI;
interface nsIStreamListener;
interface nsIFile;
interface nsIMIMEInfo;
interface nsIWebProgressListener;


[scriptable, uuid(663CC0AA-42EA-11d4-98D0-001083010E9B)]
interface nsIExternalHelperAppService : nsISupports
{
  // canHandleContent: determines if we have an external helper application for a given mime type
  // aMimeContentType --> the specified mime type we are attempting to get a helper application for
  // aUri --> the url for the data we are trying to load. The implementor may need this in order to figure 
  // out the file extension of the document.
  // returns TRUE if we have such an app and FALSE otherwise.
  boolean canHandleContent (in string aMimeContentType, in nsIURI aUri); 

  // doContent: binds an external helper application to a stream listener. The caller should pump data
  // into the returned stream listener. When the OnStopRequest is issued, the stream listener implementation
  // will launch the helper app with this data.
  // aMimeContentType --> the content type of the incoming data
  // aURI --> the URI corresponding to the incoming data
  // aWindowContext --> use GetInterface to retrieve properties like the dom window or parent window...
  //                    the service might need this in order to bring up dialogs.
  // aAbortProcess --> set to TRUE by the helper service if the caller should just forget about loading the document
  //                   (typically this occurs if the helper app just wants the URI to run and not the data)
  // returns a nsIStreamListener which the caller should pump the data into.
  nsIStreamListener doContent (in string aMimeContentType, in nsIURI aURI, 
                               in nsISupports aWindowContext, out boolean aAbortProcess); 

  // applyDecodingForType: returns true if this type is to be decoded
  //                       prior to saving or passing off to helper apps,
  //                       false otherwise
  boolean applyDecodingForType (in string aMimeContentType);

  // applyDecodingForExtension: returns false if files with this extension
  //                            are not to be decoded prior to saving or
  //                            passing off to helper apps, false otherwise
  boolean applyDecodingForExtension(in string aExtension);
};

// this is a private interface shared between external app handlers and the platform specific
// external helper app service
[scriptable, uuid(491D04D5-449C-11d4-98D0-001083010E9B)]
interface nsPIExternalAppLauncher : nsISupports
{
  // launchAppWithTempFile --> used by the handler to actually launch the helper application
  // aTempFile --> the file which contains the data we want the helper app to use when it is launched
  void launchAppWithTempFile(in nsIMIMEInfo aMIMEInfo, in nsIFile aTempFile);

  // mscott --> eventually I should move this into a new service so other consumers can add temporary files
  // they want deleted on exit.
  // aTemporaryFile --> a temporary file we should delete on exit.

  void deleteTemporaryFileOnExit(in nsIFile aTemporaryFile); 
};

// a helper app launcher is a small object created to handle the launching of an external application.

[scriptable, uuid(9503D0FE-4C9D-11d4-98D0-001083010E9B)]
interface nsIHelperAppLauncher : nsISupports
{
  // the mime info object associated with the content type this helper app launcher is currently
  // attempting to load
  readonly attribute nsIMIMEInfo MIMEInfo;

  // the source url
  readonly attribute nsIURI source;

  readonly attribute wstring suggestedFileName;

  // saveToDisk: called when we want to just save the content to a particular file
  // aNewFileLocation --> location where the content should be saved
  void saveToDisk(in nsIFile aNewFileLocation, in boolean aRememberThisPreference);

  // launchWithApplication: use aApplication to launch with this content 
  // aApplication --> nsIFile corresponding to the location of the application to use
  // aRememberThisPreference --> TRUE if we should remember this choice.
  void launchWithApplication(in nsIFile aApplication, in boolean aRememberThisPreference);

  // called if the user decides to cancel the handling of this content type
  void Cancel();

  // the following methods are used by the progress dialog to get or set information 
  // on the current helper app launcher download
  void setWebProgressListener(in nsIWebProgressListener aWebProgressListener);
  // when the stand along progress window actually closes, it calls this method
  // so we can release any local state...
  void closeProgressWindow();

  // aSourceUrl--> the url we are downloading....and the file we are saving too
  // aTimeDownloadStarted --> time in ms that the download actually began
  nsIFile getDownloadInfo(out nsIURI aSourceUrl, out long long aTimeDownloadStarted);
  
};