Changeset View
Changeset View
Standalone View
Standalone View
src/KDb.h
1 | /* This file is part of the KDE project | 1 | /* This file is part of the KDE project | ||
---|---|---|---|---|---|
2 | Copyright (C) 2004-2017 Jarosław Staniek <staniek@kde.org> | 2 | Copyright (C) 2004-2018 Jarosław Staniek <staniek@kde.org> | ||
3 | 3 | | |||
4 | This library is free software; you can redistribute it and/or | 4 | This library is free software; you can redistribute it and/or | ||
5 | modify it under the terms of the GNU Library General Public | 5 | modify it under the terms of the GNU Library General Public | ||
6 | License as published by the Free Software Foundation; either | 6 | License as published by the Free Software Foundation; either | ||
7 | version 2 of the License, or (at your option) any later version. | 7 | version 2 of the License, or (at your option) any later version. | ||
8 | 8 | | |||
9 | This library is distributed in the hope that it will be useful, | 9 | This library is distributed in the hope that it will be useful, | ||
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of | 10 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
▲ Show 20 Lines • Show All 403 Lines • ▼ Show 20 Line(s) | |||||
414 | //! @return a value that can be set for a database field of type @a type having "notEmpty" property set. | 414 | //! @return a value that can be set for a database field of type @a type having "notEmpty" property set. | ||
415 | /*! It works in a similar way as @ref QVariant KDb::emptyValueForFieldType(KDbField::Type type) | 415 | /*! It works in a similar way as @ref QVariant KDb::emptyValueForFieldType(KDbField::Type type) | ||
416 | with the following differences: | 416 | with the following differences: | ||
417 | - " " string (a single space) is returned for Text and LongText types | 417 | - " " string (a single space) is returned for Text and LongText types | ||
418 | - a byte array with saved "filenew" PNG image (icon) for BLOB type | 418 | - a byte array with saved "filenew" PNG image (icon) for BLOB type | ||
419 | Returns null QVariant for unsupported values like KDbField::InvalidType. */ | 419 | Returns null QVariant for unsupported values like KDbField::InvalidType. */ | ||
420 | KDB_EXPORT QVariant notEmptyValueForFieldType(KDbField::Type type); | 420 | KDB_EXPORT QVariant notEmptyValueForFieldType(KDbField::Type type); | ||
421 | 421 | | |||
422 | /*! @return true if the @a word is an reserved KDbSQL keyword | 422 | /*! @return true if the @a word is an reserved KDBSQL keyword | ||
423 | See generated/sqlkeywords.cpp. | 423 | See generated/sqlkeywords.cpp. | ||
424 | @todo add function returning list of keywords. */ | 424 | @todo add function returning list of keywords. */ | ||
425 | KDB_EXPORT bool isKDbSqlKeyword(const QByteArray& word); | 425 | KDB_EXPORT bool isKDbSqlKeyword(const QByteArray& word); | ||
426 | 426 | | |||
427 | //! @return @a string string with applied KDbSQL identifier escaping | 427 | //! @return @a string string with applied KDBSQL identifier escaping | ||
428 | /*! This escaping can be used for field, table, database names, etc. | 428 | /*! This escaping can be used for field, table, database names, etc. | ||
429 | Use it for user-visible backend-independent statements. | 429 | Use it for user-visible backend-independent statements. | ||
430 | @see KDb::escapeIdentifierAndAddQuotes() */ | 430 | @see KDb::escapeIdentifierAndAddQuotes() */ | ||
431 | KDB_EXPORT QString escapeIdentifier(const QString& string); | 431 | KDB_EXPORT QString escapeIdentifier(const QString& string); | ||
432 | 432 | | |||
433 | //! @overload QString escapeIdentifier(const QString&) | 433 | //! @overload QString escapeIdentifier(const QString&) | ||
434 | KDB_EXPORT QByteArray escapeIdentifier(const QByteArray& string); | 434 | KDB_EXPORT QByteArray escapeIdentifier(const QByteArray& string); | ||
435 | 435 | | |||
436 | //! @return @a string string with applied KDbSQL identifier escaping and enclosed in " quotes | 436 | //! @return @a string string with applied KDBSQL identifier escaping and enclosed in " quotes | ||
437 | /*! This escaping can be used for field, table, database names, etc. | 437 | /*! This escaping can be used for field, table, database names, etc. | ||
438 | Use it for user-visible backend-independent statements. | 438 | Use it for user-visible backend-independent statements. | ||
439 | @see KDb::escapeIdentifier */ | 439 | @see KDb::escapeIdentifier */ | ||
440 | KDB_EXPORT QString escapeIdentifierAndAddQuotes(const QString& string); | 440 | KDB_EXPORT QString escapeIdentifierAndAddQuotes(const QString& string); | ||
441 | 441 | | |||
442 | //! @overload QString escapeIdentifierAndAddQuotes(const QString&) | 442 | //! @overload QString escapeIdentifierAndAddQuotes(const QString&) | ||
443 | KDB_EXPORT QByteArray escapeIdentifierAndAddQuotes(const QByteArray& string); | 443 | KDB_EXPORT QByteArray escapeIdentifierAndAddQuotes(const QByteArray& string); | ||
444 | 444 | | |||
445 | /*! @return escaped string @a string for the KDbSQL dialect, | 445 | /*! @return escaped string @a string for the KDBSQL dialect, | ||
446 | i.e. doubles single quotes ("'") and inserts the string into single quotes. | 446 | i.e. doubles single quotes ("'") and inserts the string into single quotes. | ||
447 | Quotes "'" are prepended and appended. | 447 | Quotes "'" are prepended and appended. | ||
448 | Also escapes \\n, \\r, \\t, \\\\, \\0. | 448 | Also escapes \\n, \\r, \\t, \\\\, \\0. | ||
449 | Use it for user-visible backend-independent statements. | 449 | Use it for user-visible backend-independent statements. | ||
450 | @see unescapeString() */ | 450 | @see unescapeString() */ | ||
451 | KDB_EXPORT QString escapeString(const QString& string); | 451 | KDB_EXPORT QString escapeString(const QString& string); | ||
452 | 452 | | |||
453 | /** | 453 | /** | ||
454 | * @brief Returns escaped string @a string | 454 | * @brief Returns escaped string @a string | ||
455 | * | 455 | * | ||
456 | * If @a drv driver is present, it is used to perform escaping, otherwise escapeString() is used | 456 | * If @a drv driver is present, it is used to perform escaping, otherwise escapeString() is used | ||
457 | * so the KDbSQL dialect-escaping is performed. | 457 | * so the KDBSQL dialect-escaping is performed. | ||
458 | * | 458 | * | ||
459 | * @since 3.1.0 | 459 | * @since 3.1.0 | ||
460 | */ | 460 | */ | ||
461 | KDB_EXPORT KDbEscapedString escapeString(KDbDriver *drv, const QString& string); | 461 | KDB_EXPORT KDbEscapedString escapeString(KDbDriver *drv, const QString& string); | ||
462 | 462 | | |||
463 | /** | 463 | /** | ||
464 | * @brief Returns escaped string @a string | 464 | * @brief Returns escaped string @a string | ||
465 | * | 465 | * | ||
466 | * If @a conn is present, its driver is used to perform escaping, otherwise escapeString() is used | 466 | * If @a conn is present, its driver is used to perform escaping, otherwise escapeString() is used | ||
467 | * so the KDbSQL dialect-escaping is performed. | 467 | * so the KDBSQL dialect-escaping is performed. | ||
468 | * | 468 | * | ||
469 | * @since 3.1.0 | 469 | * @since 3.1.0 | ||
470 | */ | 470 | */ | ||
471 | KDB_EXPORT KDbEscapedString escapeString(KDbConnection *conn, const QString& string); | 471 | KDB_EXPORT KDbEscapedString escapeString(KDbConnection *conn, const QString& string); | ||
472 | 472 | | |||
473 | //! Unescapes characters in string @a string for the KDbSQL dialect. | 473 | //! Unescapes characters in string @a string for the KDBSQL dialect. | ||
474 | /** The operation depends on @a quote character, which can be be ' or ". | 474 | /** The operation depends on @a quote character, which can be be ' or ". | ||
475 | * @a string is assumed to be properly constructed. This is assured by the lexer's grammar. | 475 | * @a string is assumed to be properly constructed. This is assured by the lexer's grammar. | ||
476 | * Used by lexer to recognize the CHARACTER_STRING_LITERAL token. | 476 | * Used by lexer to recognize the CHARACTER_STRING_LITERAL token. | ||
477 | * @return unescaped string and sets value pointed by @a errorPosition (if any) to -1 on success; | 477 | * @return unescaped string and sets value pointed by @a errorPosition (if any) to -1 on success; | ||
478 | * and to index of problematic character on failure. | 478 | * and to index of problematic character on failure. | ||
479 | * The function fails when unsupported @a quote character is passed or for unsupported sequences. | 479 | * The function fails when unsupported @a quote character is passed or for unsupported sequences. | ||
480 | * | 480 | * | ||
481 | * Example sequences for ' character quote: | 481 | * Example sequences for ' character quote: | ||
▲ Show 20 Lines • Show All 170 Lines • ▼ Show 20 Line(s) | |||||
652 | /*! @return default file-based driver MIME type | 652 | /*! @return default file-based driver MIME type | ||
653 | (typically something like "application/x-kexiproject-sqlite") */ | 653 | (typically something like "application/x-kexiproject-sqlite") */ | ||
654 | KDB_EXPORT QString defaultFileBasedDriverMimeType(); | 654 | KDB_EXPORT QString defaultFileBasedDriverMimeType(); | ||
655 | 655 | | |||
656 | /*! @return default file-based driver ID (currently, "org.kde.kdb.sqlite"). */ | 656 | /*! @return default file-based driver ID (currently, "org.kde.kdb.sqlite"). */ | ||
657 | KDB_EXPORT QString defaultFileBasedDriverId(); | 657 | KDB_EXPORT QString defaultFileBasedDriverId(); | ||
658 | 658 | | |||
659 | /*! Escapes and converts value @a v (for type @a ftype) | 659 | /*! Escapes and converts value @a v (for type @a ftype) | ||
660 | to string representation required by KDbSQL commands. | 660 | to string representation required by KDBSQL commands. | ||
661 | For Date/Time type KDb::dateTimeToSql() is used. | 661 | For Date/Time type KDb::dateTimeToSql() is used. | ||
662 | For BLOB type KDb::escapeBlob() with BLOBEscapingType::ZeroXHex conversion type is used. */ | 662 | For BLOB type KDb::escapeBlob() with BLOBEscapingType::ZeroXHex conversion type is used. */ | ||
663 | KDB_EXPORT KDbEscapedString valueToSql(KDbField::Type ftype, const QVariant& v); | 663 | KDB_EXPORT KDbEscapedString valueToSql(KDbField::Type ftype, const QVariant& v); | ||
664 | 664 | | |||
665 | /*! Converts value @a v to string representation required by KDbSQL commands: | 665 | /** | ||
666 | ISO 8601 DateTime format - with "T" delimiter/ | 666 | * Converts date/time value to its string representation in ISO 8601 DateTime format - with "T" delimiter | ||
667 | For specification see https://www.w3.org/TR/NOTE-datetime. | 667 | * | ||
668 | Example: "1994-11-05T13:15:30" not "1994-11-05 13:15:30". | 668 | * @note This method is deprecated since 3.1.1, use KDb::dateTimeToIsoString() which has identical | ||
669 | @todo Add support for time zones */ | 669 | * effect. The ISO format is no longer used for creating KDBSQL statements. | ||
670 | KDB_EXPORT KDbEscapedString dateTimeToSql(const QDateTime& v); | 670 | * Prior to this version it was used to generate date/time constants in | ||
671 | * KDb::valueToSql(KDbField::Type ftype, const QVariant& v) for KDbField::DateTime type. | ||||
672 | * KDb::dateTimeToIsoString() is still used as default implementation for drivers | ||||
673 | * in KDbDriver::dateTimeToSql(). | ||||
674 | * | ||||
675 | * KDb 3.1.0 improved type safety for KDBSQL so Text type are no longer compatible with | ||||
676 | * Date/Time types. By implementing wish https://bugs.kde.org/393094 format of date/time constants | ||||
677 | * for KDBSQL has been strictly defined in a backend-independent way. | ||||
678 | * See https://community.kde.org/Kexi/Plugins/Queries/SQL_Constants for details. | ||||
679 | */ | ||||
680 | KDB_DEPRECATED_EXPORT KDbEscapedString dateTimeToSql(const QDateTime& v); | ||||
681 | | ||||
682 | /** | ||||
683 | * Converts date value to its string representation in ISO 8601 DateTime format | ||||
684 | * | ||||
685 | * The string is enclosed with single quotes "'". It is compatible with SQLite format for the | ||||
686 | * date type. It is used as default implementation for drivers in KDbDriver::dateToSql(). | ||||
687 | * | ||||
688 | * If the @a v value is convertible to KDbDate then KDbDate::toString() is used to obtain | ||||
689 | * the result. Otherwise the value is converted to QDate and QDate::toString(Qt::ISODate) is | ||||
690 | * used to obtain the result. | ||||
691 | * | ||||
692 | * "<INVALID_DATE>" string is returned for invalid (also null) date values. | ||||
693 | * | ||||
694 | * For specification of the ISO format see https://www.w3.org/TR/NOTE-datetime. | ||||
695 | * | ||||
696 | * Example value: "'1994-11-05'". | ||||
697 | * | ||||
698 | * @since 3.1.1 | ||||
699 | */ | ||||
700 | KDB_EXPORT KDbEscapedString dateToIsoString(const QVariant& v); | ||||
701 | | ||||
702 | /** | ||||
703 | * Converts time value to its string representation in ISO 8601 Time format | ||||
704 | * | ||||
705 | * The string is enclosed with single quotes "'". It is compatible with SQLite format for the | ||||
706 | * time type. It is used as default implementation for drivers in KDbDriver::timeToSql(). | ||||
707 | * | ||||
708 | * If the @a v value is convertible to KDbTime then KDbTime::toString() is used to obtain the result. | ||||
709 | * Otherwise the value is converted to QTime and QTime::toString(Qt::ISODateWithMs) | ||||
710 | * or QTime::toString(Qt::ISODate) is used to obtain the result. | ||||
711 | * If the time's milliseconds value is zero, it is not included. | ||||
712 | * | ||||
713 | * "<INVALID_TIME>" string is returned for invalid (also null) time values. | ||||
714 | * | ||||
715 | * For specification of the ISO format see https://www.w3.org/TR/NOTE-datetime. | ||||
716 | * | ||||
717 | * Example values: "'13:15:30.123'", "'13:15:30'". | ||||
718 | * | ||||
719 | * @since 3.1.1 | ||||
720 | */ | ||||
721 | KDB_EXPORT KDbEscapedString timeToIsoString(const QVariant& v); | ||||
722 | | ||||
723 | /** | ||||
724 | * Converts date/time value to its string representation in ISO 8601 DateTime format - with "T" delimiter | ||||
725 | * | ||||
726 | * The string is enclosed with single quotes "'". It is compatible with SQLite format for the | ||||
727 | * date/time type. It is used as default implementation for drivers in KDbDriver::dateTimeToSql(). | ||||
728 | * | ||||
729 | * If the @a v value is convertible to KDbDateTime then KDbDateTime::toString() is used to obtain | ||||
730 | * the result. Otherwise the value is converted to QDateTime and QDate::toString(Qt::ISODate) is | ||||
731 | * used as well as QTime::toString(Qt::ISODateWithMs) or QTime::toString(Qt::ISODate) to obtain | ||||
732 | * the result. If the time's milliseconds value is zero, it is not included. | ||||
733 | * | ||||
734 | * "<INVALID_DATETIME>" string is returned for invalid (also null) time values. | ||||
735 | * | ||||
736 | * For specification of the ISO format see https://www.w3.org/TR/NOTE-datetime. | ||||
737 | * | ||||
738 | * Example value: "'1994-11-05T13:15:30'", not "'1994-11-05 13:15:30'". | ||||
739 | * | ||||
740 | * @since 3.1.1 | ||||
741 | */ | ||||
742 | KDB_EXPORT KDbEscapedString dateTimeToIsoString(const QVariant& v); | ||||
743 | | ||||
744 | /** | ||||
745 | * Converts date value to its string representation required by KDBSQL commands | ||||
746 | * | ||||
747 | * The value can be of type QDate or KDbDate. If the value is not one of these types or is invalid | ||||
748 | * QDate or is a null KDbDate then "<INVALID_DATE>" is returned. If the value is of type KDbDate | ||||
749 | * that is not null then even if some components of the date are invalid, properly formatted string | ||||
750 | * is returned. | ||||
751 | * | ||||
752 | * Example values: "#1994-11-05", "#1994-9-05#". | ||||
753 | * | ||||
754 | * See https://community.kde.org/Kexi/Plugins/Queries/SQL_Constants for details. | ||||
755 | * | ||||
756 | * @since 3.1.1 | ||||
757 | */ | ||||
758 | KDB_EXPORT KDbEscapedString dateToSql(const QVariant& v); | ||||
759 | | ||||
760 | /** | ||||
761 | * Converts time value to its string representation required by KDBSQL commands | ||||
762 | * | ||||
763 | * The value can be of type QTime or KDbTime. If the value is not one of these types or is invalid | ||||
764 | * QTime or is a null KDbTime then "<INVALID_TIME>" is returned. If the value is of type KDbTime | ||||
765 | * that is not null then even if some components of the time are invalid, properly formatted string | ||||
766 | * is returned. If the time's milliseconds value is zero, it is not included. | ||||
767 | * | ||||
768 | * See https://community.kde.org/Kexi/Plugins/Queries/SQL_Constants for details. | ||||
769 | * | ||||
770 | * Example values: "#13:15#", "#13:9:30#", "#13:15:30.921#, "#7:20 AM#". | ||||
771 | * | ||||
772 | * @since 3.1.1 | ||||
773 | */ | ||||
774 | KDB_EXPORT KDbEscapedString timeToSql(const QVariant& v); | ||||
775 | | ||||
776 | /** | ||||
777 | * Converts date/time value to its string representation required by KDBSQL commands | ||||
778 | * | ||||
779 | * The value can be of type QDateTime or KDbDateTime. If the value is not one of these types or | ||||
780 | * is invalid QDateTime or is a null KDbDateTime then "<INVALID_DATETIME>" is returned. | ||||
781 | * If the value is of type KDbDateTime that is not null then even if some components of the | ||||
782 | * date/time are invalid, properly formatted string is returned. | ||||
783 | * If the time's milliseconds value is zero, it is not included. | ||||
784 | * | ||||
785 | * See https://community.kde.org/Kexi/Plugins/Queries/SQL_Constants for details. | ||||
786 | * | ||||
787 | * Example values: "#1994-11-05 13:15#", "#1994-11-05 13:9:30#", "#1994-9-05 13:15:30.921#". | ||||
788 | * | ||||
789 | * @since 3.1.1 | ||||
790 | */ | ||||
791 | KDB_EXPORT KDbEscapedString dateTimeToSql(const QVariant& v); | ||||
671 | 792 | | |||
672 | #ifdef KDB_DEBUG_GUI | 793 | #ifdef KDB_DEBUG_GUI | ||
673 | //! A prototype of handler for GUI debugger | 794 | //! A prototype of handler for GUI debugger | ||
674 | typedef void(*DebugGUIHandler)(const QString&); | 795 | typedef void(*DebugGUIHandler)(const QString&); | ||
675 | 796 | | |||
676 | //! Sets handler for GUI debugger | 797 | //! Sets handler for GUI debugger | ||
677 | KDB_EXPORT void setDebugGUIHandler(DebugGUIHandler handler); | 798 | KDB_EXPORT void setDebugGUIHandler(DebugGUIHandler handler); | ||
678 | 799 | | |||
▲ Show 20 Lines • Show All 99 Lines • Show Last 20 Lines |