introduce DBG_UNHANDLED_EXCEPTION_WHEN for calls with an explanatory message

Change-Id: Ic80f2ed2c0fdff20d1ee1968bec2840bf914fb5e

include/tools/diagnose_ex.h

@@ -27,7 +27,9 @@
 
 #include <tools/toolsdllapi.h>
 
-TOOLS_DLLPUBLIC void DbgUnhandledException(const css::uno::Any& caughtException, const char* currentFunction, const char* fileAndLineNo);
+TOOLS_DLLPUBLIC void DbgUnhandledException(const css::uno::Any& caughtException,
+        const char* currentFunction, const char* fileAndLineNo,
+        const char* explanatory = nullptr);
 
 #if OSL_DEBUG_LEVEL > 0
     #include <com/sun/star/configuration/CorruptedConfigurationException.hpp>
@@ -43,8 +45,12 @@ TOOLS_DLLPUBLIC void DbgUnhandledException(const css::uno::Any& caughtException,
     #define DBG_UNHANDLED_EXCEPTION()   \
         DbgUnhandledException( ::cppu::getCaughtException(), OSL_THIS_FUNC, SAL_DETAIL_WHERE);
 
+    #define DBG_UNHANDLED_EXCEPTION_WHEN(explain)   \
+        DbgUnhandledException( ::cppu::getCaughtException(), OSL_THIS_FUNC, SAL_DETAIL_WHERE, explain);
+
 #else   // OSL_DEBUG_LEVEL
     #define DBG_UNHANDLED_EXCEPTION()
+    #define DBG_UNHANDLED_EXCEPTION_WHEN(explain)
 #endif  // OSL_DEBUG_LEVEL
 
 /** This macro asserts the given condition (in debug mode), and throws

tools/source/debug/debug.cxx

@@ -76,10 +76,16 @@ void DbgTestSolarMutex()
 
 #endif
 
-void DbgUnhandledException(const css::uno::Any & caught, const char* currentFunction, const char* fileAndLineNo)
+void DbgUnhandledException(const css::uno::Any & caught, const char* currentFunction, const char* fileAndLineNo,
+        const char* explanatory)
 {
         OString sMessage( "DBG_UNHANDLED_EXCEPTION in " );
         sMessage += currentFunction;
+        if (explanatory)
+        {
+            sMessage += "\n    when: ";
+            sMessage += explanatory;
+        }
         sMessage += "\n    type: ";
         sMessage += OUStringToOString( caught.getValueTypeName(), osl_getThreadTextEncoding() );
         css::uno::Exception exception;