INTEGRATION: CWS dba30 (1.13.132); FILE MERGED

2005/09/29 22:58:36 fs 1.13.132.2: RESYNC: (1.13-1.14); FILE MERGED
2005/04/06 07:02:21 fs 1.13.132.1: #i46768# additional Settings property, for convenient access ot the Info sequence

1 files changed, 38 insertions, 6 deletions

diff --git a/offapi/com/sun/star/sdb/DataSource.idl b/offapi/com/sun/star/sdb/DataSource.idl
index 2279a76b1228..6ee5c1a626b8 100644
--- a/offapi/com/sun/star/sdb/DataSource.idl
+++ b/offapi/com/sun/star/sdb/DataSource.idl
@@ -4,9 +4,9 @@
  *
  *  $RCSfile: DataSource.idl,v $
  *
- *  $Revision: 1.14 $
+ *  $Revision: 1.15 $
  *
- *  last change: $Author: rt $ $Date: 2005-09-08 03:14:51 $
+ *  last change: $Author: hr $ $Date: 2006-08-15 10:34:35 $
  *
  *  The Contents of this file are made available subject to
  *  the terms of GNU Lesser General Public License Version 2.1.
@@ -136,12 +136,44 @@ published service DataSource
     [property] string URL;
 
 
-    /** is a list of arbitrary string tag/value pairs as
-             connection arguments; normally at least a "user" and
-             "password" property should be included.
-     */
+    /** is a list of arbitrary string tag/value pairs as connection arguments
+
+        <p>The <type>DataSource</type> itself does not attempt to interpret any of those values.</p>
+
+        <p>Instead, the values in this property have two use cases:
+        <ul><li>Upon creating a connection, for every value in this sequence it's checked
+                whether the <type scope="com::sun::star::sdbc">XDriver</type> which is to provide
+                the connection supports a setting with the respective name, using its
+                <member scope="com::sun::star::sdbc">XDriver::getPropertyInfo<member> method.br/>
+                If so, the settings is passed to the drivers's
+                <member scope="com::sun::star::sdbc">XDriver::connect<member> method. If not,
+                the setting is ignored.</li>
+            <li>External components may use the settings to carry arbitrary information with
+                the data source. Usually, this is used to control the behaviour of components
+                working with the data source.</li>
+        </ul>
+    */
     [property] sequence<com::sun::star::beans::PropertyValue> Info;
 
+    /** is a convenience wrapper around the <member>Info</member> property.
+
+        <p>Since fiddling around with a sequence of property values is somewhat uncomfortable
+        in all known UNO language bindings (especially for tasks like simply changing the value
+        of an existing value), the <member>Settings</member> property wraps the <member>Info</member>
+        property for easier single-value access.</p>
+
+        <p>The object represented by this property supports the <type scope="com::sun::star::beans">PropertyBag</type>
+        service. That is, you can at runtime add arbitrary new properties to the bag.</p>
+
+        <p>Additionally, the property bag supports default values of properties, and thus the
+        <type scope="com::sun::star::beans">XPropertyState</type> interface. If you add an own property to
+        the bag using <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member>, you need
+        to specifiy an initial value, which is also used as default value.</p>
+
+        <p>You should use the <member>Setting</member> property if you need to access a few properties only,
+        and the <member>Info</member> property if you need access to all existent settings at once.</p>
+    */
+    [property, readonly, optional] com::sun::star::beans::XPropertySet Settings;
 
     /** determines a users login name.
      */