Scid  4.6.5
codec.h
Go to the documentation of this file.
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  */
44 public:
45  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(uint32_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 src: valid pointer to a buffer containing the game data
92  * (encoded in native format).
93  * @param length: length of the game data (in bytes).
94  * @returns OK if successful or an error code.
95  */
96  virtual errorT addGame(IndexEntry* srcIe, const byte* src,
97  size_t length) = 0;
98 
99  /**
100  * Add a game to the database.
101  * @param game: valid pointer to a Game object with the data of the game.
102  * @returns OK if successful or an error code.
103  */
104  virtual errorT addGame(Game* game) = 0;
105 
106  /**
107  * Replaces a game in the database.
108  * @param srcIe: valid pointer to the new header data.
109  * @param src: valid pointer to a buffer containing the new game data
110  * (encoded in native format).
111  * @param length: length of the new game data (in bytes).
112  * @param replaced: valid gamenumT of the game to be replaced.
113  * @returns OK if successful or an error code.
114  */
115  virtual errorT saveGame(IndexEntry* srcIe, const byte* src, size_t length,
116  gamenumT replaced) = 0;
117  /**
118  * Replaces a game in the database.
119  * @param game: valid pointer to a Game object with the new data.
120  * @param replaced: valid gamenumT of the game to be replaced
121  * @returns OK if successful or an error code.
122  */
123  virtual errorT saveGame(Game* game, gamenumT replaced) = 0;
124 
125  /**
126  * Writes all pending output to the files.
127  * @returns OK if successful or an error code.
128  */
129  virtual errorT flush() = 0;
130 
131 private:
132  /**
133  * Opens/Creates a database.
134  * This virtual function is called only once immediately after the class
135  * constructor.
136  * @param fMode: a valid file mode.
137  * @param filename: the full path of the database to open.
138  * @param progress: a Progress object used for GUI communications.
139  * @param idx: valid pointer to the Index object for this database.
140  * @param nb: valid pointer to the NameBase object for this database.
141  * @returns
142  * - OK: the object is ready to be used.
143  * - ERROR_NameDataLoss: some names are corrupted and cannot be recovered,
144  * however the object can still be used.
145  * - Other error codes: the operation failed (the object must be destroyed).
146  */
147  virtual errorT dyn_open(fileModeT fMode, const char* filename,
148  const Progress& progress, Index* idx,
149  NameBase* nb) = 0;
150 };
151 
152 #endif
unsigned char byte
Definition: common.h:97
Definition: misc.h:124
virtual std::vector< std::string > getFilenames()=0
Returns the full path of the files used by the database.
virtual errorT saveGame(IndexEntry *srcIe, const byte *src, size_t length, gamenumT replaced)=0
Replaces a game in the database.
virtual ~ICodecDatabase()
Definition: codec.h:45
virtual errorT flush()=0
Writes all pending output to the files.
static ICodecDatabase * make(Codec codec, errorT *err, fileModeT fMode, const char *filename, const Progress &progress, Index *idx, NameBase *nb)
Creates a new object and calls the virtual function dyn_open().
Definition: scidbase.cpp:29
This interface separates the logic of a database from its representation.
Definition: codec.h:43
virtual const byte * getGameData(uint32_t offset, uint32_t length)=0
Fetches the data of a game (excluding index info), encoded in native format.
Definition: index.h:61
unsigned short errorT
Definition: error.h:20
Definition: game.h:227
virtual errorT addGame(IndexEntry *srcIe, const byte *src, size_t length)=0
Add a game to the database.
uint gamenumT
Definition: common.h:159
fileModeT
Definition: common.h:144
virtual Codec getType()=0
Returns the Codec type.
Definition: indexentry.h:54