• file
• revisions
• annotate
• diff
• comparison
• raw

xpcom/system/nsICrashReporter.idl@b8a032363ba2 (annotated)

xpcom/system/nsICrashReporter.idl

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0	1	/* This Source Code Form is subject to the terms of the Mozilla Public
michael@0	2	* License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0	3	* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0	4
michael@0	5	#include "nsISupports.idl"
michael@0	6
michael@0	7	interface nsIFile;
michael@0	8	interface nsIURL;
michael@0	9
michael@0	10	/**
michael@0	11	* Provides access to crash reporting functionality.
michael@0	12	*
michael@0	13	* @status UNSTABLE - This interface is not frozen and will probably change in
michael@0	14	* future releases.
michael@0	15	*/
michael@0	16
michael@0	17	[scriptable, uuid(a2080795-e54c-4ecb-b001-bdc08a2021dd)]
michael@0	18	interface nsICrashReporter : nsISupports
michael@0	19	{
michael@0	20	/**
michael@0	21	* Get the enabled status of the crash reporter.
michael@0	22	*/
michael@0	23	readonly attribute boolean enabled;
michael@0	24
michael@0	25	/**
michael@0	26	* Enable or disable crash reporting at runtime. Not available to script
michael@0	27	* because the JS engine relies on proper exception handler chaining.
michael@0	28	*/
michael@0	29	[noscript]
michael@0	30	void setEnabled(in bool enabled);
michael@0	31
michael@0	32	/**
michael@0	33	* Get or set the URL to which crash reports will be submitted.
michael@0	34	* Only https and http URLs are allowed, as the submission is handled
michael@0	35	* by OS-native networking libraries.
michael@0	36	*
michael@0	37	* @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
michael@0	38	* @throw NS_ERROR_INVALID_ARG on set if a non-http(s) URL is assigned
michael@0	39	* @throw NS_ERROR_FAILURE on get if no URL is set
michael@0	40	*/
michael@0	41	attribute nsIURL serverURL;
michael@0	42
michael@0	43	/**
michael@0	44	* Get or set the path on the local system to which minidumps will be
michael@0	45	* written when a crash happens.
michael@0	46	*
michael@0	47	* @throw NS_ERROR_NOT_INITIALIZED if crash reporting is not initialized
michael@0	48	*/
michael@0	49	attribute nsIFile minidumpPath;
michael@0	50
michael@0	51	/**
michael@0	52	* Add some extra data to be submitted with a crash report.
michael@0	53	*
michael@0	54	* @param key
michael@0	55	* Name of the data to be added.
michael@0	56	* @param data
michael@0	57	* Data to be added.
michael@0	58	*
michael@0	59	* @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
michael@0	60	* @throw NS_ERROR_INVALID_ARG if key or data contain invalid characters.
michael@0	61	* Invalid characters for key are '=' and
michael@0	62	* '\n'. Invalid character for data is '\0'.
michael@0	63	*/
michael@0	64	void annotateCrashReport(in ACString key, in ACString data);
michael@0	65
michael@0	66	/**
michael@0	67	* Append some data to the "Notes" field, to be submitted with a crash report.
michael@0	68	* Unlike annotateCrashReport, this method will append to existing data.
michael@0	69	*
michael@0	70	* @param data
michael@0	71	* Data to be added.
michael@0	72	*
michael@0	73	* @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
michael@0	74	* @throw NS_ERROR_INVALID_ARG if data contains invalid characters.
michael@0	75	* The only invalid character is '\0'.
michael@0	76	*/
michael@0	77	void appendAppNotesToCrashReport(in ACString data);
michael@0	78
michael@0	79	/**
michael@0	80	* Register a given memory range to be included in the crash report.
michael@0	81	*
michael@0	82	* @param ptr
michael@0	83	* The starting address for the bytes.
michael@0	84	* @param size
michael@0	85	* The number of bytes to include.
michael@0	86	*
michael@0	87	* @throw NS_ERROR_NOT_INITIALIZED if crash reporting not initialized
michael@0	88	* @throw NS_ERROR_NOT_IMPLEMENTED if unavailable on the current OS
michael@0	89	*/
michael@0	90	void registerAppMemory(in unsigned long long ptr, in unsigned long long size);
michael@0	91
michael@0	92	/**
michael@0	93	* Write a minidump immediately, with the user-supplied exception
michael@0	94	* information. This is implemented on Windows only, because
michael@0	95	* SEH (structured exception handling) exists on Windows only.
michael@0	96	*
michael@0	97	* @param aExceptionInfo EXCEPTION_INFO* provided by Window's SEH
michael@0	98	*/
michael@0	99	[noscript] void writeMinidumpForException(in voidPtr aExceptionInfo);
michael@0	100
michael@0	101	/**
michael@0	102	* Append note containing an Obj-C exception's info.
michael@0	103	*
michael@0	104	* @param aException NSException object to append note for
michael@0	105	*/
michael@0	106	[noscript] void appendObjCExceptionInfoToAppNotes(in voidPtr aException);
michael@0	107
michael@0	108	/**
michael@0	109	* User preference for submitting crash reports.
michael@0	110	*/
michael@0	111	attribute boolean submitReports;
michael@0	112
michael@0	113	/**
michael@0	114	* Cause the crash reporter to re-evaluate where crash events should go.
michael@0	115	*
michael@0	116	* This should be called during application startup and whenever profiles
michael@0	117	* change.
michael@0	118	*/
michael@0	119	void UpdateCrashEventsDir();
michael@0	120	};