summaryrefslogtreecommitdiffstats
path: root/toolkit/xre/nsINativeAppSupport.idl
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/xre/nsINativeAppSupport.idl')
-rw-r--r--toolkit/xre/nsINativeAppSupport.idl104
1 files changed, 104 insertions, 0 deletions
diff --git a/toolkit/xre/nsINativeAppSupport.idl b/toolkit/xre/nsINativeAppSupport.idl
new file mode 100644
index 000000000..c9a316a98
--- /dev/null
+++ b/toolkit/xre/nsINativeAppSupport.idl
@@ -0,0 +1,104 @@
+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+/* nsINativeAppSupport
+ *
+ * This "pseudo" (in the XPCOM sense) interface provides for
+ * platform-specific general application support:
+ * o It manages the details of the simple DDE communication
+ * supported on the Win32 platform (it is the addition of this
+ * item that prompted the creation of this interface.
+ *
+ * Due to the nature of the beast, this interface is not a full-blown
+ * XPCOM component. The primary reason is that objects that implement
+ * this interface generally must be operational *before* XPCOM (or any
+ * of the rest of Mozilla) are initialized. As a result, this
+ * interface is instantiated by somewhat unconventional means.
+ *
+ * To create the implementor of this interface, you call the function
+ * NS_CreateNativeAppSupport. This is done in the startup code
+ * in nsAppRunner.cpp
+ *
+ * The interface provides these functions:
+ * start - You call this to inform the native app support that the
+ * application is starting. In addition, it serves as a
+ * query as to whether the application should continue to
+ * run.
+ *
+ * If the returned boolean result is PR_FALSE, then the
+ * application should exit without further processing. In
+ * such cases, the returned nsresult indicates whether the
+ * reason to exit is due to an error or not.
+ *
+ * Win32 Note: In the case of starting a second instance
+ * of this executable, this function will return
+ * PR_FALSE and nsresult==NS_OK. This means that
+ * the command line arguments have been
+ * successfully passed to the instance of the
+ * application acting as a DDE server.
+ *
+ * stop - You call this to inform the native app support that the
+ * application *wishes* to terminate. If the returned boolean
+ * value is PR_FALSE, then the application should continue
+ * (as if there were still additional top-level windows open).
+ *
+ * Win32 Note: If this is the instance of the application
+ * acting as the DDE server, and there are current
+ * DDE conversations active with other instances
+ * acting as DDE clients, then this function will
+ * return PR_FALSE.
+ *
+ * quit - Like Stop, but this method *forces* termination (or more
+ * precisely, indicates that the application is about to be
+ * terminated regardless of what a call to Stop might have
+ * returned.
+ *
+ * This method is intended to be called when the user selects
+ * the "Quit" option (close all windows and exit).
+ *
+ * Win32 Note: Stop is problematic in the case of "Quit" (close
+ * all windows and exit the application) because
+ * either we don't Quit or (potentially) we lose
+ * requests coming from other instances of the
+ * application. The strategy is to give preference
+ * to the user's explicit Quit request. In the
+ * unlikely event that a request is pending from
+ * another instance of the application, then such
+ * requests are essentially ignored. This is
+ * roughly equivalent to handling that request by
+ * opening a new window, followed by immediately
+ * closing it. Since this is the same as if the
+ * request came in immediately before the Quit
+ * call (versus immediately after it), no harm.
+ *
+ * There is an exposure here: Upon return from this
+ * function, any DDE connect request (for Mozilla)
+ * will fail and other instances of the application
+ * will start up as a DDE server. In that case,
+ * those instances may do things that conflict with
+ * the subsequent shutting down of the instance that
+ * is quitting. For this reason, the call to Quit
+ * should be deferred as long as possible.
+ *
+ * onLastWindowClosing - Called when the last window is closed. Used as a
+ * "soft" shutdown, passwords are flushed.
+ */
+
+interface nsIXULWindow;
+interface nsICmdLineService;
+
+[scriptable, uuid(5fdf8480-1f98-11d4-8077-00600811a9c3)]
+interface nsINativeAppSupport : nsISupports {
+ // Startup/shutdown.
+ boolean start();
+ void enable();
+ boolean stop();
+ void quit();
+
+ void onLastWindowClosing();
+ void ReOpen();
+};