#include "nsISupports.idl"
#include "nsINativeMsg.idl"

/**
 * The nsIDispatchListener defines the callback listener interface that
 * can be passed to the Run routine on and event loop.  This allows 
 * application override or additions to the default dispatching event mechanism.    
 */						  

[scriptable, uuid(2EFB5007-4508-11d3-AEDA-00A024FFC08C)]
interface nsIDispatchListener : nsISupports
{
	/* Called just before the nsIEventLoop::DispatchMessage() is called.
	   This allows a listener first crack at dispatching Messages.  The 
		listener can then control if DispatchMessage() is called via the
		return.

	@param msg This is the native message that has been retrieved from the Queue
					and awaiting dispatching.

	@return NS_OK - Indicates nsIEventLoop::DispatchMessage() should be called
						 following the return from this function.
			NS_FALSE - Processing went successfully, but 
						 nsIEventLoop::DispatchMessage() should not be called.
			NS_ERROR_FAILURE - Catastrophic processing failure.  Event loop should
						 die immediately.
	*/
	void PreDispatch(in nsINativeMsg msg);

	/*
		Called just after the nsIEventLoop::DispatchMessage() has been called.

	@param msg This is the native message that has been retrieved from the Queue
					and awaiting dispatching.

	@param fDispatchHandled Indicates if nsIEventLoop::DispatchMessage() handled
					the message being passed in.

	@return NS_OK - Processing completed fine.
				NS_ERROR_FAILURE - Catastrophic processing failure.  Event loop 
				should die immediately.
	*/
	void PostDispatch(in nsINativeMsg msg, in boolean fDispatchHandled);
};