database_backend.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef KICAD_DATABASE_BACKEND_H
#define KICAD_DATABASE_BACKEND_H
 
#include <functional>
#include <limits>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
#include <wx/string.h>
 
#include <database/database_value.h>
#include <trace_helpers.h>
 
struct DATABASE_SOURCE;
 

enum class DB_FAILURE
{
    UNKNOWN,
    LOGIN,                     
    UNREACHABLE,               
    TIMEOUT,                   
    NO_DSN,                    
    NO_DRIVER,                 
    FILE_NOT_FOUND,            
    FILE_IN_USE,               
    PROVIDER_MISSING,          
    NOT_SUPPORTED_ON_PLATFORM, 
    INVALID_TYPE,              
    NETWORK_WAL                
};
 

struct DB_COLUMN
{
    std::string name;
    int         type;
    bool        supported = true; 
};
 
 
struct DB_TABLE_INFO
{
    std::string             name; 
    std::vector<DB_COLUMN>  columns;

    bool columnsUnavailable = false;
};
 

using DB_ROW_SINK = std::function<void( std::vector<DB_VALUE>&& )>;

using DB_RESTART_SINK = std::function<void()>;

using DB_STOP_CHECK = std::function<bool()>;
 
 
class DATABASE_BACKEND;
 

struct DB_BACKEND_RESULT
{
    std::unique_ptr<DATABASE_BACKEND> backend;
    DB_FAILURE                        failure = DB_FAILURE::UNKNOWN;
    std::string                       error;
};
 

class DATABASE_BACKEND
{
public:
    static constexpr size_t ALL_ROWS = std::numeric_limits<size_t>::max();
 
    virtual ~DATABASE_BACKEND() = default;
 
    virtual bool Connect() = 0;
 
    virtual void Disconnect() = 0;
 
    virtual bool IsConnected() const = 0;

    virtual bool ListTables( std::vector<std::string>& aTables ) = 0;

    virtual std::optional<DB_TABLE_INFO> DescribeTable( const std::string& aTable ) = 0;

    virtual bool ListColumns( const std::string& aTable, std::vector<std::string>& aColumns );

    virtual bool ReadTable( const DB_TABLE_INFO& aTable, const std::vector<std::string>& aColumns, size_t aMaxRows,
                            std::vector<std::string>& aLabels, const DB_ROW_SINK& aSink ) = 0;

    virtual bool ReadAllRows( const DB_TABLE_INFO& aTable, const std::vector<std::string>& aColumns,
                              std::vector<std::string>& aLabels, const DB_ROW_SINK& aSink,
                              const DB_RESTART_SINK& aRestart )
    {
        return ReadTable( aTable, aColumns, ALL_ROWS, aLabels, aSink );
    }

    virtual void BeginLoadCycle( const DB_STOP_CHECK& aStopped ) {}
 
    virtual void EndLoadCycle() {}

    virtual std::optional<bool> ReadRow( const DB_TABLE_INFO& aTable, const std::vector<std::string>& aColumns,
                                         const std::string& aKeyColumn, const std::string& aKey,
                                         std::vector<std::string>& aLabels, std::vector<DB_VALUE>& aRow )
    {
        return std::nullopt;
    }
 
    virtual std::string GetLastError() const = 0;
 
    virtual DB_FAILURE GetLastFailure() const = 0;

    static DB_BACKEND_RESULT Create( const DATABASE_SOURCE& aSource, const wxString& aBasePath );
};
 
#endif // KICAD_DATABASE_BACKEND_H