INTEGRATION: CWS unopkg (1.5.74); FILE MERGED

2003/09/26 15:10:32 dbo 1.5.74.2: #112449# additional documentation
2003/09/26 13:01:31 dbo 1.5.74.1: #112449# added ::cppu::getCaughtException()

1 files changed, 58 insertions, 5 deletions

diff --git a/cppuhelper/inc/cppuhelper/exc_hlp.hxx b/cppuhelper/inc/cppuhelper/exc_hlp.hxx
index 5a1df4c36c2e..384f0c286e16 100644
--- a/cppuhelper/inc/cppuhelper/exc_hlp.hxx
+++ b/cppuhelper/inc/cppuhelper/exc_hlp.hxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: exc_hlp.hxx,v $
  *
- *  $Revision: 1.5 $
+ *  $Revision: 1.6 $
  *
- *  last change: $Author: dbo $ $Date: 2001-11-09 13:49:15 $
+ *  last change: $Author: vg $ $Date: 2003-10-06 12:50:24 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -69,14 +69,67 @@
 namespace cppu
 {
 
-/** This function throws the exception given by rExc. The given value has to be of type
-    class EXCEPTION and must be dervived from or of type com.sun.star.uno.Exception.
+/** This function throws the exception given by rExc.  The given value has to
+    be of typeclass EXCEPTION and must be dervived from or of
+    type com.sun.star.uno.Exception.
 
-    @param rExc exception to be thrown.
+    @param rExc
+           exception to be thrown.
 */
 void SAL_CALL throwException( const ::com::sun::star::uno::Any & rExc )
     SAL_THROW( (::com::sun::star::uno::Exception) );
 
+/** @internal
+                Not for public use!
+
+    Currently under investigation if this function runs with all known
+    C++-UNO bridges.  Until now tested for:
+
+    - CC5, Solaris SPARC
+    - MSVC .NET 2002/2003, Windows
+    - gcc 3.2.2, Linux Intel
+
+
+    Use this function to get the dynamic type of a caught C++-UNO exception,
+    e.g.
+
+    try
+    {
+        ...
+    }
+    catch (::com::sun::star::uno::Exception &)
+    {
+        ::com::sun::star::uno::Any caught( ::cppu::getCaughtException() );
+        ...
+    }
+
+    Restrictions:
+
+    - only use for caught UNO exceptions
+      (C++ exceptions derived from com::sun::star::uno::Exception)
+    - only as first statement in a catch block!
+    - never do a C++ rethrow (throw;) again after you have called this function
+      and call getCaughtException() just once!
+      (function internally uses a C++ rethrow)
+
+    @return
+              caught UNO exception
+
+    @attention
+              This function is limited to the same C++ compiler runtime library.
+              E.g. for MSVC, this means that the catch handler code (the one
+              that calls getCaughtException()) needs to use the very same
+              msvcrt.dll as cppuhelper3MSC.dll and the bridge msci_uno.dll,
+              e.g. all them are compiled with the same compiler version.
+              This is because the msci_uno.dll gets a rethrown exception out
+              of the internal msvcrt.dll thread local data (tls).
+              Thus you must not use this function if your code needs to run
+              in newer UDK versions without being recompiled, because those
+              newer UDK (-> OOo versions) potentially use a newer MSVC
+              (which potentially uses an incompatible msvcrt.dll).
+*/
+::com::sun::star::uno::Any SAL_CALL getCaughtException();
+
 }
 
 #endif