gecko/xpfe/components/winhooks/nsIWindowsHooks.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * 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 mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Bill Law       <law@netscape.com>
 *   Aaron Kaluszka <ask@swva.net>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

 
/* These interface provides support for integrating Mozilla into Windows.
 * This integration consists primarily of setting Mozilla as the "default
 * browser."  Or more precisely, setting Mozilla as the executable to
 * handle certain file types.
 *
 * There are two subtly different types of desktop objects that Mozilla
 * can be configured to "handle:"
 *      o File types (based on file extension)
 *      o Internet shortcuts (based on URL protocol).
 *
 * While these are different types of objects, the mechanism by which
 * applications are matched with them is essentially the same.
 *
 * In the case of files, there is one more level of indirection.  File
 * extensions are assigned a "file type" via a Windows registry entry.
 * For example, given the file extension ".foo", the file type is
 * determined by examing the value stored in the "default" value stored
 * at the registry key HKEY_LOCAL_MACHINE\Software\Classes\.foo.
 *
 * Once you have the "file type" then you use that the same way you use
 * Internet Shortcut protocol names to determine which application to
 * launch.  The application is specified by the default value stored in
 * the registry key
 * HKEY_LOCAL_MACHINE\Software\Classes\<X>\shell\open\command, where
 * <X> is the "file type" or protocol name.
 *
 * If there are additional keys under "shell" then these appear on the
 * context menu for files/shortcuts of this type.  Typically, there are
 * entries for "print."  But Mozilla does not currently support a command
 * line option to print so we don't offer that.
 *
 * Previously, Netscape Communicator made itself the handler of standard
 * web things by creating a new file type "NetscapeMarkup" and mapping
 * extensions to that (.htm, .html, .shtml, .xbm), or, by setting itself
 * up as the "handler" for the file types of other web things (.jpg, .gif)
 * and Internet Shortcut protocols (ftp, gopher, http, https, mailto, news,
 * snews).
 *
 * In order to better enable Mozilla to co-exist with other browsers
 * (including Communicator), it will create yet another new file type,
 * "MozillaMarkup," that will be used to make Mozilla the default handler
 * for certain file extensions.  This will be done by remapping those
 * extensions to this new type.
 *
 * Mozilla will attempt to remember the original mapping and restore it
 * when the user decides to no longer have Mozilla be the default handler
 * for that extension.
 *
 * Mozilla will drop support for some items that are no longer germane:
 * the .shtml file extension and the gopher: protocol.  We will also, perhaps
 * only temporarily, drop support for protocols that aren't accessible from
 * the command line: mailto:, news:, and snews:.
 *
 * We will be adding support for the chrome: protocol (using the "-chrome"
 * command line option) and for .png, .xul and .xml file extensions.
 *
 * Missing Features:
 *
 * Currently, there is no way to extend the set of file types or protocols
 * that Mozilla can be associated with (save manually tweaking the Windows
 * registry).  This is likely to be a problem for branded Mozilla browsers
 * that might support specialized file types or protocols (e.g., .aim files).
 *
 * The plan is to extend this interface so that such file types and protocols
 * can be set up using the implementation of the interfaces defined here.
 */

interface nsIDOMWindowInternal;
interface nsIDOMElement;

/* nsIWindowsHooksSettings
 *
 * This interface is used to get/set the user preferences relating to
 * "windows hooks" (aka "windows integration").  It is basically just
 * a conglomeration of a bunch of boolean attributes; it exists mainly
 * for historical reasons (it corresponds to the internal Prefs struct
 * that was in nsIDefaultBrowser.h in Mozilla Classic).
 */
[scriptable, uuid(d7a33e08-705e-4506-aba0-843c73dfd304)]
interface nsIWindowsHooksSettings : nsISupports {

    // Internet shortcuts (based on "protocol").
    attribute boolean isHandlingHTTP;
    attribute boolean isHandlingHTTPS;
    attribute boolean isHandlingFTP;
    attribute boolean isHandlingCHROME;
    attribute boolean isHandlingGOPHER;

    // File handling (based on extension).
    attribute boolean isHandlingHTML;
    attribute boolean isHandlingJPEG;
    attribute boolean isHandlingGIF;
    attribute boolean isHandlingPNG;
    attribute boolean isHandlingXBM;
    attribute boolean isHandlingBMP;
    attribute boolean isHandlingICO;
    attribute boolean isHandlingXML;
    attribute boolean isHandlingXHTML;
    attribute boolean isHandlingXUL;

    // Nag dialog flag.  Set this so that dialog
    // appears on startup if there is a mismatch
    // between registry and these settings.
    attribute boolean showDialog;

    // Registry mismatch indicator.
    // This is true if the Win32 registry is
    // currently set to match the preferences
    // in this object.
    readonly attribute boolean registryMatches;
};

/* nsIWindowsHooks
 *
 * This interface describes the service that you can use to
 * get/set the various windows integration features specified
 * by the nsIWindowsHooksPrefs attributes.
 */
[scriptable, uuid(19c9fbb0-06a3-11d4-8076-00600811a9c3)]
interface nsIWindowsHooks : nsISupports {

    // settings
    // --------
    // Get/set this to query or modify them.  The Windows
    // registry is updated when you set this attribute.
    attribute nsIWindowsHooksSettings settings;

    // checkSettings
    // -------------
    // Check that registry matches settings and if not,
    // prompt user for whether to reset.  This is
    // controlled by the showDialog setting.  This will
    // perform the check only the first time the
    // service is called.
    //   aParent - parent window for any dialogs that
    //             will appear
    //   Returns true if the windows integration dialog was shown
    boolean checkSettings( in nsIDOMWindowInternal aParent );

    /**
     * Returns true if command is in the "(appname) QuickLaunch" value in the
     * HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\CurrentVersion\\Run
     * key.
     */
    boolean isOptionEnabled(in string option);

    /**
     * Adds the option to the "(appname) QuickLaunch" value to the key mentioned above,
     * with data "(path\to\app.exe) option", if not done already.
     */
    void startupAddOption(in string option);

    /**
     * Removes the commnand from the "(appname) QuickLaunch" value from
	 * the key mentioned above, if not done already. And deletes the
	 * "(appname) QuickLaunch" value entirely if there are no options left
     */
    void startupRemoveOption(in string option);

    /**
     * Accepts an element, either an HTML img element or an element with
     * a background image, serializes the image to a bitmap file
     * in the windows directory, and sets it to be the desktop wallpaper.
     */
    void setImageAsWallpaper(in nsIDOMElement aImageElement, in boolean useBackground);
};

%{C++
#define NS_IWINDOWSHOOKS_CONTRACTID    "@mozilla.org/winhooks;1"
#define NS_IWINDOWSHOOKS_CLASSNAME "Mozilla Windows Integration Hooks"

// The key that is used to write the quick launch appname in the windows registry
#define NS_QUICKLAUNCH_RUN_KEY "Mozilla Quick Launch"
%}