gecko/xpcom/base/nsIExceptionService.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* 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"
#include "nsIException.idl"

// An exception provider.  These can turn special nsresult codes
// into nsIExceptions

[scriptable, uuid(0577744c-c1d2-47f2-8bcc-ce7a9e5a88fc)]
interface nsIExceptionProvider : nsISupports
{
    /** Gets an nsIException or returns NULL if not possible. **/
    nsIException getException(in nsresult result, in nsIException defaultException);
};

// A ScriptErrorManager for a single thread.  These objects
// are _not_ thread-safe.  Use the ScriptErrorService
// to get a script error manager for your current thread.
[scriptable, uuid(efc9d00b-231c-4feb-852c-ac017266a415)]
interface nsIExceptionManager : nsISupports
{
    /** Sets (or clears with nsnull) the current error on the this thread. */
    void setCurrentException( in nsIException error);

    /** Gets the current error for the current thread, or NULL if no error */
     nsIException getCurrentException();

    /** Gets an exception from a registered exception provider..
        This has no effect on the "current exception" */
    nsIException getExceptionFromProvider( in nsresult rc, in nsIException defaultException);
};


// The Exception Service.  Allows you to get an set exceptions in a thread
// safe manner, or to get an ExceptionManager for your specific thread.
[scriptable, uuid(35A88F54-F267-4414-92A7-191F6454AB52)]
interface nsIExceptionService : nsIExceptionManager
{
    /** Obtains an exception manager for the current thread. */
    readonly attribute nsIExceptionManager currentExceptionManager;

    /** Installs an "exception provider" which is capable of
        translating an nsresult into an exception.  This enables
        error providers to return simple nsresults and only provide
        rich errors when specifically requested. It also has the
        advantage of allowing code like the DOM to handle all errors
        in a single function rather than at each XPCOM entry point.
        NOTE: This interface must be thread-safe - it will be called
        on whatever thread needs the error translation performed.*/
    void registerExceptionProvider( in nsIExceptionProvider provider, in PRUint32 moduleCode );
    void unregisterExceptionProvider( in nsIExceptionProvider provider, in PRUint32 moduleCode );
};


%{ C++
#define NS_EXCEPTIONSERVICE_CLASSNAME "Exception Service"
// {35A88F54-F267-4414-92A7-191F6454AB52}
#define NS_EXCEPTIONSERVICE_CID \
{ 0x35a88f54, 0xf267, 0x4414, { 0x92, 0xa7, 0x19, 0x1f, 0x64, 0x54, 0xab, 0x52 } }
#define NS_EXCEPTIONSERVICE_CONTRACTID "@mozilla.org/exceptionservice;1"
%}