LCOV - code coverage report
Current view: top level - src - codec.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 2 2 100.0 %
Date: 2018-02-05 16:49:44 Functions: 2 3 66.7 %

          Line data    Source code
       1             : /*
       2             :  * Copyright (C) 2016-2017  Fulvio Benini
       3             : 
       4             :  * This file is part of Scid (Shane's Chess Information Database).
       5             :  *
       6             :  * Scid is free software: you can redistribute it and/or modify
       7             :  * it under the terms of the GNU General Public License as published by
       8             :  * the Free Software Foundation.
       9             :  *
      10             :  * Scid is distributed in the hope that it will be useful,
      11             :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      12             :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      13             :  * GNU General Public License for more details.
      14             :  *
      15             :  * You should have received a copy of the GNU General Public License
      16             :  * along with Scid.  If not, see <http://www.gnu.org/licenses/>.
      17             :  *
      18             :  */
      19             : 
      20             : /** @file
      21             :  * Defines the ICodecDatabase interface, which encapsulates the data
      22             :  * representation of databases.
      23             :  */
      24             : 
      25             : #ifndef CODEC_H
      26             : #define CODEC_H
      27             : 
      28             : #include "common.h"
      29             : #include <string>
      30             : #include <vector>
      31             : 
      32             : class Game;
      33             : class Index;
      34             : class IndexEntry;
      35             : class NameBase;
      36             : class Progress;
      37             : 
      38             : /**
      39             :  * This interface separates the logic of a database from its representation.
      40             :  * Ideally all the file I/O should be encapsulated in classes derived from this
      41             :  * interface.
      42             :  */
      43          50 : class ICodecDatabase {
      44             : public:
      45          50 :         virtual ~ICodecDatabase(){};
      46             : 
      47             :         enum Codec { MEMORY, SCID4, PGN };
      48             :         /**
      49             :          * Creates a new object and calls the virtual function dyn_open().
      50             :          * @param codec:    the type of the object to be created.
      51             :          * @param err[out]: OK on success, an error code on failure.
      52             :          * @param fMode:    a valid file mode.
      53             :          * @param filename: the full path of the database to be opened.
      54             :          * @param progress: a Progress object used for GUI communications.
      55             :          * @param idx:      valid pointer to the Index object for this database.
      56             :          * @param nb:       valid pointer to the NameBase object for this database.
      57             :          * @returns
      58             :          * - on success: a valid pointer to the new object and set @p err to OK.
      59             :          * - on error:   0 (nullptr) and sets @p err to the error code.
      60             :          */
      61             :         static ICodecDatabase* make(Codec codec, errorT* err, fileModeT fMode,
      62             :                                     const char* filename, const Progress& progress,
      63             :                                     Index* idx, NameBase* nb);
      64             : 
      65             :         /**
      66             :          * Returns the Codec type.
      67             :          */
      68             :         virtual Codec getType() = 0;
      69             : 
      70             :         /**
      71             :          * Returns the full path of the files used by the database.
      72             :          * The order of the filenames must be consistent for objects of the same
      73             :          * Codec type.
      74             :          */
      75             :         virtual std::vector<std::string> getFilenames() = 0;
      76             : 
      77             :         /**
      78             :          * Fetches the data of a game (excluding index info), encoded in native
      79             :          * format.
      80             :          * @param offset: offset of the requested game.
      81             :          * @param length: length of the game data (in bytes).
      82             :          * @returns
      83             :          * - a pointer to the game data.
      84             :          * - 0 (nullptr) on error.
      85             :          */
      86             :         virtual const byte* getGameData(uint64_t offset, uint32_t length) = 0;
      87             : 
      88             :         /**
      89             :          * Add a game to the database.
      90             :          * @param srcIe:   valid pointer to the header data.
      91             :          * @param srcNb:   valid pointer to the NameBase containing srcIe's names.
      92             :          * @param srcData: valid pointer to a buffer containing the game data
      93             :          *                 (encoded in native format).
      94             :          * @param dataLen: length of the game data (in bytes).
      95             :          * @returns OK if successful or an error code.
      96             :          */
      97             :         virtual errorT addGame(const IndexEntry* srcIe, const NameBase* srcNb,
      98             :                                const byte* srcData, size_t dataLen) = 0;
      99             : 
     100             :         /**
     101             :          * Add a game to the database.
     102             :          * @param game: valid pointer to a Game object with the data of the game.
     103             :          * @returns OK if successful or an error code.
     104             :          */
     105             :         virtual errorT addGame(Game* game) = 0;
     106             : 
     107             :         /**
     108             :          * Replaces a game in the database.
     109             :          * @param game:     valid pointer to a Game object with the new data.
     110             :          * @param replaced: valid gamenumT of the game to be replaced
     111             :          * @returns OK if successful or an error code.
     112             :          */
     113             :         virtual errorT saveGame(Game* game, gamenumT replaced) = 0;
     114             : 
     115             :         /**
     116             :          * Replaces a game's IndexEntry (which contains the header data of a game).
     117             :          * @param ie:       reference to the IndexEntry with the new data.
     118             :          * @param replaced: valid gamenumT of the game to be replaced
     119             :          * @returns OK if successful or an error code.
     120             :          */
     121             :         virtual errorT saveIndexEntry(const IndexEntry& ie, gamenumT replaced) = 0;
     122             : 
     123             :         /**
     124             :          * Adds a name (player, event, site or round) to the database.
     125             :          * @param nt:   nameT type of the name to add.
     126             :          * @param name: the name to add.
     127             :          * @returns
     128             :          * - on success, a @e std::pair containing OK and the corresponding ID.
     129             :          * - on failure, a @e std::pair containing an error code and 0.
     130             :          */
     131             :         virtual std::pair<errorT, idNumberT> addName(nameT nt,
     132             :                                                      const char* name) = 0;
     133             : 
     134             :         /**
     135             :          * Writes all pending output to the files.
     136             :          * @returns OK if successful or an error code.
     137             :          */
     138             :         virtual errorT flush() = 0;
     139             : 
     140             : private:
     141             :         /**
     142             :          * Opens/Creates a database.
     143             :          * This virtual function is called only once immediately after the class
     144             :          * constructor.
     145             :          * @param fMode:    a valid file mode.
     146             :          * @param filename: the full path of the database to open.
     147             :          * @param progress: a Progress object used for GUI communications.
     148             :          * @param idx:      valid pointer to the Index object for this database.
     149             :          * @param nb:       valid pointer to the NameBase object for this database.
     150             :          * @returns
     151             :          * - OK: the object is ready to be used.
     152             :          * - ERROR_NameDataLoss: some names are corrupted and cannot be recovered,
     153             :          *                       however the object can still be used.
     154             :          * - Other error codes: the operation failed (the object must be destroyed).
     155             :          */
     156             :         virtual errorT dyn_open(fileModeT fMode, const char* filename,
     157             :                                 const Progress& progress, Index* idx,
     158             :                                 NameBase* nb) = 0;
     159             : };
     160             : 
     161             : #endif

Generated by: LCOV version 1.13