michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIFile;
michael@0: interface nsIURL;
michael@0: 
michael@0: /**
michael@0:  * Provides access to crash reporting functionality.
michael@0:  *
michael@0:  * @status UNSTABLE - This interface is not frozen and will probably change in
michael@0:  *                    future releases.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(a2080795-e54c-4ecb-b001-bdc08a2021dd)]
michael@0: interface nsICrashReporter : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Get the enabled status of the crash reporter.
michael@0:    */
michael@0:   readonly attribute boolean enabled;
michael@0: 
michael@0:   /**
michael@0:    * Enable or disable crash reporting at runtime. Not available to script
michael@0:    * because the JS engine relies on proper exception handler chaining.
michael@0:    */
michael@0:   [noscript]
michael@0:   void setEnabled(in bool enabled);
michael@0: 
michael@0:   /**
michael@0:    * Get or set the URL to which crash reports will be submitted.
michael@0:    * Only https and http URLs are allowed, as the submission is handled
michael@0:    * by OS-native networking libraries.
michael@0:    *
michael@0:    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
michael@0:    * @throw NS_ERROR_INVALID_ARG on set if a non-http(s) URL is assigned
michael@0:    * @throw NS_ERROR_FAILURE on get if no URL is set
michael@0:    */
michael@0:   attribute nsIURL serverURL;
michael@0: 
michael@0:   /**
michael@0:    * Get or set the path on the local system to which minidumps will be
michael@0:    * written when a crash happens.
michael@0:    *
michael@0:    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
michael@0:    */
michael@0:   attribute nsIFile minidumpPath;
michael@0: 
michael@0:   /**
michael@0:    * Add some extra data to be submitted with a crash report.
michael@0:    *
michael@0:    * @param key
michael@0:    *        Name of the data to be added.
michael@0:    * @param data
michael@0:    *        Data to be added.
michael@0:    *
michael@0:    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
michael@0:    * @throw NS_ERROR_INVALID_ARG if key or data contain invalid characters.
michael@0:    *                             Invalid characters for key are '=' and
michael@0:    *                             '\n'.  Invalid character for data is '\0'.
michael@0:    */
michael@0:   void annotateCrashReport(in ACString key, in ACString data);
michael@0: 
michael@0:   /**
michael@0:    * Append some data to the "Notes" field, to be submitted with a crash report.
michael@0:    * Unlike annotateCrashReport, this method will append to existing data.
michael@0:    *
michael@0:    * @param data
michael@0:    *        Data to be added.
michael@0:    *
michael@0:    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
michael@0:    * @throw NS_ERROR_INVALID_ARG if data contains invalid characters.
michael@0:    *                             The only invalid character is '\0'.
michael@0:    */
michael@0:   void appendAppNotesToCrashReport(in ACString data);
michael@0: 
michael@0:   /**
michael@0:    * Register a given memory range to be included in the crash report.
michael@0:    *
michael@0:    * @param ptr
michael@0:    *        The starting address for the bytes.
michael@0:    * @param size
michael@0:    *        The number of bytes to include.
michael@0:    *
michael@0:    * @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
michael@0:    * @throw NS_ERROR_NOT_IMPLEMENTED if unavailable on the current OS
michael@0:    */
michael@0:   void registerAppMemory(in unsigned long long ptr, in unsigned long long size);
michael@0: 
michael@0:   /**
michael@0:    * Write a minidump immediately, with the user-supplied exception
michael@0:    * information. This is implemented on Windows only, because
michael@0:    * SEH (structured exception handling) exists on Windows only.
michael@0:    *
michael@0:    * @param aExceptionInfo  EXCEPTION_INFO* provided by Window's SEH
michael@0:    */
michael@0:   [noscript] void writeMinidumpForException(in voidPtr aExceptionInfo);
michael@0:   
michael@0:   /**
michael@0:    * Append note containing an Obj-C exception's info.
michael@0:    *
michael@0:    * @param aException  NSException object to append note for
michael@0:    */
michael@0:   [noscript] void appendObjCExceptionInfoToAppNotes(in voidPtr aException);
michael@0: 
michael@0:   /**
michael@0:    * User preference for submitting crash reports.
michael@0:    */
michael@0:   attribute boolean submitReports;
michael@0: 
michael@0:   /**
michael@0:    * Cause the crash reporter to re-evaluate where crash events should go.
michael@0:    *
michael@0:    * This should be called during application startup and whenever profiles
michael@0:    * change.
michael@0:    */
michael@0:   void UpdateCrashEventsDir();
michael@0: };