include/connectivity/dbtools.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_CONNECTIVITY_DBTOOLS_HXX
  21 #define INCLUDED_CONNECTIVITY_DBTOOLS_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <string_view>
  26
  27 #include <connectivity/dbexception.hxx>
  28 #include <comphelper/stl_types.hxx>
  29 #include <unotools/sharedunocomponent.hxx>
  30 #include <connectivity/dbtoolsdllapi.hxx>
  31 #include <connectivity/FValue.hxx>
  32
  33 namespace com::sun::star {
  34
  35 namespace sdb {
  36     class XSingleSelectQueryComposer;
  37 }
  38 namespace sdbcx {
  39     class XTablesSupplier;
  40 }
  41 namespace sdbc {
  42     class XConnection;
  43     class XDatabaseMetaData;
  44     class XRowSet;
  45     class XDataSource;
  46     class SQLException;
  47     class XParameters;
  48     class XRowUpdate;
  49 }
  50 namespace beans {
  51     class XPropertySet;
  52 }
  53 namespace awt {
  54     class XWindow;
  55 }
  56 namespace lang {
  57     struct Locale;
  58 }
  59 namespace container {
  60     class XNameAccess;
  61 }
  62 namespace uno {
  63     class XComponentContext;
  64 }
  65 namespace util {
  66     class XNumberFormatTypes;
  67     class XNumberFormatsSupplier;
  68 }
  69 namespace task {
  70     class XInteractionHandler;
  71 }
  72
  73 }
  74
  75 class SvStream;
  76
  77 namespace dbtools
  78 {
  79     class ISQLStatementHelper;
  80     typedef ::utl::SharedUNOComponent< css::sdbc::XConnection > SharedConnection;
  81
  82     enum class EComposeRule
  83     {
  84         InTableDefinitions,
  85         InIndexDefinitions,
  86         InDataManipulation,
  87         InProcedureCalls,
  88         InPrivilegeDefinitions,
  89         Complete
  90     };
  91
  92     // date conversion
  93
  94     // calculates the default numberformat for a given datatype and a give language
  95     OOO_DLLPUBLIC_DBTOOLS
  96     sal_Int32 getDefaultNumberFormat(const css::uno::Reference< css::beans::XPropertySet >& _xColumn,
  97                                      const css::uno::Reference< css::util::XNumberFormatTypes >& _xTypes,
  98                                      const css::lang::Locale& _rLocale);
  99
 100     // calculates the default numberformat for a given datatype and a give language
 101     // @param  _nDataType @see com.sun.star.sdbc.DataType
 102     // @param _nScale       can be zero
 103     OOO_DLLPUBLIC_DBTOOLS
 104     sal_Int32 getDefaultNumberFormat(sal_Int32 _nDataType,
 105                                      sal_Int32 _nScale,
 106                                      bool _bIsCurrency,
 107                                      const css::uno::Reference< css::util::XNumberFormatTypes >& _xTypes,
 108                                      const css::lang::Locale& _rLocale);
 109
 110
 111     /** creates a connection which can be used for the rowset given
 112
 113         The function tries to obtain a connection for the row set with the following
 114         steps (in this order):
 115         <nl>
 116             <li>If the rowset already has an ActiveConnection (means a non-<NULL/> value for this property),
 117                 this one is used.</li>
 118             <li>If row set is part of a database form document (see ->isEmbeddedInDatabase),
 119                 a connection for the respective database is used.</li>
 120             <li>If in the parent hierarchy of the row set, there is an object supporting
 121                 the XConnection interface, this one is returned.</li>
 122             <li>If the DataSourceName property of the row set is not empty, a connection for this
 123                 data source is retrieved.</li>
 124             <li>If the URL property of the row set is not empty, a connection for this URL is
 125                 retrieved from the driver manager.
 126         </nl>
 127
 128         The calculated connection is set as ActiveConnection property on the rowset.
 129
 130         If the connection was newly created by the method, then
 131         the ownership of the connection is delivered to a temporary object, which observes the
 132         row set: As soon as a connection-relevant property of the row set changes, or as soon
 133         as somebody else sets another ActiveConnection at the row set, the original
 134         connection (the one which this function calculated) is disposed and discarded. At this
 135         very moment, also the temporary observer object dies. This way, it is ensured that
 136         there's no resource leak from an un-owned connection object.
 137
 138         @param _rxRowSet
 139             the row set
 140
 141         @param _rxFactory
 142             a service factory, which can be used to create data sources, interaction handler etc (the usual stuff)
 143
 144     */
 145     OOO_DLLPUBLIC_DBTOOLS
 146     css::uno::Reference< css::sdbc::XConnection> connectRowset(
 147         const css::uno::Reference< css::sdbc::XRowSet>& _rxRowSet,
 148         const css::uno::Reference< css::uno::XComponentContext>& _rxContext,
 149         const css::uno::Reference< css::awt::XWindow>& _rxParent
 150     );
 151
 152     /** ensures that a row set has a valid ActiveConnection, if possible
 153
 154         This function does nearly the same as ->connectRowset. In fact, it is to be preferred over
 155         ->connectRowset, if possible.
 156
 157         There are a few differences:
 158         <ul><li>If a connection could be determined for the given RowSet, it is always
 159                 set as ActiveConnection.</li>
 160             <li>Definition of the ownership of the created connection allows for more scenarios:
 161                 <ul><li>If the connection was not newly created, the returned ->SharedConnection
 162                         instance will not have the ownership, since in this case it's assumed
 163                         that there already is an instance which has the ownership.</li>
 164                     <li>If the connection was newly created, then the returned SharedConnection
 165                         instance will have the ownership of the XConnection.</li>
 166                 </ul>
 167             </li>
 168         </ul>
 169     */
 170     OOO_DLLPUBLIC_DBTOOLS SharedConnection    ensureRowSetConnection(
 171         const css::uno::Reference< css::sdbc::XRowSet>& _rxRowSet,
 172         const css::uno::Reference< css::uno::XComponentContext>& _rxContext,
 173         const css::uno::Reference< css::awt::XWindow>& _rxParent
 174     );
 175
 176     /** returns the connection the RowSet is currently working with (which is the ActiveConnection property)
 177
 178         @throws css::uno::RuntimeException
 179     */
 180     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::sdbc::XConnection> getConnection(const css::uno::Reference< css::sdbc::XRowSet>& _rxRowSet);
 181     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::sdbc::XConnection> getConnection_withFeedback(
 182             const OUString& _rDataSourceName,
 183             const OUString& _rUser,
 184             const OUString& _rPwd,
 185             const css::uno::Reference< css::uno::XComponentContext>& _rxContext,
 186             const css::uno::Reference< css::awt::XWindow>& _rxParent);
 187
 188
 189     /** determines whether the given component is part of a document which is an embedded database
 190         document (such as a form)
 191     */
 192     OOO_DLLPUBLIC_DBTOOLS bool    isEmbeddedInDatabase(
 193                 const css::uno::Reference< css::uno::XInterface >& _rxComponent,
 194                 css::uno::Reference< css::sdbc::XConnection >& _rxActualConnection
 195             );
 196
 197     /** returns the columns of the named table of the given connection
 198     */
 199     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::container::XNameAccess> getTableFields(
 200         const css::uno::Reference< css::sdbc::XConnection>& _rxConn,
 201         const OUString& _rName
 202     );
 203
 204     /** returns the primary key columns of the table
 205     */
 206     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::container::XNameAccess> getPrimaryKeyColumns_throw(
 207         const css::uno::Any& i_aTable
 208     );
 209     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::container::XNameAccess> getPrimaryKeyColumns_throw(
 210         const css::uno::Reference< css::beans::XPropertySet >& i_xTable
 211     );
 212
 213     /** get fields for a result set given by a "command descriptor"
 214
 215         <p>A command descriptor here means:
 216         <ul><li>a SDB-level connection (com.sun.star.sdb::Connection</li>
 217             <li>a string specifying the name of an object relative to the connection</li>
 218             <li>a com.sun.star.sdb::CommandType value specifying the type
 219                 of the object</type></li>
 220         </ul>
 221         </p>
 222
 223         @param _rxConnection
 224             the connection relative to which the to-be-examined object exists
 225
 226         @param _nCommandType
 227             the type of the object
 228
 229         @param _rCommand
 230             the object. This may be a table name, a query name, or an SQL statement, depending on the value
 231             of <arg>_nCommandType</arg>
 232
 233         @param _rxCollectionOner
 234             If (and only if) <arg>CommandType</arg> is CommandType.COMMAND, the fields collection which is returned
 235             by this function here is a temporary object. It is kept alive by another object, which is to be
 236             created temporarily, too. To ensure that the fields you get are valid as long as you need them,
 237             the owner which controls their life time is transferred to this parameter upon return.<br/>
 238
 239             Your fields live as long as this component lives.<br/>
 240
 241             Additionally, you are encouraged to dispose this component as soon as you don't need the fields anymore.
 242             It depends on the connection's implementation if this is necessary, but the is no guarantee, so to
 243             be on the safe side with respect to resource leaks, you should dispose the component.
 244
 245         @param _pErrorInfo
 246             If not <NULL/>, then upon return from the function the instance pointed to by this argument will
 247             contain any available error information in case something went wrong.
 248
 249         @return
 250             the container of the columns (aka fields) of the object
 251     */
 252     OOO_DLLPUBLIC_DBTOOLS
 253     css::uno::Reference< css::container::XNameAccess >
 254         getFieldsByCommandDescriptor(
 255             const css::uno::Reference< css::sdbc::XConnection >& _rxConnection,
 256             const sal_Int32 _nCommandType,
 257             const OUString& _rCommand,
 258             css::uno::Reference< css::lang::XComponent >& _rxKeepFieldsAlive,
 259             SQLExceptionInfo* _pErrorInfo = nullptr
 260         );
 261
 262
 263     /** get fields for a result set given by a "command descriptor"
 264
 265         <p>A command descriptor here means:
 266         <ul><li>a SDB-level connection (com.sun.star.sdb::Connection</li>
 267             <li>a string specifying the name of an object relative to the connection</li>
 268             <li>a com.sun.star.sdb::CommandType value specifying the type
 269                 of the object</type></li>
 270         </ul>
 271         </p>
 272
 273         @param _rxConnection
 274             the connection relative to which the to-be-examined object exists
 275
 276         @param _nCommandType
 277             the type of the object
 278
 279         @param _rCommand
 280             the object. This may be a table name, a query name, or an SQL statement, depending on the value
 281             of <arg>_nCommandType</arg>
 282
 283         @param _pErrorInfo
 284             If not <NULL/>, then upon return from the function the instance pointed to by this argument will
 285             contain any available error information in case something went wrong.
 286
 287         @return
 288             an array of strings containing the names of the columns (aka fields) of the object
 289     */
 290     OOO_DLLPUBLIC_DBTOOLS css::uno::Sequence< OUString >
 291         getFieldNamesByCommandDescriptor(
 292             const css::uno::Reference< css::sdbc::XConnection >& _rxConnection,
 293             const sal_Int32 _nCommandType,
 294             const OUString& _rCommand,
 295             SQLExceptionInfo* _pErrorInfo = nullptr
 296         );
 297
 298
 299     /** create a new css::sdbc::SQLContext, fill it with the given descriptions and the given source,
 300         and <i>append</i> _rException (i.e. put it into the NextException member of the SQLContext).
 301     */
 302     OOO_DLLPUBLIC_DBTOOLS
 303     css::sdbc::SQLException prependErrorInfo(
 304         const css::sdbc::SQLException& _rChainedException,
 305         const css::uno::Reference< css::uno::XInterface >& _rxContext,
 306         const OUString& _rAdditionalError,
 307         const StandardSQLState _eSQLState = StandardSQLState::ERROR_UNSPECIFIED);
 308
 309     /** search the parent hierarchy for a data source.
 310     */
 311     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::sdbc::XDataSource> findDataSource(const css::uno::Reference< css::uno::XInterface >& _xParent);
 312
 313     /** determines the value of a boolean data source setting, given by ASCII name
 314
 315         @param _rxConnection
 316             the connection belonging to the data source whose setting is to be retrieved
 317         @param _pAsciiSettingName
 318             the ASCII name of the setting
 319     */
 320     OOO_DLLPUBLIC_DBTOOLS bool getBooleanDataSourceSetting(
 321             const css::uno::Reference< css::sdbc::XConnection >& _rxConnection,
 322             const char* _pAsciiSettingName
 323         );
 324     OOO_DLLPUBLIC_DBTOOLS bool getBooleanDataSourceSetting(
 325             const css::uno::Reference< css::sdbc::XConnection >& _rxConnection,
 326             const OUString& rSettingName
 327         );
 328
 329     /** check if a specific property is enabled in the info sequence
 330         @deprecated
 331             Use getBooleanDataSourceSetting instead, which cares for the default of the property itself,
 332             instead of spreading this knowledge through all callers.
 333     */
 334     OOO_DLLPUBLIC_DBTOOLS
 335     bool isDataSourcePropertyEnabled(const css::uno::Reference< css::uno::XInterface>& _xProp,
 336                                      const OUString& _sProperty,
 337                                            bool _bDefault);
 338
 339     /** retrieves a particular indirect data source setting
 340
 341         @param _rxDataSource
 342             a data source component
 343         @param _pAsciiSettingsName
 344             the ASCII name of the setting to obtain
 345         @param _rSettingsValue
 346             the value of the setting, upon successful return
 347
 348         @return
 349             <FALSE/> if the setting is not present in the <member scope="css::sdb">DataSource::Info</member>
 350             member of the data source
 351             <TRUE/> otherwise
 352     */
 353     OOO_DLLPUBLIC_DBTOOLS
 354     bool    getDataSourceSetting(
 355         const css::uno::Reference< css::uno::XInterface >& _rxDataSource,
 356         const char* _pAsciiSettingsName,
 357         css::uno::Any& /* [out] */ _rSettingsValue
 358     );
 359     OOO_DLLPUBLIC_DBTOOLS
 360     bool    getDataSourceSetting(
 361         const css::uno::Reference< css::uno::XInterface >& _rxDataSource,
 362         const OUString& _sSettingsName,
 363         css::uno::Any& /* [out] */ _rSettingsValue
 364     );
 365
 366     OOO_DLLPUBLIC_DBTOOLS OUString getDefaultReportEngineServiceName(const css::uno::Reference< css::uno::XComponentContext>& _rxFactory);
 367
 368     /** quote the given name with the given quote string.
 369     */
 370     OOO_DLLPUBLIC_DBTOOLS OUString quoteName(std::u16string_view _rQuote, const OUString& _rName);
 371
 372     /** quote the given table name (which may contain a catalog and a schema) according to the rules provided by the meta data
 373     */
 374     OOO_DLLPUBLIC_DBTOOLS
 375     OUString quoteTableName(const css::uno::Reference< css::sdbc::XDatabaseMetaData>& _rxMeta
 376                                     , const OUString& _rName
 377                                     ,EComposeRule _eComposeRule);
 378
 379     /** split a fully qualified table name (including catalog and schema, if applicable) into its component parts.
 380         @param  _rxConnMetaData     meta data describing the connection where you got the table name from
 381         @param  _rQualifiedName     fully qualified table name
 382         @param  _rCatalog           (out parameter) upon return, contains the catalog name
 383         @param  _rSchema            (out parameter) upon return, contains the schema name
 384         @param  _rName              (out parameter) upon return, contains the table name
 385         @param  _eComposeRule       where do you need the name for
 386     */
 387     OOO_DLLPUBLIC_DBTOOLS void qualifiedNameComponents(const css::uno::Reference< css::sdbc::XDatabaseMetaData >& _rxConnMetaData,
 388         const OUString& _rQualifiedName, OUString& _rCatalog, OUString& _rSchema, OUString& _rName,EComposeRule _eComposeRule);
 389
 390     /** calculate a NumberFormatsSupplier for use with a given connection
 391         @param      _rxConn         the connection for which the formatter is requested
 392         @param      _bAllowDefault  if the connection (and related components, such as its parent) cannot supply
 393                                     a formatter, we can ask the DatabaseEnvironment for a default one. This parameter
 394                                     states if this is allowed.
 395         @param      _rxFactory      required (only of _bAllowDefault is sal_True) for creating the DatabaseEnvironment.
 396         @return     the formatter all object related to the given connection should work with.
 397     */
 398     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::util::XNumberFormatsSupplier> getNumberFormats(
 399         const css::uno::Reference< css::sdbc::XConnection>& _rxConn,
 400         bool _bAllowDefault = false,
 401         const css::uno::Reference< css::uno::XComponentContext>& _rxContext = css::uno::Reference< css::uno::XComponentContext>()
 402     );
 403
 404     /** create a css::sdb::XSingleSelectQueryComposer which represents
 405         the current settings (Command/CommandType/Filter/Order) of the given rowset.
 406
 407         As such an instance can be obtained from a css::sdb::Connection
 408         only the function searches for the connection the RowSet is using via connectRowset.
 409         This implies that a connection will be set on the RowSet if needed.
 410         (need to changes this sometimes ...)
 411     */
 412     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::sdb::XSingleSelectQueryComposer > getCurrentSettingsComposer(
 413         const css::uno::Reference< css::beans::XPropertySet>& _rxRowSetProps,
 414         const css::uno::Reference< css::uno::XComponentContext>& _rxContext,
 415         const css::uno::Reference< css::awt::XWindow>& _rxParent
 416     );
 417
 418     /** transfer and translate properties between two FormComponents
 419         @param      _rxOld      the source property set
 420         @param      _rxNew      the destination property set
 421         @param      _rLocale    the locale for converting number related properties
 422     */
 423     OOO_DLLPUBLIC_DBTOOLS void TransferFormComponentProperties(
 424         const css::uno::Reference< css::beans::XPropertySet>& _rxOld,
 425         const css::uno::Reference< css::beans::XPropertySet>& _rxNew,
 426         const css::lang::Locale& _rLocale
 427         );
 428
 429     /** check if the property "Privileges" supports css::sdbcx::Privilege::INSERT
 430         @param      _rxCursorSet    the property set
 431     */
 432     OOO_DLLPUBLIC_DBTOOLS bool canInsert(const css::uno::Reference< css::beans::XPropertySet>& _rxCursorSet);
 433     /** check if the property "Privileges" supports css::sdbcx::Privilege::UPDATE
 434         @param      _rxCursorSet    the property set
 435     */
 436     OOO_DLLPUBLIC_DBTOOLS bool canUpdate(const css::uno::Reference< css::beans::XPropertySet>& _rxCursorSet);
 437     /** check if the property "Privileges" supports css::sdbcx::Privilege::DELETE
 438         @param      _rxCursorSet    the property set
 439     */
 440     OOO_DLLPUBLIC_DBTOOLS bool canDelete(const css::uno::Reference< css::beans::XPropertySet>& _rxCursorSet);
 441
 442
 443     /** compose a complete table name from its up to three parts, regarding to the database meta data composing rules
 444     */
 445     OOO_DLLPUBLIC_DBTOOLS OUString composeTableName( const css::uno::Reference< css::sdbc::XDatabaseMetaData >& _rxMetaData,
 446                             const OUString& _rCatalog,
 447                             const OUString& _rSchema,
 448                             const OUString& _rName,
 449                             bool _bQuote,
 450                             EComposeRule _eComposeRule);
 451
 452     /** composes a table name for usage in a SELECT statement
 453
 454         This includes quoting of the table as indicated by the connection's meta data, plus respecting
 455         the settings "UseCatalogInSelect" and "UseSchemaInSelect", which might be present
 456         in the data source which the connection belongs to.
 457     */
 458     OOO_DLLPUBLIC_DBTOOLS OUString composeTableNameForSelect(
 459                             const css::uno::Reference< css::sdbc::XConnection >& _rxConnection,
 460                             const OUString& _rCatalog,
 461                             const OUString& _rSchema,
 462                             const OUString& _rName );
 463
 464     /** composes a table name for usage in a SELECT statement
 465
 466         This includes quoting of the table as indicated by the connection's meta data, plus respecting
 467         the settings "UseCatalogInSelect" and "UseSchemaInSelect", which might be present
 468         in the data source which the connection belongs to.
 469     */
 470     OOO_DLLPUBLIC_DBTOOLS OUString composeTableNameForSelect(
 471                             const css::uno::Reference< css::sdbc::XConnection >& _rxConnection,
 472                             const css::uno::Reference< css::beans::XPropertySet>& _xTable );
 473
 474     /** compose the table name out of the property set which must support the properties from the service <member scope= "css::sdbcx">table</member>
 475         @param  _xMetaData
 476             The metadata from the connection.
 477         @param  _xTable
 478             The table.
 479     */
 480     OOO_DLLPUBLIC_DBTOOLS OUString composeTableName(
 481         const css::uno::Reference< css::sdbc::XDatabaseMetaData>& _xMetaData,
 482         const css::uno::Reference< css::beans::XPropertySet>& _xTable,
 483         EComposeRule _eComposeRule,
 484         bool _bQuote);
 485
 486
 487     OOO_DLLPUBLIC_DBTOOLS sal_Int32 getSearchColumnFlag( const css::uno::Reference< css::sdbc::XConnection>& _rxConn,
 488                                     sal_Int32 _nDataType);
 489     // return the datasource for the given datasource name
 490     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::sdbc::XDataSource> getDataSource(const OUString& _rsDataSourceName,
 491                         const css::uno::Reference< css::uno::XComponentContext>& _rxContext);
 492
 493     /** search for a name that is NOT in the NameAcces
 494         @param  _rxContainer
 495             the NameAccess container to search in
 496         @param  _rBaseName
 497             the base name that should be used to create the new name
 498         @param  _bStartWithNumber
 499             When <TRUE/> the name ends with number even when the name itself doesn't occur in the collection.
 500         @return
 501             A name which doesn't exist in the collection.
 502     */
 503     OOO_DLLPUBLIC_DBTOOLS
 504     OUString createUniqueName(const css::uno::Reference< css::container::XNameAccess>& _rxContainer,
 505                                      const OUString& _rBaseName,
 506                                      bool _bStartWithNumber = true);
 507
 508     /** creates a unique name which is not already used in the given name array
 509     */
 510     OOO_DLLPUBLIC_DBTOOLS OUString createUniqueName(
 511         const css::uno::Sequence< OUString >& _rNames,
 512         const OUString& _rBaseName,
 513         bool _bStartWithNumber
 514     );
 515
 516     /** create a name which is a valid SQL 92 identifier name
 517         @param      _rName          the string which should be converted
 518         @param      _rSpecials      @see com.sun.star.sdbc.XDatabaseMetaData.getExtraNameCharacters
 519
 520         @see isValidSQLName
 521     */
 522     OOO_DLLPUBLIC_DBTOOLS OUString convertName2SQLName(const OUString& _rName, std::u16string_view _rSpecials);
 523
 524     /** checks whether the given name is a valid SQL name
 525
 526         @param      _rName          the string which should be converted
 527         @param      _rSpecials      @see com.sun.star.sdbc.XDatabaseMetaData.getExtraNameCharacters
 528
 529         @see convertName2SQLName
 530     */
 531     OOO_DLLPUBLIC_DBTOOLS bool isValidSQLName( const OUString& _rName, std::u16string_view _rSpecials );
 532
 533     OOO_DLLPUBLIC_DBTOOLS
 534     void showError( const SQLExceptionInfo& _rInfo,
 535                     const css::uno::Reference< css::awt::XWindow>& _pParent,
 536                     const css::uno::Reference< css::uno::XComponentContext>& _rxContext);
 537
 538     /** implements <method scope="com.sun.star.sdb">XRowUpdate::updateObject</method>
 539         <p>The object which is to be set is analyzed, and in case it is a simlpe scalar type for which there
 540         is another updateXXX method, this other method is used.</p>
 541         @param _rxUpdatedObject
 542             the interface to forward all updateXXX calls to (except updateObject)
 543         @param _nColumnIndex
 544             the column index to update
 545         @param _rValue
 546             the value to update
 547         @return
 548             <TRUE/> if the update request was successfully re-routed to one of the other updateXXX methods
 549     */
 550     OOO_DLLPUBLIC_DBTOOLS
 551     bool implUpdateObject(  const css::uno::Reference< css::sdbc::XRowUpdate >& _rxUpdatedObject,
 552                                 const sal_Int32 _nColumnIndex,
 553                                 const css::uno::Any& _rValue);
 554
 555
 556     /** ask the user for parameters if the prepared statement needs some and sets them in the prepared statement
 557         @param _xConnection     the connection must be able to create css::sdb::SingleSelectQueryComposers
 558         @param _xPreparedStmt   the prepared statement where the parameters could be set when needed
 559         @param _aParametersSet  contains which parameters have to asked for and which already have set.
 560     */
 561     OOO_DLLPUBLIC_DBTOOLS
 562     void askForParameters(  const css::uno::Reference< css::sdb::XSingleSelectQueryComposer >& _xComposer,
 563                             const css::uno::Reference< css::sdbc::XParameters>& _xParameters,
 564                             const css::uno::Reference< css::sdbc::XConnection>& _xConnection,
 565                             const css::uno::Reference< css::task::XInteractionHandler >& _rxHandler,
 566                             const ::std::vector<bool, std::allocator<bool> >& _aParametersSet = ::std::vector<bool, std::allocator<bool> >());
 567
 568     /** call the appropriate set method for the specific sql type @see css::sdbc::DataType
 569         @param  _xParams        the parameters where to set the value
 570         @param  parameterIndex  the index of the parameter, 1 based
 571         @param  x               the value to set
 572         @param  sqlType         the corresponding sql type @see css::sdbc::DataType
 573         @param  scale           the scale of the sql type can be 0
 574         @throws css::sdbc::SQLException
 575         @throws css::uno::RuntimeException
 576     */
 577     OOO_DLLPUBLIC_DBTOOLS
 578     void setObjectWithInfo( const css::uno::Reference< css::sdbc::XParameters>& _xParameters,
 579                             sal_Int32 parameterIndex,
 580                             const css::uno::Any& x,
 581                             sal_Int32 sqlType,
 582                             sal_Int32 scale=0);
 583
 584     /** call the appropriate set method for the specific sql type @see css::sdbc::DataType
 585         @param  _xParams        the parameters where to set the value
 586         @param  parameterIndex  the index of the parameter, 1 based
 587         @param  x               the value to set
 588         @param  sqlType         the corresponding sql type @see css::sdbc::DataType
 589         @param  scale           the scale of the sql type can be 0
 590         @throws css::sdbc::SQLException
 591         @throws css::uno::RuntimeException
 592     */
 593     OOO_DLLPUBLIC_DBTOOLS
 594     void setObjectWithInfo( const css::uno::Reference< css::sdbc::XParameters>& _xParameters,
 595                             sal_Int32 parameterIndex,
 596                             const ::connectivity::ORowSetValue& x,
 597                             sal_Int32 sqlType,
 598                             sal_Int32 scale);
 599
 600
 601     /** implements <method scope="com.sun.star.sdb">XParameters::setObject</method>
 602         <p>The object which is to be set is analyzed, and in case it is a simlpe scalar type for which there
 603         is another setXXX method, this other method is used.</p>
 604         @param _rxParameters
 605             the interface to forward all setXXX calls to (except setObject)
 606         @param _nColumnIndex
 607             the column index to update
 608         @param _rValue
 609             the value to update
 610         @return
 611             <TRUE/> if the update request was successfully re-routed to one of the other updateXXX methods
 612     */
 613     OOO_DLLPUBLIC_DBTOOLS
 614     bool implSetObject( const css::uno::Reference< css::sdbc::XParameters>& _rxParameters,
 615                             const sal_Int32 _nColumnIndex,
 616                             const css::uno::Any& _rValue);
 617
 618     /** creates the standard sql create table statement without the key part.
 619         @param  descriptor
 620             The descriptor of the new table.
 621         @param  _xConnection
 622             The connection.
 623         @param  _bAddScale
 624             The scale will also be added when the value is 0.
 625     */
 626     OOO_DLLPUBLIC_DBTOOLS
 627     OUString createStandardCreateStatement(  const css::uno::Reference< css::beans::XPropertySet >& descriptor,
 628                                                     const css::uno::Reference< css::sdbc::XConnection>& _xConnection,
 629                                                     ISQLStatementHelper* _pHelper,
 630                                                     std::u16string_view _sCreatePattern);
 631
 632     /** creates the standard sql statement for the key part of a create table statement.
 633         @param  descriptor
 634             The descriptor of the new table.
 635         @param  _xConnection
 636             The connection.
 637     */
 638     OOO_DLLPUBLIC_DBTOOLS
 639     OUString createStandardKeyStatement( const css::uno::Reference< css::beans::XPropertySet >& descriptor,
 640                                                 const css::uno::Reference< css::sdbc::XConnection>& _xConnection);
 641
 642     /** creates the standard sql statement for the type part of a create or alter table statement.
 643         @param  _pHelper
 644             Allow to add special SQL constructs.
 645         @param  descriptor
 646             The descriptor of the column.
 647         @param  _xConnection
 648             The connection.
 649     */
 650     OOO_DLLPUBLIC_DBTOOLS
 651     OUString createStandardTypePart(     const css::uno::Reference< css::beans::XPropertySet >& descriptor
 652                                                 ,const css::uno::Reference< css::sdbc::XConnection>& _xConnection
 653                                                 ,std::u16string_view _sCreatePattern = {});
 654
 655     /** creates the standard sql statement for the column part of a create table statement.
 656         @param  _pHelper
 657             Allow to add special SQL constructs.
 658         @param  descriptor
 659             The descriptor of the column.
 660         @param  _xConnection
 661             The connection.
 662         @param  _pHelper
 663             Allow to add special SQL constructs.
 664     */
 665     OOO_DLLPUBLIC_DBTOOLS
 666     OUString createStandardColumnPart(   const css::uno::Reference< css::beans::XPropertySet >& descriptor
 667                                                 ,const css::uno::Reference< css::sdbc::XConnection>& _xConnection
 668                                                 ,ISQLStatementHelper* _pHelper = nullptr
 669                                                 ,std::u16string_view _sCreatePattern = {});
 670
 671     /** creates a SQL CREATE TABLE statement
 672
 673         @param  descriptor
 674             The descriptor of the new table.
 675         @param  _xConnection
 676             The connection.
 677
 678         @return
 679             The CREATE TABLE statement.
 680     */
 681     OOO_DLLPUBLIC_DBTOOLS
 682     OUString createSqlCreateTableStatement(  const css::uno::Reference< css::beans::XPropertySet >& descriptor
 683                                                     ,const css::uno::Reference< css::sdbc::XConnection>& _xConnection);
 684
 685     /** creates a SDBC column with the help of getColumns.
 686         @param  _xTable
 687             The table.
 688         @param  _rName
 689             The name of the column.
 690         @param  _bCase
 691             Is the column case sensitive.
 692         @param  _bQueryForInfo
 693             If <TRUE/> the autoincrement and currency field will be read from the meta data, otherwise the following parameters will be used instead
 694         @param  _bIsAutoIncrement
 695             <TRUE/> if the column is an autoincrement.
 696         @param  _bIsCurrency
 697             <TRUE/> if the column is a currency field.
 698         @param  _nDataType
 699             The data type of the column.
 700     */
 701     OOO_DLLPUBLIC_DBTOOLS
 702     css::uno::Reference< css::beans::XPropertySet>
 703             createSDBCXColumn(  const css::uno::Reference< css::beans::XPropertySet>& _xTable,
 704                                 const css::uno::Reference< css::sdbc::XConnection>& _xConnection,
 705                                 const OUString& _rName,
 706                                 bool _bCase,
 707                                 bool _bQueryForInfo,
 708                                 bool _bIsAutoIncrement,
 709                                 bool _bIsCurrency,
 710                                 sal_Int32 _nDataType);
 711
 712     /** tries to locate the corresponding DataDefinitionSupplier for the given url and connection
 713         @param  _rsUrl
 714             The URL used to connect to the database.
 715         @param  _xConnection
 716             The connection used to find the correct driver.
 717         @param  _rxContext
 718             Used to create the drivermanager.
 719         @return
 720             The datadefinition object.
 721     */
 722     OOO_DLLPUBLIC_DBTOOLS css::uno::Reference< css::sdbcx::XTablesSupplier> getDataDefinitionByURLAndConnection(
 723             const OUString& _rsUrl,
 724             const css::uno::Reference< css::sdbc::XConnection>& _xConnection,
 725             const css::uno::Reference< css::uno::XComponentContext>& _rxContext);
 726
 727     /** returns the table privileges to the given parameters
 728         @param  _xMetaData
 729             The meta data.
 730         @param  _sCatalog
 731             contains the catalog name
 732         @param  _sSchema
 733             contains the schema name
 734         @param  _sTable
 735             contains the table name
 736     */
 737     OOO_DLLPUBLIC_DBTOOLS
 738     sal_Int32 getTablePrivileges(const css::uno::Reference< css::sdbc::XDatabaseMetaData>& _xMetaData,
 739                                  const OUString& _sCatalog,
 740                                  const OUString& _sSchema,
 741                                  const OUString& _sTable);
 742
 743     typedef ::std::pair<bool,bool> TBoolPair;
 744     typedef ::std::pair< TBoolPair,sal_Int32 > ColumnInformation;
 745     typedef ::std::multimap< OUString, ColumnInformation, ::comphelper::UStringMixLess> ColumnInformationMap;
 746     /** collects the information about auto increment, currency and data type for the given column name.
 747         The column must be quoted, * is also valid.
 748         @param  _xConnection
 749             The connection.
 750         @param  _sComposedTableName
 751             The quoted table name. ccc.sss.ttt
 752         @param  _sName
 753             The name of the column, or *
 754         @param  _rInfo
 755             The information about the column(s).
 756     */
 757     OOO_DLLPUBLIC_DBTOOLS
 758     void collectColumnInformation(  const css::uno::Reference< css::sdbc::XConnection>& _xConnection,
 759                                     std::u16string_view _sComposedTableName,
 760                                     std::u16string_view _rName,
 761                                     ColumnInformationMap& _rInfo);
 762
 763
 764     /** adds a boolean comparison clause to the given SQL predicate
 765
 766         @param _rExpression
 767             the expression which is to be compared with a boolean value
 768         @param _bValue
 769             the boolean value which the expression is to be compared with
 770         @param _nBooleanComparisonMode
 771             the boolean comparison mode to be used. Usually obtained from
 772             a css.sdb.DataSource's Settings member.
 773         @param _out_rSQLPredicate
 774             the buffer to which the comparison predicate will be appended
 775     */
 776     OOO_DLLPUBLIC_DBTOOLS void getBooleanComparisonPredicate(
 777             std::u16string_view _rExpression,
 778             const bool  _bValue,
 779             const sal_Int32 _nBooleanComparisonMode,
 780             OUStringBuffer& _out_rSQLPredicate
 781         );
 782
 783     /** is this field an aggregate?
 784
 785         @param _xComposer
 786             a query composer that knows the field by name
 787         @param _xField
 788             the field
 789     */
 790     OOO_DLLPUBLIC_DBTOOLS bool isAggregateColumn(
 791             const css::uno::Reference< css::sdb::XSingleSelectQueryComposer > &_xComposer,
 792             const css::uno::Reference< css::beans::XPropertySet > &_xField
 793         );
 794
 795     /** is this column an aggregate?
 796
 797         @param _xColumns collection of columns
 798             look for column sName in there
 799         @param _sName
 800             name of the column
 801     */
 802     OOO_DLLPUBLIC_DBTOOLS bool isAggregateColumn(
 803             const css::uno::Reference< css::container::XNameAccess > &_xColumns,
 804             const OUString &_sName
 805         );
 806
 807     /** is this column an aggregate?
 808
 809         @param _xColumn
 810     */
 811     OOO_DLLPUBLIC_DBTOOLS bool isAggregateColumn(
 812             const css::uno::Reference< css::beans::XPropertySet > &_xColumn
 813         );
 814
 815 }   // namespace dbtools
 816
 817 namespace connectivity
 818 {
 819 namespace dbase
 820 {
 821     enum DBFType  { dBaseIII         = 0x03,
 822                     dBaseIV          = 0x04,
 823                     dBaseV           = 0x05,
 824                     VisualFoxPro     = 0x30,
 825                     VisualFoxProAuto = 0x31, // Visual FoxPro with AutoIncrement field
 826                     dBaseFS          = 0x43,
 827                     dBaseFSMemo      = 0xB3,
 828                     dBaseIIIMemo     = 0x83,
 829                     dBaseIVMemo      = 0x8B,
 830                     dBaseIVMemoSQL   = 0x8E,
 831                     FoxProMemo       = 0xF5
 832     };
 833
 834     /** decode a DBase file's codepage byte to a RTL charset
 835         @param  _out_nCharset
 836             in case of success, the decoded RTL charset is written there.
 837             else, this is not written to.
 838         @param  nType
 839             the file's type byte
 840         @param  nCodepage
 841             the file's codepage byte
 842         @return
 843             true if a RTL charset was successfully decoded and written to _out_nCharset
 844             false if nothing was written to _out_nCharset
 845     */
 846     OOO_DLLPUBLIC_DBTOOLS bool dbfDecodeCharset(rtl_TextEncoding &_out_nCharset, sal_uInt8 nType, sal_uInt8 nCodepage);
 847
 848     /** decode a DBase file's codepage byte to a RTL charset
 849         @param  _out_nCharset
 850             in case of success, the decoded RTL charset is written there.
 851             else, this is not written to.
 852         @param  dbf_Stream
 853             pointer to a SvStream encapsulating the DBase file.
 854             The stream will be rewinded and read from.
 855             No guarantee is made on its position afterwards. Caller must reposition it itself.
 856         @return
 857             true if a RTL charset was successfully decoded and written to _out_nCharset
 858             false if nothing was written to _out_nCharset
 859     */
 860     OOO_DLLPUBLIC_DBTOOLS bool dbfReadCharset(rtl_TextEncoding &nCharSet, SvStream* dbf_Stream);
 861
 862 } // namespace connectivity::dbase
 863 } // namespace connectivity
 864
 865 #endif // INCLUDED_CONNECTIVITY_DBTOOLS_HXX
 866
 867 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */