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 fMode: a valid file mode.
52 : * @param filename: the full path of the database to be opened.
53 : * @param progress: a Progress object used for GUI communications.
54 : * @param idx: valid pointer to the Index object for this database.
55 : * @param nb: valid pointer to the NameBase object for this database.
56 : * @returns
57 : * - on success: a valid pointer to the new object and OK.
58 : * - on error: nullptr and the error code.
59 : */
60 : static std::pair<ICodecDatabase*, errorT> open(Codec codec, fileModeT fMode,
61 : const char* filename,
62 : const Progress& progress,
63 : Index* idx, NameBase* nb);
64 :
65 : /**
66 : * Returns the Codec type.
67 : */
68 : virtual Codec getType() const = 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() const = 0;
76 :
77 : /**
78 : * Returns a vector of tag pairs containing extra information about the
79 : * database (type, description, autoload, etc..)
80 : */
81 : virtual std::vector<std::pair<const char*, std::string>>
82 : getExtraInfo() const = 0;
83 :
84 : /**
85 : * Fetches the data of a game (excluding index info), encoded in native
86 : * format.
87 : * @param offset: offset of the requested game.
88 : * @param length: length of the game data (in bytes).
89 : * @returns
90 : * - a pointer to the game data.
91 : * - 0 (nullptr) on error.
92 : */
93 : virtual const byte* getGameData(uint64_t offset, uint32_t length) = 0;
94 :
95 : /**
96 : * Add a game to the database.
97 : * @param srcIe: valid pointer to the header data.
98 : * @param srcNb: valid pointer to the NameBase containing srcIe's names.
99 : * @param srcData: valid pointer to a buffer containing the game data
100 : * (encoded in native format).
101 : * @param dataLen: length of the game data (in bytes).
102 : * @returns OK if successful or an error code.
103 : */
104 : virtual errorT addGame(const IndexEntry* srcIe, const NameBase* srcNb,
105 : const byte* srcData, size_t dataLen) = 0;
106 :
107 : /**
108 : * Add a game to the database.
109 : * @param game: valid pointer to a Game object with the data of the game.
110 : * @returns OK if successful or an error code.
111 : */
112 : virtual errorT addGame(Game* game) = 0;
113 :
114 : /**
115 : * Replaces a game in the database.
116 : * @param game: valid pointer to a Game object with the new data.
117 : * @param replaced: valid gamenumT of the game to be replaced
118 : * @returns OK if successful or an error code.
119 : */
120 : virtual errorT saveGame(Game* game, gamenumT replaced) = 0;
121 :
122 : /**
123 : * Replaces a game's IndexEntry (which contains the header data of a game).
124 : * @param ie: reference to the IndexEntry with the new data.
125 : * @param replaced: valid gamenumT of the game to be replaced
126 : * @returns OK if successful or an error code.
127 : */
128 : virtual errorT saveIndexEntry(const IndexEntry& ie, gamenumT replaced) = 0;
129 :
130 : /**
131 : * Adds a name (player, event, site or round) to the database.
132 : * @param nt: nameT type of the name to add.
133 : * @param name: the name to add.
134 : * @returns
135 : * - on success, a @e std::pair containing OK and the corresponding ID.
136 : * - on failure, a @e std::pair containing an error code and 0.
137 : */
138 : virtual std::pair<errorT, idNumberT> addName(nameT nt,
139 : const char* name) = 0;
140 :
141 : /**
142 : * Writes all pending output to the files.
143 : * @returns OK if successful or an error code.
144 : */
145 : virtual errorT flush() = 0;
146 :
147 : private:
148 : /**
149 : * Opens/Creates a database.
150 : * This virtual function is called only once immediately after the class
151 : * constructor.
152 : * @param fMode: a valid file mode.
153 : * @param filename: the full path of the database to open.
154 : * @param progress: a Progress object used for GUI communications.
155 : * @param idx: valid pointer to the Index object for this database.
156 : * @param nb: valid pointer to the NameBase object for this database.
157 : * @returns
158 : * - OK: the object is ready to be used.
159 : * - ERROR_NameDataLoss: some names are corrupted and cannot be recovered,
160 : * however the object can still be used.
161 : * - Other error codes: the operation failed (the object must be destroyed).
162 : */
163 : virtual errorT dyn_open(fileModeT fMode, const char* filename,
164 : const Progress& progress, Index* idx,
165 : NameBase* nb) = 0;
166 : };
167 :
168 : #endif
|
