Main Page | Alphabetical List | Data Structures | File List | Data Fields | Globals

lingoteach.h

Go to the documentation of this file.
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 */

Generated on Sun Nov 23 22:33:44 2003 for liblingoteach by doxygen 1.3.3