00001 /* This file is part of LingoTeach, the Language Teaching program 00002 * Copyright (C) 2001-2003 The LingoTeach Team 00003 * 00004 * This program is free software; you can redistribute it and/or modify 00005 * it under the terms of the GNU General Public License as published by 00006 * the Free Software Foundation; either version 2 of the License, or 00007 * (at your option) any later version. 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00017 */ 00018 00019 #ifndef LINGOTEACH_H 00020 #define LINGOTEACH_H 1 00021 00022 #include "lingdefs.h" 00023 00024 /* 00025 * This file defines all functions that can be used to access 00026 * data. No XML filenames should be ever visible outside this module. 00027 */ 00028 00029 /** 00030 * Creates a new, empty lingConfig for usage. 00031 * The lingConfig has to be freed by the user. 00032 * 00033 * \return A new lingConfig. 00034 */ 00035 lingConfig* 00036 ling_conf_init_config (void); 00037 00038 /** 00039 * Sets the application name in a lingConfig. 00040 * 00041 * \param settings The settings to modify. 00042 * \param name The name of the application, which uses the library. 00043 * \return the modified settings, if the name could be applied to them. 00044 */ 00045 lingConfig* 00046 ling_conf_set_app_name (lingConfig *settings, lingchar *name); 00047 00048 /** 00049 * Sets the full qualified path to the language file in a lingConfig. 00050 * 00051 * \param settings The settings to modify. 00052 * \param lfile The file, which contains the languages. 00053 * \return The modifed settings, if the language file could be applied to them. 00054 */ 00055 lingConfig* 00056 ling_conf_set_lang_file (lingConfig *settings, lingchar *lfile); 00057 00058 /** 00059 * Creates a new lingMeaning and returns it. 00060 * The lingMeaning has to be freed by the user. 00061 * 00062 * \return A new, empty lingMeaning. 00063 */ 00064 lingMeaning* 00065 ling_meaning_get_new (void); 00066 00067 /** 00068 * Searches for a lingMeaning, that is the same type as the one, that is passed 00069 * to it. This helps to make sure, that multiple choice answers are not 00070 * obvious. (Currently not functional!). 00071 * The lingMeaning has to be freed by the user. 00072 * 00073 * \param meaning A lingMeaning, for which a similar one should be found. 00074 * \return A meaning that is the same type of thing as the one that 00075 * is passed to it. 00076 */ 00077 /* 00078 lingMeaning* 00079 ling_meaning_get_similar (lingMeaning *meaning); 00080 */ 00081 00082 /** 00083 * Gets another lingMeaning from a lesson file. 00084 * The lingMeaning has to be freed by the user. 00085 * 00086 * \param lesson The lesson to fetch the meaning from. 00087 * \param type The method to use for getting the lingMeaning. 00088 * \param language The language, which should be used. 00089 * \return A meaning pointer, using the method given as argument 00090 * to the function. 00091 */ 00092 lingMeaning* 00093 ling_meaning_get_another_meaning (lingLesson *lesson, Method type, 00094 char *language); 00095 00096 /** 00097 * Gets a specific lingMeaning from the given lesson. 00098 * The lingMeaning has to be freed by the user. 00099 * 00100 * \param lesson The lesson to fetch the meaning from. 00101 * \param id The id, which should be searched for. 00102 * \param language The language, which should be used. 00103 * \return a lingMeaning containing the meaning, which has the given id. 00104 * If none is found with the given language, the function returns NULL. 00105 */ 00106 lingMeaning* 00107 ling_meaning_get_by_word_id (lingLesson *lesson, int id, char *language); 00108 00109 /** 00110 * Frees the memory used by a list of lingMeaning and the lingMeanings itself 00111 * 00112 * \param meaning The meaning list to free. 00113 */ 00114 void 00115 ling_meaning_free_meaning (lingMeaning *meaning); 00116 00117 /** 00118 * Frees the memory used by a lingMeaning and the lingMeaning itself 00119 * 00120 * \param tree The list of meanings, in which the meanings is. 00121 * \param node The meaning, which should be freed. 00122 * return The new list without the freed meaning. 00123 */ 00124 lingMeaning* 00125 ling_meaning_free_meaning_1 (lingMeaning *tree, lingMeaning *node); 00126 00127 /** 00128 * Saves a list of meanings into a given lesson file. The format is 00129 * the standard lingoteach lesson format. 00130 * 00131 * \param meaning The list of meanings to save. 00132 * \param filename The file the meanings should be saved in. 00133 * \param settings The settings to use for the file. 00134 * \return TRUE on succesful saving, else FALSE. 00135 */ 00136 lingbool 00137 ling_meaning_save_meanings (lingMeaning *meaning, char *filename, 00138 lingConfig *settings); 00139 00140 /** 00141 * Adds a new meaning at the end of the given list. 00142 * 00143 * \param tree The meaning list to which the meaning should be added. 00144 * \param meaning The meaning to add to the tree. 00145 * \return The new, modified tree. 00146 */ 00147 lingMeaning* 00148 ling_meaning_add_meaning (lingMeaning *tree, lingMeaning *meaning); 00149 00150 /** 00151 * Inserts a meaning after specific meaning into a meaning list. 00152 * 00153 * \param tree The meaning list to which the meaning should be added. 00154 * \param parent The parent meaning, after whihc the child should be added. 00155 * \param child The meaning to add. 00156 * \return The new, modified tree. 00157 */ 00158 lingMeaning* 00159 ling_meaning_insert_after_meaning (lingMeaning *tree, lingMeaning *parent, 00160 lingMeaning *child); 00161 00162 /** 00163 * Modifies a meaning of the given list of meanings 00164 * 00165 * \param tree The list of meanings in which the meaning exists. 00166 * \param id The id of the meaning, which should be modified. 00167 * \param meaning The modified meaning . 00168 * \return The tree with the modified meaning. 00169 */ 00170 lingMeaning* 00171 ling_meaning_modify_meaning (lingMeaning *tree, int id, lingMeaning *meaning); 00172 00173 /** 00174 * Returns the path to the sound snippet for the given meaning. 00175 * 00176 * \param soundpath The full qualified path to the sound files. 00177 * \param meaning The lingMeaning the sound snippet has to be found for. 00178 * \return The full qualified path to the sound snippet of the meaning. 00179 */ 00180 char* 00181 ling_meaning_find_sound (char *soundpath, lingMeaning *meaning); 00182 00183 /** 00184 * Allocates a chunk of memory for usage 00185 * 00186 * \param bytes The count of bytes to allocate 00187 * \return A pointer to the newly allocated space 00188 */ 00189 void* 00190 ling_malloc (size_t bytes); 00191 00192 /** 00193 * Frees the memory hold by a pointer, which was previously allocated 00194 * using ling_malloc(). 00195 * 00196 * \param ptr The pointer to free. 00197 */ 00198 void 00199 ling_free (void *ptr); 00200 00201 /** 00202 * Prepares and adds a lesson file to an existing list of lessons. 00203 * 00204 * \param lesson The lesson list, the new lesson should be added to. 00205 * If lesson is NULL, a new list will be created and returned. 00206 * \param filename The full qualified file path of the file. 00207 * \param settings The settings to use for the lesson. 00208 * \return The new lesson list. 00209 */ 00210 lingLesson* 00211 ling_lesson_add_lesson (lingLesson *lesson, char *filename, 00212 lingConfig *settings); 00213 00214 /** 00215 * Removes a lesson from the list of used ones and frees all its 00216 * internal references. 00217 * 00218 * \param lesson The lesson list to look for the lesson. 00219 * \param node The lesson to free. 00220 * \return The modified lesson list. 00221 */ 00222 lingLesson* 00223 ling_lesson_remove_lesson (lingLesson *lesson, lingLesson *node); 00224 00225 /** 00226 * Returns the full qualified file path of the matching lesson entry. 00227 * 00228 * \param lesson The lesson for which the path should be returned. 00229 * \return The lesson path of the lesson, else NULL. 00230 */ 00231 char* 00232 ling_lesson_return_path (lingLesson *lesson); 00233 00234 /** 00235 * Modifies the usage flag of a lesson, so that it will be automatically used 00236 * by the different meaning access functions. 00237 * 00238 * \param lesson The lesson to use 00239 * \param use A boolean statement for usage (TRUE or FALSE). 00240 */ 00241 void 00242 ling_lesson_use_lesson (lingLesson *lesson, lingbool use); 00243 00244 /** 00245 * Returns the status of the use-flag of a lesson. 00246 * 00247 * \param lesson The lesson, the usage flag should be returned for. 00248 * \return TRUE, if the lesson is currently marked as used 00249 * in the internal list, else FALSE. 00250 */ 00251 lingbool 00252 ling_lesson_return_used (lingLesson *lesson); 00253 00254 /** 00255 * Returns the last meaning id of the given lesson. 00256 * 00257 * \param lesson The lesson, for which the max. meaning id should be returned. 00258 * \return the maximum (last!) meaning id of a lesson file (can be 0, if it 00259 * fails). 00260 */ 00261 int 00262 ling_lesson_get_max_meaning (lingLesson *lesson); 00263 00264 /** 00265 * Saves a lesson into the passed file. 00266 * If the file does not exist, it will be automatically created, else 00267 * its contents will be completely overwritten. 00268 * 00269 * \param lesson The lesson to save. 00270 * \param filename The lesson file for saving the lesson. 00271 * \return TRUE, if the lesson could be saved, else FALSE. 00272 */ 00273 lingbool 00274 ling_lesson_save_lesson (lingLesson *lesson, char *filename); 00275 00276 /** 00277 * Creates a new template lesson with optional empty meanings. 00278 * 00279 * \param filename The lesson file to create. 00280 * \param meanings The amount of meaning templates to create. 00281 * \return The filename on success or NULL 00282 */ 00283 char* 00284 ling_lesson_create_new (char *filename, int meanings); 00285 00286 /** 00287 * Creates a linked list of meanings, which are available in the given file. 00288 * 00289 * \param lesson The lesson, from which the tree should be created. 00290 * \return A linked list of meanings of the lesson. 00291 */ 00292 lingMeaning* 00293 ling_lesson_create_tree (lingLesson *lesson); 00294 00295 /** 00296 * Returns a random lesson of the lesson list, which is passed as argument. 00297 * Lessons which are not used are ignored. The function tries to determine 00298 * an used lesson twenty times. If none is found, NULL will be returned. 00299 * 00300 * \param lesson The lesson list to use for the random lesson. 00301 * \return A random lesson or NULL if none found after twenty rounds. 00302 */ 00303 lingLesson* 00304 ling_lesson_return_rand_lesson (lingLesson *lesson); 00305 00306 /** 00307 * Gets a NULL terminated list of available languages (based on the language 00308 * file set in the lingConfig). The return value should to be freed using 00309 * ling_lang_free_languages(). 00310 * 00311 * \param settings The lingConfig to use for looking up the languages. 00312 * \return a NULL terminated list of the languages 00313 */ 00314 lingchar** 00315 ling_lang_get_languages (lingConfig *settings); 00316 00317 /** 00318 * Gets the count of languages contained in a lingConfig. 00319 * 00320 * \param settings The lingConfig to use for looking up the languages. 00321 * \return An integer showing the maximum count of the languages or 00322 * -1 on failure. 00323 */ 00324 int 00325 ling_lang_get_max_languages (lingConfig *settings); 00326 00327 /** 00328 * Frees a previously allocated array of languages. 00329 * 00330 * \param languages The array of languages 00331 * \param size The size of the array 00332 */ 00333 void 00334 ling_lang_free_languages (lingchar **languages, int size); 00335 00336 #endif /* LINGOTEACH_H */