From 827b50a29d510fb93d03e83a56d11518298d2db8 Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 11:12:35 +0100 Subject: [PATCH 1/9] CodeMaid API header cleanup. --- src/api/api.h | 491 ++++++++++++++++++++++++-------------------------- 1 file changed, 238 insertions(+), 253 deletions(-) diff --git a/src/api/api.h b/src/api/api.h index 0749fadb..ef7cd61a 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -20,7 +20,7 @@ You should have received a copy of the GNU General Public License along with LOOT. If not, see . -*/ + */ /** @file api.h @@ -31,10 +31,10 @@ @section var_sec Variable Types The LOOT API uses character strings and integers for information input/output. - - All strings are null-terminated byte character strings encoded in UTF-8. - - All codes are unsigned integers at least 16 bits in size. - - All array sizes are unsigned integers at least 16 bits in size. - - File paths are case-sensitive if and only if the underlying file system is case-sensitive. + - All strings are null-terminated byte character strings encoded in UTF-8. + - All codes are unsigned integers at least 16 bits in size. + - All array sizes are unsigned integers at least 16 bits in size. + - File paths are case-sensitive if and only if the underlying file system is case-sensitive. @section memory_sec Memory Management @@ -43,7 +43,7 @@ Data returned by a function lasts until a function is called which returns data of the same type (eg. a string is stored until the client calls another function which returns a string, an integer array lasts until another integer array is returned, etc.). All allocated memory is freed when loot_destroy_db() is called, except the string allocated by loot_get_error_message(), which must be freed by calling loot_cleanup(). -*/ + */ #ifndef __LOOT_API_H__ #define __LOOT_API_H__ @@ -85,286 +85,271 @@ extern "C" { #endif + //////////////////////// + // Types + //////////////////////// -//////////////////////// -// Types -//////////////////////// + /** + @brief A structure that holds all game-specific data used by the LOOT API. + @details Used to keep each game's data independent. Abstracts the definition of the API's internal state while still providing type safety across the library. Multiple handles can also be made for each game, though it should be kept in mind that the API is not thread-safe. + */ + typedef struct _loot_db_int * loot_db; -/** - @brief A structure that holds all game-specific data used by the LOOT API. - @details Used to keep each game's data independent. Abstracts the definition of the API's internal state while still providing type safety across the library. Multiple handles can also be made for each game, though it should be kept in mind that the API is not thread-safe. -*/ -typedef struct _loot_db_int * loot_db; + /** + @brief A structure that holds the type of a message and the message string itself. + @var loot_message::type The type of the message, specified using one of the message type codes given below. + @var loot_message::message The message string itself. + */ + typedef struct { + unsigned int type; + const char * message; + } loot_message; -/** - @brief A structure that holds the type of a message and the message string itself. - @var loot_message::type The type of the message, specified using one of the message type codes given below. - @var loot_message::message The message string itself. -*/ -typedef struct { - unsigned int type; - const char * message; -} loot_message; + /*********************//** + @name Return Codes + @brief Error codes signify an issue that caused a function to exit prematurely. If a function exits prematurely, a reversal of any changes made during its execution is attempted before it exits. + *************************/ + ///@{ + LOOT_API extern const unsigned int loot_ok; ///< The function completed successfully. + LOOT_API extern const unsigned int loot_error_liblo_error; ///< There was an error in performing a load order operation. + LOOT_API extern const unsigned int loot_error_file_write_fail; ///< A file could not be written to. + LOOT_API extern const unsigned int loot_error_parse_fail; ///< There was an error parsing the file. + LOOT_API extern const unsigned int loot_error_condition_eval_fail; ///< There was an error evaluating the conditionals in a metadata file. + LOOT_API extern const unsigned int loot_error_regex_eval_fail; ///< There was an error evaluating the regular expressions in a metadata file. + LOOT_API extern const unsigned int loot_error_no_mem; ///< The API was unable to allocate the required memory. + LOOT_API extern const unsigned int loot_error_invalid_args; ///< Invalid arguments were given for the function. + LOOT_API extern const unsigned int loot_error_no_tag_map; ///< No Bash Tag map has been generated yet. + LOOT_API extern const unsigned int loot_error_path_not_found; ///< A file or folder path could not be found. + LOOT_API extern const unsigned int loot_error_no_game_detected; ///< The given game could not be found. + LOOT_API extern const unsigned int loot_error_windows_error; ///< An error occurred during a call to the Windows API. + LOOT_API extern const unsigned int loot_error_sorting_error; ///< An error occurred while sorting plugins. + /** + @brief Matches the value of the highest-numbered return code. + @details Provided in case clients wish to incorporate additional return codes in their implementation and desire some method of avoiding value conflicts. + */ + LOOT_API extern const unsigned int loot_return_max; -/*********************//** - @name Return Codes - @brief Error codes signify an issue that caused a function to exit prematurely. If a function exits prematurely, a reversal of any changes made during its execution is attempted before it exits. -*************************/ -///@{ + ///@} -LOOT_API extern const unsigned int loot_ok; ///< The function completed successfully. -LOOT_API extern const unsigned int loot_error_liblo_error; ///< There was an error in performing a load order operation. -LOOT_API extern const unsigned int loot_error_file_write_fail; ///< A file could not be written to. -LOOT_API extern const unsigned int loot_error_parse_fail; ///< There was an error parsing the file. -LOOT_API extern const unsigned int loot_error_condition_eval_fail; ///< There was an error evaluating the conditionals in a metadata file. -LOOT_API extern const unsigned int loot_error_regex_eval_fail; ///< There was an error evaluating the regular expressions in a metadata file. -LOOT_API extern const unsigned int loot_error_no_mem; ///< The API was unable to allocate the required memory. -LOOT_API extern const unsigned int loot_error_invalid_args; ///< Invalid arguments were given for the function. -LOOT_API extern const unsigned int loot_error_no_tag_map; ///< No Bash Tag map has been generated yet. -LOOT_API extern const unsigned int loot_error_path_not_found; ///< A file or folder path could not be found. -LOOT_API extern const unsigned int loot_error_no_game_detected; ///< The given game could not be found. -LOOT_API extern const unsigned int loot_error_windows_error; ///< An error occurred during a call to the Windows API. -LOOT_API extern const unsigned int loot_error_sorting_error; ///< An error occurred while sorting plugins. + /*******************//** + @name Game Codes + @brief Used with loot_create_db(). + ***********************/ + ///@{ + LOOT_API extern const unsigned int loot_game_tes4; ///< Game code for The Elder Scrolls IV: Oblivion. + LOOT_API extern const unsigned int loot_game_tes5; ///< Game code for The Elder Scrolls V: Skyrim. + LOOT_API extern const unsigned int loot_game_fo3; ///< Game code for Fallout 3. + LOOT_API extern const unsigned int loot_game_fonv; ///< Game code for Fallout: New Vegas. -/** - @brief Matches the value of the highest-numbered return code. - @details Provided in case clients wish to incorporate additional return codes in their implementation and desire some method of avoiding value conflicts. -*/ -LOOT_API extern const unsigned int loot_return_max; + ///@} -///@} + /***************************//** + @name Message Type Codes + @brief Used with the loot_message structure. + *******************************/ + ///@{ + LOOT_API extern const unsigned int loot_message_say; ///< Denotes a generic note-type message. + LOOT_API extern const unsigned int loot_message_warn; ///< Denotes a warning message. + LOOT_API extern const unsigned int loot_message_error; ///< Denotes an error message. -/*******************//** - @name Game Codes - @brief Used with loot_create_db(). -***********************/ -///@{ + /** + @brief Denites a Bash Tag suggestion message. + @details This type should never be seen client-side as it is only used during conversion between internal Bash Tag and message structures, but it is provided just in case. + */ + LOOT_API extern const unsigned int loot_message_tag; -LOOT_API extern const unsigned int loot_game_tes4; ///< Game code for The Elder Scrolls IV: Oblivion. -LOOT_API extern const unsigned int loot_game_tes5; ///< Game code for The Elder Scrolls V: Skyrim. -LOOT_API extern const unsigned int loot_game_fo3; ///< Game code for Fallout 3. -LOOT_API extern const unsigned int loot_game_fonv; ///< Game code for Fallout: New Vegas. + ///@} -///@} + /*******************************//** + @name Message Language Codes + @brief Used with loot_eval_lists(). + ***********************************/ + ///@{ + LOOT_API extern const unsigned int loot_lang_any; ///< Tells the API to select messages of any language. + LOOT_API extern const unsigned int loot_lang_english; ///< Tells the API to preferentially select English messages. + LOOT_API extern const unsigned int loot_lang_spanish; ///< Tells the API to preferentially select Spanish messages. + LOOT_API extern const unsigned int loot_lang_russian; ///< Tells the API to preferentially select Russian messages. + LOOT_API extern const unsigned int loot_lang_french; ///< Tells the API to preferentially select French messages. + LOOT_API extern const unsigned int loot_lang_chinese; ///< Tells the API to preferentially select Chinese messages. + LOOT_API extern const unsigned int loot_lang_polish; ///< Tells the API to preferentially select Polish messages. + LOOT_API extern const unsigned int loot_lang_brazilian_portuguese; ///< Tells the API to preferentially select Brazilian Portuguese messages. + LOOT_API extern const unsigned int loot_lang_finnish; ///< Tells the API to preferentially select Finnish messages. + LOOT_API extern const unsigned int loot_lang_german; ///< Tells the API to preferentially select German messages. + ///@} -/***************************//** - @name Message Type Codes - @brief Used with the loot_message structure. -*******************************/ -///@{ -LOOT_API extern const unsigned int loot_message_say; ///< Denotes a generic note-type message. -LOOT_API extern const unsigned int loot_message_warn; ///< Denotes a warning message. -LOOT_API extern const unsigned int loot_message_error; ///< Denotes an error message. + /*********************************//** + @name Plugin Cleanliness Codes + @brief Used with loot_get_dirty_message(). + *************************************/ + ///@{ + LOOT_API extern const unsigned int loot_needs_cleaning_no; ///< Denotes that the plugin queried does not need cleaning. + LOOT_API extern const unsigned int loot_needs_cleaning_yes; ///< Denotes that the plugin queried needs cleaning. + LOOT_API extern const unsigned int loot_needs_cleaning_unknown; ///< Denotes that the API is unable to determine whether or not the plugin queried needs cleaning. -/** - @brief Denites a Bash Tag suggestion message. - @details This type should never be seen client-side as it is only used during conversion between internal Bash Tag and message structures, but it is provided just in case. -*/ -LOOT_API extern const unsigned int loot_message_tag; + ///@} -///@} + /*********************************//** + @name Error Handling Functions + *************************************/ + ///@{ + /** + @brief Returns the message for the last error or warning encountered. + @details Outputs a string giving the a message containing the details of the last error or warning encountered by a function. Each time this function is called, the memory for the previous message is freed, so only one error message is available at any one time. + @param details A pointer to the error details string outputted by the function. + @returns A return code. + */ + LOOT_API unsigned int loot_get_error_message(const char ** const message); -/*******************************//** - @name Message Language Codes - @brief Used with loot_eval_lists(). -***********************************/ -///@{ -LOOT_API extern const unsigned int loot_lang_any; ///< Tells the API to select messages of any language. -LOOT_API extern const unsigned int loot_lang_english; ///< Tells the API to preferentially select English messages. -LOOT_API extern const unsigned int loot_lang_spanish; ///< Tells the API to preferentially select Spanish messages. -LOOT_API extern const unsigned int loot_lang_russian; ///< Tells the API to preferentially select Russian messages. -LOOT_API extern const unsigned int loot_lang_french; ///< Tells the API to preferentially select French messages. -LOOT_API extern const unsigned int loot_lang_chinese; ///< Tells the API to preferentially select Chinese messages. -LOOT_API extern const unsigned int loot_lang_polish; ///< Tells the API to preferentially select Polish messages. -LOOT_API extern const unsigned int loot_lang_brazilian_portuguese; ///< Tells the API to preferentially select Brazilian Portuguese messages. -LOOT_API extern const unsigned int loot_lang_finnish; ///< Tells the API to preferentially select Finnish messages. -LOOT_API extern const unsigned int loot_lang_german; ///< Tells the API to preferentially select German messages. -///@} + /** + @brief Frees the memory allocated to the last error details string. + */ + LOOT_API void loot_cleanup(); -/*********************************//** - @name Plugin Cleanliness Codes - @brief Used with loot_get_dirty_message(). -*************************************/ -///@{ -LOOT_API extern const unsigned int loot_needs_cleaning_no; ///< Denotes that the plugin queried does not need cleaning. -LOOT_API extern const unsigned int loot_needs_cleaning_yes; ///< Denotes that the plugin queried needs cleaning. -LOOT_API extern const unsigned int loot_needs_cleaning_unknown; ///< Denotes that the API is unable to determine whether or not the plugin queried needs cleaning. + ///@} -///@} + /**************************//** + @name Version Functions + ******************************/ + ///@{ + /** + @brief Checks for API compatibility. + @details Checks whether the loaded API is compatible with the given version of the API, abstracting API stability policy away from clients. The version numbering used is major.minor.patch. + @param versionMajor The major version number to check. + @param versionMinor The minor version number to check. + @param versionPatch The patch version number to check. + @returns True if the API versions are compatible, false otherwise. + */ + LOOT_API bool loot_is_compatible(const unsigned int versionMajor, const unsigned int versionMinor, const unsigned int versionPatch); + /** + @brief Gets the API version. + @details Outputs the major, minor and patch version numbers for the loaded API. The version numbering used is major.minor.patch. + @param versionMajor A pointer to the major version number. + @param versionMinor A pointer to the minor version number. + @param versionPatch A pointer to the patch version number. + */ + LOOT_API unsigned int loot_get_version(unsigned int * const versionMajor, unsigned int * const versionMinor, unsigned int * const versionPatch); -/*********************************//** - @name Error Handling Functions -*************************************/ -///@{ + ///@} -/** - @brief Returns the message for the last error or warning encountered. - @details Outputs a string giving the a message containing the details of the last error or warning encountered by a function. Each time this function is called, the memory for the previous message is freed, so only one error message is available at any one time. - @param details A pointer to the error details string outputted by the function. - @returns A return code. -*/ -LOOT_API unsigned int loot_get_error_message (const char ** const message); + /***************************************//** + @name Lifecycle Management Functions + *******************************************/ + ///@{ + /** + @brief Initialise a new database handle. + @details Creates a handle for a database, which is then used by all database functions. + @param db A pointer to the handle that is created by the function. + @param gameId A game code specifying which game to create the handle for. + @param gamePath The relative or absolute path to the game folder, ot `NULL`. If `NULL`, the API will attempt to detect the data path of the specified game. + @returns A return code. + */ + LOOT_API unsigned int loot_create_db(loot_db * const db, const unsigned int clientGame, const char * const gamePath); -/** - @brief Frees the memory allocated to the last error details string. -*/ -LOOT_API void loot_cleanup (); + /** + @brief Destroy an existing database handle. + @details Destroys the given database handle, freeing up memory allocated during its use, excluding any memory allocated to error messages. + @param db The database handle to destroy. + */ + LOOT_API void loot_destroy_db(loot_db db); -///@} + ///@} + /***********************************//** + @name Database Loading Functions + ***************************************/ + ///@{ + /** + @brief Loads the masterlist and userlist from the paths specified. + @details Can be called multiple times, each time replacing the previously-loaded data. + @param db The database the function acts on. + @param masterlistPath A string containing the relative or absolute path to the masterlist file that should be loaded. + @param userlistPath A string containing the relative or absolute path to the userlist file that should be loaded, or `NULL`. If `NULL`, no userlist will be loaded. + @returns A return code. + */ + LOOT_API unsigned int loot_load_lists(loot_db db, const char * const masterlistPath, + const char * const userlistPath); -/**************************//** - @name Version Functions -******************************/ -///@{ + /** + @brief Evaluates all conditions and regular expression metadata entries. + @details Repeated calls re-evaluate the metadata from scratch. This function affects the output of all the database access functions. + @param db The database the function acts on. + @param language The language code that is used for message language comparisons. + @returns A return code. + */ + LOOT_API unsigned int loot_eval_lists(loot_db db, const unsigned int language); -/** - @brief Checks for API compatibility. - @details Checks whether the loaded API is compatible with the given version of the API, abstracting API stability policy away from clients. The version numbering used is major.minor.patch. - @param versionMajor The major version number to check. - @param versionMinor The minor version number to check. - @param versionPatch The patch version number to check. - @returns True if the API versions are compatible, false otherwise. -*/ -LOOT_API bool loot_is_compatible (const unsigned int versionMajor, const unsigned int versionMinor, const unsigned int versionPatch); + ///@} -/** - @brief Gets the API version. - @details Outputs the major, minor and patch version numbers for the loaded API. The version numbering used is major.minor.patch. - @param versionMajor A pointer to the major version number. - @param versionMinor A pointer to the minor version number. - @param versionPatch A pointer to the patch version number. -*/ -LOOT_API unsigned int loot_get_version (unsigned int * const versionMajor, unsigned int * const versionMinor, unsigned int * const versionPatch); + /**********************************//** + @name Database Access Functions + **************************************/ + ///@{ + /** + @brief Outputs an array of the Bash Tags that are suggested in the database. + @details This function must be called prior to calling loot_get_plugin_tags() to ensure that the latter can return the Tags using the correct array indicies. + @param db The database the function acts on. + @param tagMap A pointer to the outputted array of Bash Tags. The array functions as a map where the indicies are the keys, allowing the API to use them as UIDs for Bash Tags instead of passing their names as strings every time loot_get_plugin_tags() is called. If no Bash Tags are suggested, this will be `NULL`. + @param numTags A pointer to the size of the outputted array. If no Bash Tags are suggested, this will be `0`. + @returns A return code. + */ + LOOT_API unsigned int loot_get_tag_map(loot_db db, char *** const tagMap, size_t * const numTags); + /** + @brief Outputs the Bash Tags suggested for addition and removal by the database for the given plugin. + @details loot_get_tag_map() must be called before this to ensure that the Bash Tag UIDs outputted by this function can be matched up to name strings. + @param db The database the function acts on. + @param plugin The filename of the plugin to look up Bash Tag suggestions for. + @param tags_added A pointer to the outputted array of UIDs of the Bash Tags suggested for addition to the specified plugin. `NULL` if no Bash Tag additions are suggested. + @param numTags_added A pointer to the size of the tags_added array. `0` if `tags_added` is `NULL`. + @param tags_removed A pointer to the outputted array of UIDs of the Bash Tags suggested for removal from the specified plugin. `NULL` if no Bash Tag removals are suggested. + @param numTags_removed A pointer to the size of the `tags_removed` array. `0` if `tags_removed` is `null`. + @param userlistModified `true` if the Bash Tag suggestions were modified by the data in the userlist, `false` otherwise. + @returns A return code. + */ + LOOT_API unsigned int loot_get_plugin_tags(loot_db db, const char * const plugin, + unsigned int ** const tags_added, + size_t * const numTags_added, + unsigned int ** const tags_removed, + size_t * const numTags_removed, + bool * const userlistModified); -///@} + /** + @brief Outputs the messages associated with the given plugin in the database. + @param db The database the function acts on. + @param plugin The filename of the plugin to look up messages for. + @param messages A pointer to the outputted array of messages associated with the specified plugin, given as loot_message structures. `NULL` if the plugin has no messages associated with it. + @param numMessages A pointer to the size of the outputted array. If no messages are outputted, this will be `0`. + @returns A return code. + */ + LOOT_API unsigned int loot_get_plugin_messages(loot_db db, const char * const plugin, + loot_message ** const messages, + size_t * const numMessages); -/***************************************//** - @name Lifecycle Management Functions -*******************************************/ -///@{ + /** + @brief Determines the database's knowledge of a plugin's dirtiness. -/** - @brief Initialise a new database handle. - @details Creates a handle for a database, which is then used by all database functions. - @param db A pointer to the handle that is created by the function. - @param gameId A game code specifying which game to create the handle for. - @param gamePath The relative or absolute path to the game folder, ot `NULL`. If `NULL`, the API will attempt to detect the data path of the specified game. - @returns A return code. -*/ -LOOT_API unsigned int loot_create_db (loot_db * const db, const unsigned int clientGame, const char * const gamePath); + @details Outputs whether the plugin should be cleaned or not, or if no data is available. + @param db The database the function acts on. + @param plugin The plugin to look up dirty status information for. + @param needsCleaning A pointer to a plugin cleanliness code. + @returns A return code. + */ -/** - @brief Destroy an existing database handle. - @details Destroys the given database handle, freeing up memory allocated during its use, excluding any memory allocated to error messages. - @param db The database handle to destroy. -*/ -LOOT_API void loot_destroy_db (loot_db db); + LOOT_API unsigned int loot_get_dirty_info(loot_db db, const char * const plugin, + unsigned int * const needsCleaning); -///@} - - -/***********************************//** - @name Database Loading Functions -***************************************/ -///@{ - -/** - @brief Loads the masterlist and userlist from the paths specified. - @details Can be called multiple times, each time replacing the previously-loaded data. - @param db The database the function acts on. - @param masterlistPath A string containing the relative or absolute path to the masterlist file that should be loaded. - @param userlistPath A string containing the relative or absolute path to the userlist file that should be loaded, or `NULL`. If `NULL`, no userlist will be loaded. - @returns A return code. -*/ -LOOT_API unsigned int loot_load_lists (loot_db db, const char * const masterlistPath, - const char * const userlistPath); - -/** - @brief Evaluates all conditions and regular expression metadata entries. - @details Repeated calls re-evaluate the metadata from scratch. This function affects the output of all the database access functions. - @param db The database the function acts on. - @param language The language code that is used for message language comparisons. - @returns A return code. -*/ -LOOT_API unsigned int loot_eval_lists (loot_db db, const unsigned int language); - -///@} - - -/**********************************//** - @name Database Access Functions -**************************************/ -///@{ - -/** - @brief Outputs an array of the Bash Tags that are suggested in the database. - @details This function must be called prior to calling loot_get_plugin_tags() to ensure that the latter can return the Tags using the correct array indicies. - @param db The database the function acts on. - @param tagMap A pointer to the outputted array of Bash Tags. The array functions as a map where the indicies are the keys, allowing the API to use them as UIDs for Bash Tags instead of passing their names as strings every time loot_get_plugin_tags() is called. If no Bash Tags are suggested, this will be `NULL`. - @param numTags A pointer to the size of the outputted array. If no Bash Tags are suggested, this will be `0`. - @returns A return code. -*/ -LOOT_API unsigned int loot_get_tag_map (loot_db db, char *** const tagMap, size_t * const numTags); - -/** - @brief Outputs the Bash Tags suggested for addition and removal by the database for the given plugin. - @details loot_get_tag_map() must be called before this to ensure that the Bash Tag UIDs outputted by this function can be matched up to name strings. - @param db The database the function acts on. - @param plugin The filename of the plugin to look up Bash Tag suggestions for. - @param tags_added A pointer to the outputted array of UIDs of the Bash Tags suggested for addition to the specified plugin. `NULL` if no Bash Tag additions are suggested. - @param numTags_added A pointer to the size of the tags_added array. `0` if `tags_added` is `NULL`. - @param tags_removed A pointer to the outputted array of UIDs of the Bash Tags suggested for removal from the specified plugin. `NULL` if no Bash Tag removals are suggested. - @param numTags_removed A pointer to the size of the `tags_removed` array. `0` if `tags_removed` is `null`. - @param userlistModified `true` if the Bash Tag suggestions were modified by the data in the userlist, `false` otherwise. - @returns A return code. -*/ -LOOT_API unsigned int loot_get_plugin_tags (loot_db db, const char * const plugin, - unsigned int ** const tags_added, - size_t * const numTags_added, - unsigned int ** const tags_removed, - size_t * const numTags_removed, - bool * const userlistModified); - -/** - @brief Outputs the messages associated with the given plugin in the database. - @param db The database the function acts on. - @param plugin The filename of the plugin to look up messages for. - @param messages A pointer to the outputted array of messages associated with the specified plugin, given as loot_message structures. `NULL` if the plugin has no messages associated with it. - @param numMessages A pointer to the size of the outputted array. If no messages are outputted, this will be `0`. - @returns A return code. -*/ -LOOT_API unsigned int loot_get_plugin_messages (loot_db db, const char * const plugin, - loot_message ** const messages, - size_t * const numMessages); - -/** - @brief Determines the database's knowledge of a plugin's dirtiness. - - @details Outputs whether the plugin should be cleaned or not, or if no data is available. - @param db The database the function acts on. - @param plugin The plugin to look up dirty status information for. - @param needsCleaning A pointer to a plugin cleanliness code. - @returns A return code. -*/ - -LOOT_API unsigned int loot_get_dirty_info (loot_db db, const char * const plugin, - unsigned int * const needsCleaning); - -/** - @brief Writes a minimal metadata file that only contains plugins with Bash Tag suggestions and/or dirty info, plus the suggestions and info themselves. - @param db The database the function acts on. - @param outputFile The path to which the file shall be written. - @param overwrite If `false` and `outputFile` already exists, no data will be written. Otherwise, data will be written. - @returns A return code. -*/ -LOOT_API unsigned int loot_write_minimal_list (loot_db db, const char * const outputFile, const bool overwrite); - -///@} + /** + @brief Writes a minimal metadata file that only contains plugins with Bash Tag suggestions and/or dirty info, plus the suggestions and info themselves. + @param db The database the function acts on. + @param outputFile The path to which the file shall be written. + @param overwrite If `false` and `outputFile` already exists, no data will be written. Otherwise, data will be written. + @returns A return code. + */ + LOOT_API unsigned int loot_write_minimal_list(loot_db db, const char * const outputFile, const bool overwrite); + ///@} #ifdef __cplusplus } From 4ef15273ac2c25431f3923073f8b15cd3e87845f Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 12:44:24 +0100 Subject: [PATCH 2/9] More API header formatting cleanup. Fixed a few bad formatting changes CodeMaid made, wrapped most of the code to 80 characters (not the error descriptions, I think it's easier to read them as-is), and tweaked function comments to make parameter documentation easier to read. --- src/api/api.h | 590 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 355 insertions(+), 235 deletions(-) diff --git a/src/api/api.h b/src/api/api.h index ef7cd61a..d024c3c6 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -23,27 +23,37 @@ */ /** - @file api.h - @brief This file contains the API frontend. - - @note The LOOT API is *not* thread safe. Thread safety is a goal, but one that has not yet been achieved. Bear this in mind if using it in a multi-threaded client. - - @section var_sec Variable Types - - The LOOT API uses character strings and integers for information input/output. - - All strings are null-terminated byte character strings encoded in UTF-8. - - All codes are unsigned integers at least 16 bits in size. - - All array sizes are unsigned integers at least 16 bits in size. - - File paths are case-sensitive if and only if the underlying file system is case-sensitive. - - @section memory_sec Memory Management - - The LOOT API manages the memory of strings and arrays it returns internally, so such strings and arrays should not be deallocated by the client. - - Data returned by a function lasts until a function is called which returns data of the same type (eg. a string is stored until the client calls another function which returns a string, an integer array lasts until another integer array is returned, etc.). - - All allocated memory is freed when loot_destroy_db() is called, except the string allocated by loot_get_error_message(), which must be freed by calling loot_cleanup(). - */ + * @file api.h + * @brief This file contains the API frontend. + * + * @note The LOOT API is *not* thread safe. Thread safety is a goal, but one + * that has not yet been achieved. Bear this in mind if using it in a + * multi-threaded client. + * + * @section var_sec Variable Types + * + * The LOOT API uses character strings and integers for information + * input/output. + * - All strings are null-terminated byte character strings encoded in UTF-8. + * - All codes are unsigned integers at least 16 bits in size. + * - All array sizes are unsigned integers at least 16 bits in size. + * - File paths are case-sensitive if and only if the underlying file system + * is case-sensitive. + * + * @section memory_sec Memory Management + * + * The LOOT API manages the memory of strings and arrays it returns, so such + * strings and arrays should not be deallocated by the client. + * + * Data returned by a function lasts until a function is called which returns + * data of the same type (eg. a string is stored until the client calls + * another function which returns a string, an integer array lasts until + * another integer array is returned, etc.). + * + * All allocated memory is freed when loot_destroy_db() is called, except the + * string allocated by loot_get_error_message(), which must be freed by + * calling loot_cleanup(). + */ #ifndef __LOOT_API_H__ #define __LOOT_API_H__ @@ -51,23 +61,23 @@ #include #if defined(_MSC_VER) -//MSVC doesn't support C99, so do the stdbool.h definitions ourselves. -//START OF stdbool.h DEFINITIONS. +/* MSVC doesn't support C99, so do the stdbool.h definitions ourselves. + START OF stdbool.h DEFINITIONS. */ # ifndef __cplusplus # define bool _Bool # define true 1 # define false 0 # endif # define __bool_true_false_are_defined 1 -//END OF stdbool.h DEFINITIONS. +/* END OF stdbool.h DEFINITIONS. */ #else # include #endif -// set up dll import/export decorators -// when compiling the dll on windows, ensure LOOT_EXPORT is defined. clients -// that use this header do not need to define anything to import the symbols -// properly. +/* set up dll import/export decorators + when compiling the dll on windows, ensure LOOT_EXPORT is defined. clients + that use this header do not need to define anything to import the symbols + properly. */ #if defined(_WIN32) || defined(_WIN64) # ifdef LOOT_STATIC # define LOOT_API @@ -85,230 +95,320 @@ extern "C" { #endif - //////////////////////// - // Types - //////////////////////// + /**********************************************************************//** + * Types + *************************************************************************/ /** - @brief A structure that holds all game-specific data used by the LOOT API. - @details Used to keep each game's data independent. Abstracts the definition of the API's internal state while still providing type safety across the library. Multiple handles can also be made for each game, though it should be kept in mind that the API is not thread-safe. - */ + * @brief A structure that holds all game-specific data used by the API. + * @details Used to keep each game's data independent. Abstracts the + * definition of the API's internal state while still providing + * type safety across the library. Multiple handles can also be + * made for each game, though it should be kept in mind that the + * API is not thread-safe. + */ typedef struct _loot_db_int * loot_db; /** - @brief A structure that holds the type of a message and the message string itself. - @var loot_message::type The type of the message, specified using one of the message type codes given below. - @var loot_message::message The message string itself. - */ + * @brief A structure that holds the type of a message and the message + * string itself. + * @var loot_message::type + * The type of the message, specified using one of the message type + * codes given below. + * @var loot_message::message + * The message string itself. + */ typedef struct { unsigned int type; const char * message; } loot_message; - /*********************//** - @name Return Codes - @brief Error codes signify an issue that caused a function to exit prematurely. If a function exits prematurely, a reversal of any changes made during its execution is attempted before it exits. - *************************/ - ///@{ - LOOT_API extern const unsigned int loot_ok; ///< The function completed successfully. - LOOT_API extern const unsigned int loot_error_liblo_error; ///< There was an error in performing a load order operation. - LOOT_API extern const unsigned int loot_error_file_write_fail; ///< A file could not be written to. - LOOT_API extern const unsigned int loot_error_parse_fail; ///< There was an error parsing the file. - LOOT_API extern const unsigned int loot_error_condition_eval_fail; ///< There was an error evaluating the conditionals in a metadata file. - LOOT_API extern const unsigned int loot_error_regex_eval_fail; ///< There was an error evaluating the regular expressions in a metadata file. - LOOT_API extern const unsigned int loot_error_no_mem; ///< The API was unable to allocate the required memory. - LOOT_API extern const unsigned int loot_error_invalid_args; ///< Invalid arguments were given for the function. - LOOT_API extern const unsigned int loot_error_no_tag_map; ///< No Bash Tag map has been generated yet. - LOOT_API extern const unsigned int loot_error_path_not_found; ///< A file or folder path could not be found. - LOOT_API extern const unsigned int loot_error_no_game_detected; ///< The given game could not be found. - LOOT_API extern const unsigned int loot_error_windows_error; ///< An error occurred during a call to the Windows API. - LOOT_API extern const unsigned int loot_error_sorting_error; ///< An error occurred while sorting plugins. + /**********************************************************************//** + * @name Return Codes + * @brief Error codes signify an issue that caused a function to exit + * prematurely. If a function exits prematurely, a reversal of any + * changes made during its execution is attempted before it exits. + *************************************************************************/ + /**@{*/ + + LOOT_API extern const unsigned int loot_ok; /**< The function completed successfully. */ + LOOT_API extern const unsigned int loot_error_liblo_error; /**< There was an error in performing a load order operation. */ + LOOT_API extern const unsigned int loot_error_file_write_fail; /**< A file could not be written to. */ + LOOT_API extern const unsigned int loot_error_parse_fail; /**< There was an error parsing the file. */ + LOOT_API extern const unsigned int loot_error_condition_eval_fail; /**< There was an error evaluating the conditionals in a metadata file. */ + LOOT_API extern const unsigned int loot_error_regex_eval_fail; /**< There was an error evaluating the regular expressions in a metadata file. */ + LOOT_API extern const unsigned int loot_error_no_mem; /**< The API was unable to allocate the required memory. */ + LOOT_API extern const unsigned int loot_error_invalid_args; /**< Invalid arguments were given for the function. */ + LOOT_API extern const unsigned int loot_error_no_tag_map; /**< No Bash Tag map has been generated yet. */ + LOOT_API extern const unsigned int loot_error_path_not_found; /**< A file or folder path could not be found. */ + LOOT_API extern const unsigned int loot_error_no_game_detected; /**< The given game could not be found. */ + LOOT_API extern const unsigned int loot_error_windows_error; /**< An error occurred during a call to the Windows API. */ + LOOT_API extern const unsigned int loot_error_sorting_error; /**< An error occurred while sorting plugins. */ /** - @brief Matches the value of the highest-numbered return code. - @details Provided in case clients wish to incorporate additional return codes in their implementation and desire some method of avoiding value conflicts. - */ + * @brief Matches the value of the highest-numbered return code. + * @details Provided in case clients wish to incorporate additional return + * codes in their implementation and desire some method of + * avoiding value conflicts. + */ LOOT_API extern const unsigned int loot_return_max; - ///@} + /**@}*/ + /**********************************************************************//** + * @name Game Codes + * @brief Used with loot_create_db(). + *************************************************************************/ + /**@{*/ - /*******************//** - @name Game Codes - @brief Used with loot_create_db(). - ***********************/ - ///@{ - LOOT_API extern const unsigned int loot_game_tes4; ///< Game code for The Elder Scrolls IV: Oblivion. - LOOT_API extern const unsigned int loot_game_tes5; ///< Game code for The Elder Scrolls V: Skyrim. - LOOT_API extern const unsigned int loot_game_fo3; ///< Game code for Fallout 3. - LOOT_API extern const unsigned int loot_game_fonv; ///< Game code for Fallout: New Vegas. + LOOT_API extern const unsigned int loot_game_tes4; /**< Game code for The Elder Scrolls IV: Oblivion. */ + LOOT_API extern const unsigned int loot_game_tes5; /**< Game code for The Elder Scrolls V: Skyrim. */ + LOOT_API extern const unsigned int loot_game_fo3; /**< Game code for Fallout 3. */ + LOOT_API extern const unsigned int loot_game_fonv; /**< Game code for Fallout: New Vegas. */ - ///@} + /**@}*/ + /**********************************************************************//** + * @name Message Type Codes + * @brief Used with the loot_message structure. + *************************************************************************/ + /**@{*/ - /***************************//** - @name Message Type Codes - @brief Used with the loot_message structure. - *******************************/ - ///@{ - LOOT_API extern const unsigned int loot_message_say; ///< Denotes a generic note-type message. - LOOT_API extern const unsigned int loot_message_warn; ///< Denotes a warning message. - LOOT_API extern const unsigned int loot_message_error; ///< Denotes an error message. + LOOT_API extern const unsigned int loot_message_say; /**< Denotes a generic note-type message. */ + LOOT_API extern const unsigned int loot_message_warn; /**< Denotes a warning message. */ + LOOT_API extern const unsigned int loot_message_error; /**< Denotes an error message. */ /** - @brief Denites a Bash Tag suggestion message. - @details This type should never be seen client-side as it is only used during conversion between internal Bash Tag and message structures, but it is provided just in case. - */ + * @brief Denites a Bash Tag suggestion message. + * @details This type should never be seen client-side as it is only used + * during conversion between internal Bash Tag and message + * structures, but it is provided just in case. + */ LOOT_API extern const unsigned int loot_message_tag; - ///@} + /**@}*/ + /**********************************************************************//** + * @name Message Language Codes + * @brief Used with loot_eval_lists(). + *************************************************************************/ + /**@{*/ - /*******************************//** - @name Message Language Codes - @brief Used with loot_eval_lists(). - ***********************************/ - ///@{ - LOOT_API extern const unsigned int loot_lang_any; ///< Tells the API to select messages of any language. - LOOT_API extern const unsigned int loot_lang_english; ///< Tells the API to preferentially select English messages. - LOOT_API extern const unsigned int loot_lang_spanish; ///< Tells the API to preferentially select Spanish messages. - LOOT_API extern const unsigned int loot_lang_russian; ///< Tells the API to preferentially select Russian messages. - LOOT_API extern const unsigned int loot_lang_french; ///< Tells the API to preferentially select French messages. - LOOT_API extern const unsigned int loot_lang_chinese; ///< Tells the API to preferentially select Chinese messages. - LOOT_API extern const unsigned int loot_lang_polish; ///< Tells the API to preferentially select Polish messages. - LOOT_API extern const unsigned int loot_lang_brazilian_portuguese; ///< Tells the API to preferentially select Brazilian Portuguese messages. - LOOT_API extern const unsigned int loot_lang_finnish; ///< Tells the API to preferentially select Finnish messages. - LOOT_API extern const unsigned int loot_lang_german; ///< Tells the API to preferentially select German messages. - ///@} + LOOT_API extern const unsigned int loot_lang_any; /**< Tells the API to select messages of any language. */ + LOOT_API extern const unsigned int loot_lang_english; /**< Tells the API to preferentially select English messages. */ + LOOT_API extern const unsigned int loot_lang_spanish; /**< Tells the API to preferentially select Spanish messages */ + LOOT_API extern const unsigned int loot_lang_russian; /**< Tells the API to preferentially select Russian messages. */ + LOOT_API extern const unsigned int loot_lang_french; /**< Tells the API to preferentially select French messages. */ + LOOT_API extern const unsigned int loot_lang_chinese; /**< Tells the API to preferentially select Chinese messages. */ + LOOT_API extern const unsigned int loot_lang_polish; /**< Tells the API to preferentially select Polish messages. */ + LOOT_API extern const unsigned int loot_lang_brazilian_portuguese; /**< Tells the API to preferentially select Brazilian Portuguese messages. */ + LOOT_API extern const unsigned int loot_lang_finnish; /**< Tells the API to preferentially select Finnish messages. */ + LOOT_API extern const unsigned int loot_lang_german; /**< Tells the API to preferentially select German messages. */ - /*********************************//** - @name Plugin Cleanliness Codes - @brief Used with loot_get_dirty_message(). - *************************************/ - ///@{ - LOOT_API extern const unsigned int loot_needs_cleaning_no; ///< Denotes that the plugin queried does not need cleaning. - LOOT_API extern const unsigned int loot_needs_cleaning_yes; ///< Denotes that the plugin queried needs cleaning. - LOOT_API extern const unsigned int loot_needs_cleaning_unknown; ///< Denotes that the API is unable to determine whether or not the plugin queried needs cleaning. + /**@}*/ + /**********************************************************************//** + * @name Plugin Cleanliness Codes + * @brief Used with loot_get_dirty_message(). + *************************************************************************/ + /**@{*/ - ///@} + LOOT_API extern const unsigned int loot_needs_cleaning_no; /**< Denotes that the plugin queried does not need cleaning. */ + LOOT_API extern const unsigned int loot_needs_cleaning_yes; /**< Denotes that the plugin queried needs cleaning. */ + LOOT_API extern const unsigned int loot_needs_cleaning_unknown; /**< Denotes that the API is unable to determine whether or not the plugin queried needs cleaning. */ + + /**@}*/ + /**********************************************************************//** + * @name Error Handling Functions + *************************************************************************/ + /**@{*/ - /*********************************//** - @name Error Handling Functions - *************************************/ - ///@{ /** - @brief Returns the message for the last error or warning encountered. - @details Outputs a string giving the a message containing the details of the last error or warning encountered by a function. Each time this function is called, the memory for the previous message is freed, so only one error message is available at any one time. - @param details A pointer to the error details string outputted by the function. - @returns A return code. - */ + * @brief Returns the message for the last error or warning encountered. + * @details Outputs a string giving the a message containing the details + * of the last error or warning encountered by a function. Each + * time this function is called, the memory for the previous + * message is freed, so only one error message is available at + * any one time. + * @param details + * A pointer to the error details string outputted by the function. + * @returns A return code. + */ LOOT_API unsigned int loot_get_error_message(const char ** const message); /** - @brief Frees the memory allocated to the last error details string. - */ - LOOT_API void loot_cleanup(); + * @brief Frees the memory allocated to the last error details string. + */ + LOOT_API void loot_cleanup(); - ///@} - - /**************************//** - @name Version Functions - ******************************/ - ///@{ - /** - @brief Checks for API compatibility. - @details Checks whether the loaded API is compatible with the given version of the API, abstracting API stability policy away from clients. The version numbering used is major.minor.patch. - @param versionMajor The major version number to check. - @param versionMinor The minor version number to check. - @param versionPatch The patch version number to check. - @returns True if the API versions are compatible, false otherwise. - */ - LOOT_API bool loot_is_compatible(const unsigned int versionMajor, const unsigned int versionMinor, const unsigned int versionPatch); + /**@}*/ + /**********************************************************************//** + * @name Version Functions + *************************************************************************/ + /**@{*/ /** - @brief Gets the API version. - @details Outputs the major, minor and patch version numbers for the loaded API. The version numbering used is major.minor.patch. - @param versionMajor A pointer to the major version number. - @param versionMinor A pointer to the minor version number. - @param versionPatch A pointer to the patch version number. - */ - LOOT_API unsigned int loot_get_version(unsigned int * const versionMajor, unsigned int * const versionMinor, unsigned int * const versionPatch); - - ///@} - - /***************************************//** - @name Lifecycle Management Functions - *******************************************/ - ///@{ - /** - @brief Initialise a new database handle. - @details Creates a handle for a database, which is then used by all database functions. - @param db A pointer to the handle that is created by the function. - @param gameId A game code specifying which game to create the handle for. - @param gamePath The relative or absolute path to the game folder, ot `NULL`. If `NULL`, the API will attempt to detect the data path of the specified game. - @returns A return code. - */ - LOOT_API unsigned int loot_create_db(loot_db * const db, const unsigned int clientGame, const char * const gamePath); + * @brief Checks for API compatibility. + * @details Checks whether the loaded API is compatible with the given + * version of the API, abstracting API stability policy away from + * clients. The version numbering used is major.minor.patch. + * @param versionMajor + * The major version number to check. + * @param versionMinor + * The minor version number to check. + * @param versionPatch + * The patch version number to check. + * @returns True if the API versions are compatible, false otherwise. + */ + LOOT_API bool loot_is_compatible(const unsigned int versionMajor, + const unsigned int versionMinor, + const unsigned int versionPatch); /** - @brief Destroy an existing database handle. - @details Destroys the given database handle, freeing up memory allocated during its use, excluding any memory allocated to error messages. - @param db The database handle to destroy. - */ - LOOT_API void loot_destroy_db(loot_db db); + * @brief Gets the API version. + * @details Outputs the major, minor and patch version numbers for the + * loaded API. The version numbering used is major.minor.patch. + * @param versionMajor + * A pointer to the major version number. + * @param versionMinor + * A pointer to the minor version number. + * @param versionPatch + * A pointer to the patch version number. + */ + LOOT_API unsigned int loot_get_version(unsigned int * const versionMajor, + unsigned int * const versionMinor, + unsigned int * const versionPatch); - ///@} + /**@}*/ + /**********************************************************************//** + * @name Lifecycle Management Functions + *************************************************************************/ + /**@{*/ - /***********************************//** - @name Database Loading Functions - ***************************************/ - ///@{ /** - @brief Loads the masterlist and userlist from the paths specified. - @details Can be called multiple times, each time replacing the previously-loaded data. - @param db The database the function acts on. - @param masterlistPath A string containing the relative or absolute path to the masterlist file that should be loaded. - @param userlistPath A string containing the relative or absolute path to the userlist file that should be loaded, or `NULL`. If `NULL`, no userlist will be loaded. - @returns A return code. - */ - LOOT_API unsigned int loot_load_lists(loot_db db, const char * const masterlistPath, + * @brief Initialise a new database handle. + * @details Creates a handle for a database, which is then used by all + * database functions. + * @param db + * A pointer to the handle that is created by the function. + * @param gameId + * A game code for which to create the handle. + * @param gamePath + * The relative or absolute path to the game folder, or `NULL`. + * If `NULL`, the API will attempt to detect the data path of the + * specified game. + * @returns A return code. + */ + LOOT_API unsigned int loot_create_db(loot_db * const db, + const unsigned int clientGame, + const char * const gamePath); + + /** + * @brief Destroy an existing database handle. + * @details Destroys the given database handle, freeing up memory + * allocated during its use, excluding any memory allocated to + * error messages. + * @param db + * The database handle to destroy. + */ + LOOT_API void loot_destroy_db(loot_db db); + + /**@}*/ + /**********************************************************************//** + * @name Database Loading Functions + *************************************************************************/ + /**@{*/ + + /** + * @brief Loads the masterlist and userlist from the paths specified. + * @details Can be called multiple times, each time replacing the + * previously-loaded data. + * @param db + * The database the function acts on. + * @param masterlistPath + * A string containing the relative or absolute path to the masterlist + * file that should be loaded. + * @param userlistPath + * A string containing the relative or absolute path to the userlist + * file that should be loaded, or `NULL`. If `NULL`, no userlist will + * be loaded. + * @returns A return code. + */ + LOOT_API unsigned int loot_load_lists(loot_db db, + const char * const masterlistPath, const char * const userlistPath); /** - @brief Evaluates all conditions and regular expression metadata entries. - @details Repeated calls re-evaluate the metadata from scratch. This function affects the output of all the database access functions. - @param db The database the function acts on. - @param language The language code that is used for message language comparisons. - @returns A return code. - */ - LOOT_API unsigned int loot_eval_lists(loot_db db, const unsigned int language); + * @brief Evaluates all conditions and regular expression metadata + * entries. + * @details Repeated calls re-evaluate the metadata from scratch. This + * function affects the output of all the database access + * functions. + * @param db + * The database the function acts on. + * @param language + * The language code that is used for message language comparisons. + * @returns A return code. + */ + LOOT_API unsigned int loot_eval_lists(loot_db db, + const unsigned int language); - ///@} - - /**********************************//** - @name Database Access Functions - **************************************/ - ///@{ - /** - @brief Outputs an array of the Bash Tags that are suggested in the database. - @details This function must be called prior to calling loot_get_plugin_tags() to ensure that the latter can return the Tags using the correct array indicies. - @param db The database the function acts on. - @param tagMap A pointer to the outputted array of Bash Tags. The array functions as a map where the indicies are the keys, allowing the API to use them as UIDs for Bash Tags instead of passing their names as strings every time loot_get_plugin_tags() is called. If no Bash Tags are suggested, this will be `NULL`. - @param numTags A pointer to the size of the outputted array. If no Bash Tags are suggested, this will be `0`. - @returns A return code. - */ - LOOT_API unsigned int loot_get_tag_map(loot_db db, char *** const tagMap, size_t * const numTags); + /**@}*/ + /**********************************************************************//** + * @name Database Access Functions + *************************************************************************/ + /**@{*/ /** - @brief Outputs the Bash Tags suggested for addition and removal by the database for the given plugin. - @details loot_get_tag_map() must be called before this to ensure that the Bash Tag UIDs outputted by this function can be matched up to name strings. - @param db The database the function acts on. - @param plugin The filename of the plugin to look up Bash Tag suggestions for. - @param tags_added A pointer to the outputted array of UIDs of the Bash Tags suggested for addition to the specified plugin. `NULL` if no Bash Tag additions are suggested. - @param numTags_added A pointer to the size of the tags_added array. `0` if `tags_added` is `NULL`. - @param tags_removed A pointer to the outputted array of UIDs of the Bash Tags suggested for removal from the specified plugin. `NULL` if no Bash Tag removals are suggested. - @param numTags_removed A pointer to the size of the `tags_removed` array. `0` if `tags_removed` is `null`. - @param userlistModified `true` if the Bash Tag suggestions were modified by the data in the userlist, `false` otherwise. - @returns A return code. - */ - LOOT_API unsigned int loot_get_plugin_tags(loot_db db, const char * const plugin, + * @brief Outputs an array of the Bash Tags that are suggested in the + * database. + * @details This function must be called prior to calling + * loot_get_plugin_tags() to ensure that the latter can return + * the Tags using the correct array indicies. + * @param db + * The database the function acts on. + * @param tagMap + * A pointer to the outputted array of Bash Tags. The array functions + * as a map where the indicies are the keys, allowing the API to use + * them as UIDs for Bash Tags instead of passing their names as + * strings every time loot_get_plugin_tags() is called. If no Bash + * Tags are suggested, this will be `NULL`. + * @param numTags + * A pointer to the size of the outputted array. If no Bash Tags are + * suggested, this will be `0`. + * @returns A return code. + */ + LOOT_API unsigned int loot_get_tag_map(loot_db db, + char *** const tagMap, + size_t * const numTags); + + /** + * @brief Outputs the Bash Tags suggested for addition and removal by the + * database for the given plugin. + * @details loot_get_tag_map() must be called before this to ensure that + * the Bash Tag UIDs outputted by this function can be matched up + * to name strings. + * @param db + * The database the function acts on. + * @param plugin + * The filename of the plugin to look up Bash Tag suggestions for. + * @param tags_added + * A pointer to the outputted array of UIDs of the Bash Tags suggested + * for addition to the specified plugin. `NULL` if no Bash Tag + * additions are suggested. + * @param numTags_added + * A pointer to the size of the tags_added array. `0` if `tags_added` + * is `NULL`. + * @param tags_removed + * A pointer to the outputted array of UIDs of the Bash Tags suggested + * for removal from the specified plugin. `NULL` if no Bash Tag + * removals are suggested. + * @param numTags_removed + * A pointer to the size of the `tags_removed` array. `0` if + * `tags_removed` is `null`. + * @param userlistModified + * `true` if the Bash Tag suggestions were modified by the data in the + * userlist, `false` otherwise. + * @returns A return code. + */ + LOOT_API unsigned int loot_get_plugin_tags(loot_db db, + const char * const plugin, unsigned int ** const tags_added, size_t * const numTags_added, unsigned int ** const tags_removed, @@ -316,40 +416,60 @@ extern "C" bool * const userlistModified); /** - @brief Outputs the messages associated with the given plugin in the database. - @param db The database the function acts on. - @param plugin The filename of the plugin to look up messages for. - @param messages A pointer to the outputted array of messages associated with the specified plugin, given as loot_message structures. `NULL` if the plugin has no messages associated with it. - @param numMessages A pointer to the size of the outputted array. If no messages are outputted, this will be `0`. - @returns A return code. - */ - LOOT_API unsigned int loot_get_plugin_messages(loot_db db, const char * const plugin, + * @brief Outputs the messages associated with the given plugin in the + * database. + * @param db + * The database the function acts on. + * @param plugin + * The filename of the plugin to look up messages for. + * @param messages + * A pointer to the outputted array of messages associated with the + * specified plugin, given as loot_message structures. `NULL` if the + * plugin has no messages associated with it. + * @param numMessages + * A pointer to the size of the outputted array. If no messages are + * outputted, this will be `0`. + * @returns A return code. + */ + LOOT_API unsigned int loot_get_plugin_messages(loot_db db, + const char * const plugin, loot_message ** const messages, size_t * const numMessages); /** - @brief Determines the database's knowledge of a plugin's dirtiness. - - @details Outputs whether the plugin should be cleaned or not, or if no data is available. - @param db The database the function acts on. - @param plugin The plugin to look up dirty status information for. - @param needsCleaning A pointer to a plugin cleanliness code. - @returns A return code. - */ - - LOOT_API unsigned int loot_get_dirty_info(loot_db db, const char * const plugin, + * @brief Determines the database's knowledge of a plugin's dirtiness. + * @details Outputs whether the plugin should be cleaned or not, or if + * no data is available. + * @param db + * The database the function acts on. + * @param plugin + * The plugin to look up dirty status information for. + * @param needsCleaning + * A pointer to a plugin cleanliness code. + * @returns A return code. + */ + LOOT_API unsigned int loot_get_dirty_info(loot_db db, + const char * const plugin, unsigned int * const needsCleaning); /** - @brief Writes a minimal metadata file that only contains plugins with Bash Tag suggestions and/or dirty info, plus the suggestions and info themselves. - @param db The database the function acts on. - @param outputFile The path to which the file shall be written. - @param overwrite If `false` and `outputFile` already exists, no data will be written. Otherwise, data will be written. - @returns A return code. - */ - LOOT_API unsigned int loot_write_minimal_list(loot_db db, const char * const outputFile, const bool overwrite); + * @brief Writes a minimal metadata file that only contains plugins with + * Bash Tag suggestions and/or dirty info, plus the suggestions and + * info themselves. + * @param db + * The database the function acts on. + * @param outputFile + * The path to which the file shall be written. + * @param overwrite + * If `false` and `outputFile` already exists, no data will be + * written. Otherwise, data will be written. + * @returns A return code. + */ + LOOT_API unsigned int loot_write_minimal_list(loot_db db, + const char * const outputFile, + const bool overwrite); - ///@} + /**@}*/ #ifdef __cplusplus } From 8256420bb8245b03731f20b3112a9a8d7b7d9861 Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 12:52:01 +0100 Subject: [PATCH 3/9] Removed Message::tag. Also hosed pretty assignment block indents. Thanks, CodeMaid! >:| I can't figure out how not to make it do that, the extension is too useful otherwise though. --- src/api/api.cpp | 87 +++++++++++++++++++++--------------------- src/api/api.h | 8 ---- src/backend/metadata.h | 10 ++--- 3 files changed, 47 insertions(+), 58 deletions(-) diff --git a/src/api/api.cpp b/src/api/api.cpp index 59000490..d356e00d 100644 --- a/src/api/api.cpp +++ b/src/api/api.cpp @@ -44,49 +44,48 @@ #include #include -const unsigned int loot_ok = loot::error::ok; -const unsigned int loot_error_liblo_error = loot::error::liblo_error; -const unsigned int loot_error_file_write_fail = loot::error::path_write_fail; -const unsigned int loot_error_parse_fail = loot::error::path_read_fail; -const unsigned int loot_error_condition_eval_fail = loot::error::condition_eval_fail; -const unsigned int loot_error_regex_eval_fail = loot::error::regex_eval_fail; -const unsigned int loot_error_no_mem = loot::error::no_mem; -const unsigned int loot_error_invalid_args = loot::error::invalid_args; -const unsigned int loot_error_no_tag_map = loot::error::no_tag_map; -const unsigned int loot_error_path_not_found = loot::error::path_not_found; -const unsigned int loot_error_no_game_detected = loot::error::no_game_detected; -const unsigned int loot_error_windows_error = loot::error::windows_error; -const unsigned int loot_error_sorting_error = loot::error::sorting_error; -const unsigned int loot_return_max = loot_error_sorting_error; +const unsigned int loot_ok = loot::error::ok; +const unsigned int loot_error_liblo_error = loot::error::liblo_error; +const unsigned int loot_error_file_write_fail = loot::error::path_write_fail; +const unsigned int loot_error_parse_fail = loot::error::path_read_fail; +const unsigned int loot_error_condition_eval_fail = loot::error::condition_eval_fail; +const unsigned int loot_error_regex_eval_fail = loot::error::regex_eval_fail; +const unsigned int loot_error_no_mem = loot::error::no_mem; +const unsigned int loot_error_invalid_args = loot::error::invalid_args; +const unsigned int loot_error_no_tag_map = loot::error::no_tag_map; +const unsigned int loot_error_path_not_found = loot::error::path_not_found; +const unsigned int loot_error_no_game_detected = loot::error::no_game_detected; +const unsigned int loot_error_windows_error = loot::error::windows_error; +const unsigned int loot_error_sorting_error = loot::error::sorting_error; +const unsigned int loot_return_max = loot_error_sorting_error; // The following are the games identifiers used by the API. -const unsigned int loot_game_tes4 = loot::Game::tes4; -const unsigned int loot_game_tes5 = loot::Game::tes5; -const unsigned int loot_game_fo3 = loot::Game::fo3; -const unsigned int loot_game_fonv = loot::Game::fonv; +const unsigned int loot_game_tes4 = loot::Game::tes4; +const unsigned int loot_game_tes5 = loot::Game::tes5; +const unsigned int loot_game_fo3 = loot::Game::fo3; +const unsigned int loot_game_fonv = loot::Game::fonv; // LOOT message types. -const unsigned int loot_message_say = loot::Message::say; -const unsigned int loot_message_warn = loot::Message::warn; -const unsigned int loot_message_error = loot::Message::error; -const unsigned int loot_message_tag = loot::Message::tag; +const unsigned int loot_message_say = loot::Message::say; +const unsigned int loot_message_warn = loot::Message::warn; +const unsigned int loot_message_error = loot::Message::error; // LOOT message languages. -const unsigned int loot_lang_any = loot::Language::any; -const unsigned int loot_lang_english = loot::Language::english; -const unsigned int loot_lang_spanish = loot::Language::spanish; -const unsigned int loot_lang_russian = loot::Language::russian; -const unsigned int loot_lang_french = loot::Language::french; -const unsigned int loot_lang_chinese = loot::Language::chinese; -const unsigned int loot_lang_polish = loot::Language::polish; -const unsigned int loot_lang_brazilian_portuguese = loot::Language::brazilian_portuguese; -const unsigned int loot_lang_finnish = loot::Language::finnish; -const unsigned int loot_lang_german = loot::Language::german; +const unsigned int loot_lang_any = loot::Language::any; +const unsigned int loot_lang_english = loot::Language::english; +const unsigned int loot_lang_spanish = loot::Language::spanish; +const unsigned int loot_lang_russian = loot::Language::russian; +const unsigned int loot_lang_french = loot::Language::french; +const unsigned int loot_lang_chinese = loot::Language::chinese; +const unsigned int loot_lang_polish = loot::Language::polish; +const unsigned int loot_lang_brazilian_portuguese = loot::Language::brazilian_portuguese; +const unsigned int loot_lang_finnish = loot::Language::finnish; +const unsigned int loot_lang_german = loot::Language::german; // LOOT cleanliness codes. -const unsigned int loot_needs_cleaning_no = 0; -const unsigned int loot_needs_cleaning_yes = 1; -const unsigned int loot_needs_cleaning_unknown = 2; +const unsigned int loot_needs_cleaning_no = 0; +const unsigned int loot_needs_cleaning_yes = 1; +const unsigned int loot_needs_cleaning_unknown = 2; struct _loot_db_int : public loot::Game { _loot_db_int(const unsigned int clientGame, const std::string gamePath) @@ -104,13 +103,13 @@ struct _loot_db_int : public loot::Game { delete[] extRemovedTagIds; if (extTagMap != nullptr) { - for (size_t i=0; i < bashTagMap.size(); i++) + for (size_t i = 0; i < bashTagMap.size(); i++) delete[] extTagMap[i]; //Gotta clear those allocated strings. delete[] extTagMap; } if (extMessageArray != nullptr) { - for (size_t i=0; i < extMessageArraySize; i++) + for (size_t i = 0; i < extMessageArraySize; i++) delete[] extMessageArray[i].message; //Gotta clear those allocated strings. delete[] extMessageArray; } @@ -242,7 +241,7 @@ LOOT_API unsigned int loot_create_db(loot_db * const db, const unsigned int clie if (gamePath != nullptr) game_path = gamePath; - loot_db retVal ={ 0 }; + loot_db retVal = {0}; try { retVal = new _loot_db_int(clientGame, game_path); } @@ -305,13 +304,13 @@ LOOT_API unsigned int loot_load_lists(loot_db db, const char * const masterlistP delete[] db->extRemovedTagIds; if (db->extTagMap != nullptr) { - for (size_t i=0; i < db->bashTagMap.size(); i++) + for (size_t i = 0; i < db->bashTagMap.size(); i++) delete[] db->extTagMap[i]; //Gotta clear those allocated strings. delete[] db->extTagMap; } if (db->extMessageArray != nullptr) { - for (size_t i=0; i < db->extMessageArraySize; i++) + for (size_t i = 0; i < db->extMessageArraySize; i++) delete[] db->extMessageArray[i].message; //Gotta clear those allocated strings. delete[] db->extMessageArray; } @@ -373,7 +372,7 @@ LOOT_API unsigned int loot_get_tag_map(loot_db db, char *** const tagMap, size_t //Clear existing array allocation. if (db->extTagMap != nullptr) { - for (size_t i=0, max=db->bashTagMap.size(); i < max; ++i) { + for (size_t i = 0, max = db->bashTagMap.size(); i < max; ++i) { delete[] db->extTagMap[i]; } delete[] db->extTagMap; @@ -501,12 +500,12 @@ LOOT_API unsigned int loot_get_plugin_tags(loot_db db, const char * const plugin try { if (numAdded != 0) { db->extAddedTagIds = new uint32_t[numAdded]; - for (size_t i=0; i < numAdded; i++) + for (size_t i = 0; i < numAdded; i++) db->extAddedTagIds[i] = tagsAddedIDs[i]; } if (numRemoved != 0) { db->extRemovedTagIds = new uint32_t[numRemoved]; - for (size_t i=0; i < numRemoved; i++) + for (size_t i = 0; i < numRemoved; i++) db->extRemovedTagIds[i] = tagsRemovedIDs[i]; } } @@ -534,7 +533,7 @@ LOOT_API unsigned int loot_get_plugin_messages(loot_db db, const char * const pl //Clear existing array allocation. if (db->extMessageArray != nullptr) { - for (size_t i=0; i < db->extMessageArraySize; ++i) { + for (size_t i = 0; i < db->extMessageArraySize; ++i) { delete[] db->extMessageArray[i].message; } delete[] db->extMessageArray; diff --git a/src/api/api.h b/src/api/api.h index d024c3c6..fd508956 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -176,14 +176,6 @@ extern "C" LOOT_API extern const unsigned int loot_message_warn; /**< Denotes a warning message. */ LOOT_API extern const unsigned int loot_message_error; /**< Denotes an error message. */ - /** - * @brief Denites a Bash Tag suggestion message. - * @details This type should never be seen client-side as it is only used - * during conversion between internal Bash Tag and message - * structures, but it is provided just in case. - */ - LOOT_API extern const unsigned int loot_message_tag; - /**@}*/ /**********************************************************************//** * @name Message Language Codes diff --git a/src/backend/metadata.h b/src/backend/metadata.h index 03efa274..95de1d7f 100644 --- a/src/backend/metadata.h +++ b/src/backend/metadata.h @@ -20,7 +20,7 @@ You should have received a copy of the GNU General Public License along with LOOT. If not, see . -*/ + */ #ifndef __LOOT_METADATA__ #define __LOOT_METADATA__ @@ -35,7 +35,6 @@ #include namespace loot { - const unsigned int max_priority = 1000000; class Game; @@ -123,10 +122,9 @@ namespace loot { std::vector Content() const; MessageContent ChooseContent(const unsigned int language) const; - static const unsigned int say = 0; - static const unsigned int warn = 1; + static const unsigned int say = 0; + static const unsigned int warn = 1; static const unsigned int error = 2; - static const unsigned int tag = 3; private: unsigned int _type; std::vector _content; @@ -136,7 +134,7 @@ namespace loot { public: File(); File(const std::string& name, const std::string& display = "", - const std::string& condition = ""); + const std::string& condition = ""); bool operator < (const File& rhs) const; bool operator == (const File& rhs) const; From 572cc084a5e056417651b6b13037113586e3bd44 Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 16:11:38 +0100 Subject: [PATCH 4/9] Improved some masterlist update error messages. Also CodeMaid tidied up a few initialisers. --- src/backend/git.cpp | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/backend/git.cpp b/src/backend/git.cpp index 28ec18a4..5a3e537c 100644 --- a/src/backend/git.cpp +++ b/src/backend/git.cpp @@ -42,7 +42,7 @@ namespace lc = boost::locale; namespace loot { struct git_handler { public: - git_handler() : repo(nullptr), remote(nullptr), cfg(nullptr), obj(nullptr), commit(nullptr), ref(nullptr), ref2(nullptr), sig(nullptr), blob(nullptr), merge_head(nullptr), tree(nullptr), diff(nullptr), buf({ 0 }) {} + git_handler() : repo(nullptr), remote(nullptr), cfg(nullptr), obj(nullptr), commit(nullptr), ref(nullptr), ref2(nullptr), sig(nullptr), blob(nullptr), merge_head(nullptr), tree(nullptr), diff(nullptr), buf({0}) {} ~git_handler() { git_commit_free(commit); @@ -183,7 +183,7 @@ namespace loot { git.call(git_signature_new(&git.sig, "LOOT", "loot@placeholder.net", 0, 0)); BOOST_LOG_TRIVIAL(debug) << "Setting up checkout options."; - char * paths[] ={ "masterlist.yaml" }; + char * paths[] = {"masterlist.yaml"}; git_checkout_options checkout_opts = GIT_CHECKOUT_OPTIONS_INIT; checkout_opts.checkout_strategy = GIT_CHECKOUT_FORCE; checkout_opts.paths.strings = paths; @@ -250,7 +250,7 @@ namespace loot { } else { // Repository exists: check settings are correct, then pull updates. - git.ui_message = "An error occurred while trying to access the local masterlist repository. If this error happens again, try deleting the \".git\" folder in \"%LOCALAPPDATA%\\LOOT\\" + game.FolderName() + "\"."; + git.ui_message = "An error occurred while trying to access the local masterlist repository. If this error happens again, try deleting the \".git\" folder in " + repo_path.string() + "."; // Open the repository. BOOST_LOG_TRIVIAL(info) << "Existing repository found, attempting to open it."; @@ -283,7 +283,7 @@ namespace loot { BOOST_LOG_TRIVIAL(info) << "Received " << stats->indexed_objects << " of " << stats->total_objects << " objects in " << stats->received_bytes << " bytes."; // Check that a branch with the correct name exists. - git.ui_message = "An error occurred while trying to access the local masterlist repository. If this error happens again, try deleting the \".git\" folder in \"%LOCALAPPDATA%\\LOOT\\" + game.FolderName() + "\"."; + git.ui_message = "An error occurred while trying to access the local masterlist repository. If this error happens again, try deleting the \".git\" folder in " + repo_path.string() + "\"."; int ret = git_branch_lookup(&git.ref, git.repo, repo_branch.c_str(), GIT_BRANCH_LOCAL); if (ret == GIT_ENOTFOUND) { // Branch doesn't exist. Create a new branch using the remote branch's latest commit. @@ -383,7 +383,7 @@ namespace loot { bool parsingFailed = false; std::string parsingError; - git.ui_message = "An error occurred while trying to read information on the updated masterlist. If this error happens again, try deleting the \".git\" folder in \"%LOCALAPPDATA%\\LOOT\\" + game.FolderName() + "\"."; + git.ui_message = "An error occurred while trying to read information on the updated masterlist. If this error happens again, try deleting the \".git\" folder in " + repo_path.string() + "\"."; do { // Get some descriptive info about what was checked out. @@ -414,7 +414,7 @@ namespace loot { git.ref = nullptr; git.obj = nullptr; git.commit = nullptr; - git.buf ={ 0 }; + git.buf = {0}; //Now try parsing the masterlist. BOOST_LOG_TRIVIAL(debug) << "Testing masterlist parsing."; From b5cbcde216a2aec685f9a3dd0492ab8ca64b2eee Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 16:34:31 +0100 Subject: [PATCH 5/9] Added sorting and update functions to API header. As yet unimplemented. --- src/api/api.cpp | 32 +++++++++++++++ src/api/api.h | 106 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) diff --git a/src/api/api.cpp b/src/api/api.cpp index d356e00d..ffde700c 100644 --- a/src/api/api.cpp +++ b/src/api/api.cpp @@ -359,6 +359,38 @@ LOOT_API unsigned int loot_eval_lists(loot_db db, const unsigned int language) { return loot_ok; } +//////////////////////////////////// +// LOOT Functionality Functions +//////////////////////////////////// + +LOOT_API unsigned int loot_sort_plugins(loot_db db, + char *** const sortedPlugins, + size_t * numPlugins) { + return loot_ok; +} + +LOOT_API unsigned int loot_apply_load_order(loot_db db, + const char ** const loadOrder, + size_t numPlugins) { + return loot_ok; +} + +LOOT_API unsigned int loot_update_masterlist(loot_db db, + const char * const masterlistPath, + const char * const remoteURL, + const char * const remoteBranch, + bool * const updated) { + return loot_ok; +} + +LOOT_API unsigned int loot_get_masterlist_revision(const char * const masterlistPath, + const bool getShortID, + char ** const revisionID, + char ** const revisionDate, + bool * const isModified) { + return loot_ok; +} + ////////////////////////// // DB Access Functions ////////////////////////// diff --git a/src/api/api.h b/src/api/api.h index fd508956..5d68d4b9 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -341,6 +341,112 @@ extern "C" LOOT_API unsigned int loot_eval_lists(loot_db db, const unsigned int language); + /**********************************************************************//** + * @name LOOT Functionality Functions + *************************************************************************/ + /**@{*/ + + /** + * @brief Calculates a new load order for the game's installed plugins + * (including inactive plugins) and outputs the sorted order. + * @details Pulls metadata from the masterlist and userlist if they are + * loaded, and reads the contents of each plugin. No changes are + * applied to the load order used by the game. This function does + * not load or evaluate the masterlist or userlist. + * @param db + * The database the function acts on. + * @param sortedPlugins + * A pointer to an array of plugin filenames in their sorted load + * order. + * @param numPlugins + * A pointer to the size of the outputted array. + * @returns A return code. + */ + LOOT_API unsigned int loot_sort_plugins(loot_db db, + char *** const sortedPlugins, + size_t * numPlugins); + + /** + * @brief Applies the given load order. + * @param db + * The database the function acts on. + * @param loadOrder + * An array of plugin filenames in the load order to be set. + * @param numPlugins + * The size of the inputted array. + * @returns A return code. + */ + LOOT_API unsigned int loot_apply_load_order(loot_db db, + const char ** const loadOrder, + size_t numPlugins); + + /** + * @brief Update the given masterlist. + * @details Uses Git to update the given masterlist to a given remote. + * If the masterlist doesn't exist, this will create it. This + * function also initialises a Git repository in the given + * masterlist's parent folder. If the masterlist was not already + * up-to-date, it will be re-loaded, but not re-evaluated. + * + * If a Git repository is already present, it will be used to + * perform a diff-only update, but if for any reason a + * fast-forward merge update is not possible, the existing + * repository will be deleted and a new repository cloned from + * the given remote. + * @param db + * The database the function acts on. + * @param masterlistPath + * A string containing the relative or absolute path to the masterlist + * file that should be updated. + * @param remoteURL + * The URL of the remote from which to fetch updates. This can also be + * a relative or absolute path to a local repository. + * @param remoteBranch + * The branch of the remote from which to apply updates. + * @param updated + * `true` if the masterlist was updated. `false` if no update was + * necessary, ie. it was already up-to-date. If `true`, the masterlist + * will have been re-loaded, but will need to be re-evaluated + * separately. + * @returns A return code. + */ + LOOT_API unsigned int loot_update_masterlist(loot_db db, + const char * const masterlistPath, + const char * const remoteURL, + const char * const remoteBranch, + bool * const updated); + + /** + * @brief Get the given masterlist's revision. + * @details Getting a masterlist's revision is only possible if it is + * found inside a local Git repository. + * @param masterlistPath + * A string containing the relative or absolute path to the masterlist + * file that should be queried. + * @param getShortID + * If `true`, the shortest unique hexadecimal revision hash that is at + * least 7 characters long will be outputted. Otherwise, the full 40 + * character hash will be outputted. + * @param revisionID + * A pointer to a string containing the outputted revision hash for + * the masterlist. If the masterlist doesn't exist, or there is no Git + * repository at its location, this will be `NULL`. + * @param revisionDate + * A pointer to a string containing the ISO 8601 formatted revision + * date, ie. YYYY-MM-DD. If the masterlist doesn't exist, or there is + * no Git repository at its location, this will be `NULL`. + * @param isModified + * A pointer to a boolean that is `true` if the masterlist has been + * edited since the outputted revision, or `false` if it is at exactly + * the revision given. + * @returns A return code. + */ + LOOT_API unsigned int loot_get_masterlist_revision(const char * const masterlistPath, + const bool getShortID, + char ** const revisionID, + char ** const revisionDate, + bool * const isModified); + /**@}*/ /**********************************************************************//** * @name Database Access Functions From 6dcf00ed2950f7729c5548f064f78a765378bcc6 Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 16:49:28 +0100 Subject: [PATCH 6/9] Fixed some Doxygen errors. --- src/api/api.h | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/api/api.h b/src/api/api.h index 5d68d4b9..d3173aaa 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -111,14 +111,16 @@ extern "C" /** * @brief A structure that holds the type of a message and the message - * string itself. - * @var loot_message::type - * The type of the message, specified using one of the message type - * codes given below. - * @var loot_message::message - * The message string itself. + * string itself. */ typedef struct { + /** + * @var type + * The type of the message, specified using one of the message + * type codes. + * @var message + * The message string itself. + */ unsigned int type; const char * message; } loot_message; @@ -218,7 +220,7 @@ extern "C" * time this function is called, the memory for the previous * message is freed, so only one error message is available at * any one time. - * @param details + * @param message * A pointer to the error details string outputted by the function. * @returns A return code. */ @@ -279,7 +281,7 @@ extern "C" * database functions. * @param db * A pointer to the handle that is created by the function. - * @param gameId + * @param clientGame * A game code for which to create the handle. * @param gamePath * The relative or absolute path to the game folder, or `NULL`. From 4908f4d2808b9f5f56d669850badc329f8b05abd Mon Sep 17 00:00:00 2001 From: WrinklyNinja Date: Thu, 4 Sep 2014 17:32:49 +0100 Subject: [PATCH 7/9] Moved Doxygen index into API header. --- docs/Doxyfile | 3 +-- docs/api_index.dox | 18 ------------------ src/api/api.h | 40 +++++++++++++++++++++++++++++++++++++++- 3 files changed, 40 insertions(+), 21 deletions(-) delete mode 100644 docs/api_index.dox diff --git a/docs/Doxyfile b/docs/Doxyfile index 286fac13..da82cb3a 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -655,8 +655,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = ../src/api/api.h \ - api_index.dox +INPUT = ../src/api/api.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/docs/api_index.dox b/docs/api_index.dox deleted file mode 100644 index abaa67fa..00000000 --- a/docs/api_index.dox +++ /dev/null @@ -1,18 +0,0 @@ -/** - @mainpage - @author WrinklyNinja - @version 0..0 - @copyright The LOOT API is distributed under the GNU General Public License v3.0. For the full text of the license, see the "GNU GPL v3.txt" file included in the source archive. - - @section intro_sec Introduction - - LOOT is a utility that helps users avoid serious conflicts between their mods by setting their plugins in an optimal load order. It also provides tens of thousands of plugin-specific messages, including usage notes, requirements, incompatibilities, bug warnings and installation mistake notifications, and thousands of Bash Tag suggestions. - - This metadata that LOOT supplies is stored in its masterlist, which is maintained by the LOOT team using information provided by mod authors and users. Users can also add to and modify the metadata used by LOOT through the use of userlist files. The LOOT API provides a way for third-party developers to access this metadata for use in their own programs. - - All further API documentation is contained within the documentation for api.h. - - @section credit_sec Credits - - The LOOT API is written by WrinklyNinja in C/C++ and makes use of the yaml-cpp and libloadorder libraries and some of the Boost libraries. Copyright license information for all these may be found in the "licenses/Licenses.txt" file. -*/ diff --git a/src/api/api.h b/src/api/api.h index d3173aaa..40f1167d 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -22,6 +22,44 @@ . */ +/** + * @mainpage + * @author WrinklyNinja + * @version 0.7.0 + * @copyright + * The LOOT API is distributed under the GNU General Public License v3.0. + * For the full text of the license, see the "GNU GPL v3.txt" file + * included in the source archive. + * + * @section intro_sec Introduction + * LOOT is a utility that helps users avoid serious conflicts between + * their mods by setting their plugins in an optimal load order. It also + * provides tens of thousands of plugin-specific messages, including usage + * notes, requirements, incompatibilities, bug warnings and installation + * mistake notifications, and thousands of Bash Tag suggestions. + * + * This metadata that LOOT supplies is stored in its masterlist, which is + * maintained by the LOOT team using information provided by mod authors + * and users. Users can also add to and modify the metadata used by LOOT + * through the use of userlist files. The LOOT API provides a way for + * third-party developers to access this metadata for use in their own + * programs. + * + * All further API documentation is contained within the documentation for + * api.h. + * + * @section credit_sec Credits + * The LOOT API is written by WrinklyNinja in C/C++ and makes use of the + * [Alphanum](http://www.davekoelle.com/alphanum.html), + * [Boost](http://www.boost.org/), + * [libespm](http://github.com/WrinklyNinja/libespm), + * [libgit2](http://github.com/libgit2/libgit2), + * [libloadorder](http://github.com/WrinklyNinja/libloadorder/) and + * [yaml-cpp](http://code.google.com/p/yaml-cpp/) libraries. Copyright license + * information for all these may be found in the "docs/licenses/Licenses.txt" + * file. + */ + /** * @file api.h * @brief This file contains the API frontend. @@ -199,7 +237,7 @@ extern "C" /**@}*/ /**********************************************************************//** * @name Plugin Cleanliness Codes - * @brief Used with loot_get_dirty_message(). + * @brief Used with loot_get_dirty_info(). *************************************************************************/ /**@{*/ From 840241c9f3609f993a57a3bde08d5ffa6d55ae1f Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Fri, 26 Sep 2014 17:09:21 +0100 Subject: [PATCH 8/9] Implemented loot_apply_load_order. Also improved constness of parameters. --- src/api/api.cpp | 25 ++++++++++++++++++++++--- src/api/api.h | 6 +++--- src/backend/game.cpp | 44 ++++++++++++++++++++++++++------------------ src/backend/game.h | 1 + 4 files changed, 52 insertions(+), 24 deletions(-) diff --git a/src/api/api.cpp b/src/api/api.cpp index ffde700c..307e7782 100644 --- a/src/api/api.cpp +++ b/src/api/api.cpp @@ -365,13 +365,26 @@ LOOT_API unsigned int loot_eval_lists(loot_db db, const unsigned int language) { LOOT_API unsigned int loot_sort_plugins(loot_db db, char *** const sortedPlugins, - size_t * numPlugins) { + size_t * const numPlugins) { + if (db == nullptr || sortedPlugins == nullptr || numPlugins == nullptr) + return c_error(loot_error_invalid_args, "Null pointer passed."); + return loot_ok; } LOOT_API unsigned int loot_apply_load_order(loot_db db, - const char ** const loadOrder, - size_t numPlugins) { + const char * const * const loadOrder, + const size_t numPlugins) { + if (db == nullptr || loadOrder == nullptr) + return c_error(loot_error_invalid_args, "Null pointer passed."); + + try { + db->SetLoadOrder(loadOrder, numPlugins); + } + catch (loot::error &e) { + return c_error(e); + } + return loot_ok; } @@ -380,6 +393,9 @@ LOOT_API unsigned int loot_update_masterlist(loot_db db, const char * const remoteURL, const char * const remoteBranch, bool * const updated) { + if (db == nullptr || masterlistPath == nullptr || remoteURL == nullptr || remoteBranch == nullptr || updated == nullptr) + return c_error(loot_error_invalid_args, "Null pointer passed."); + return loot_ok; } @@ -388,6 +404,9 @@ LOOT_API unsigned int loot_get_masterlist_revision(const char * const masterlist char ** const revisionID, char ** const revisionDate, bool * const isModified) { + if (masterlistPath == nullptr || revisionID == nullptr || revisionDate == nullptr || isModified == nullptr) + return c_error(loot_error_invalid_args, "Null pointer passed."); + return loot_ok; } diff --git a/src/api/api.h b/src/api/api.h index 40f1167d..50694ec7 100644 --- a/src/api/api.h +++ b/src/api/api.h @@ -404,7 +404,7 @@ extern "C" */ LOOT_API unsigned int loot_sort_plugins(loot_db db, char *** const sortedPlugins, - size_t * numPlugins); + size_t * const numPlugins); /** * @brief Applies the given load order. @@ -417,8 +417,8 @@ extern "C" * @returns A return code. */ LOOT_API unsigned int loot_apply_load_order(loot_db db, - const char ** const loadOrder, - size_t numPlugins); + const char * const * const loadOrder, + const size_t numPlugins); /** * @brief Update the given masterlist. diff --git a/src/backend/game.cpp b/src/backend/game.cpp index d66ad6d7..fe6ddff6 100644 --- a/src/backend/game.cpp +++ b/src/backend/game.cpp @@ -620,12 +620,10 @@ namespace loot { lo_destroy_handle(gh); } - void Game::SetLoadOrder(const std::list& loadOrder) const { + void Game::SetLoadOrder(const char * const * const loadOrder, const size_t numPlugins) const { BOOST_LOG_TRIVIAL(debug) << "Setting load order for game: " << _name; lo_game_handle gh = nullptr; - char ** pluginArr = nullptr; - size_t pluginArrSize = 0; int ret; if (Id() == Game::tes4) ret = lo_create_handle(&gh, LIBLO_GAME_TES4, gamePath.string().c_str()); @@ -670,19 +668,7 @@ namespace loot { throw error(error::liblo_error, err); } - pluginArrSize = loadOrder.size(); - pluginArr = new char*[pluginArrSize]; - int i = 0; - for (const auto &plugin : loadOrder) { - pluginArr[i] = new char[plugin.length() + 1]; - strcpy(pluginArr[i], plugin.c_str()); - ++i; - } - - if (lo_set_load_order(gh, pluginArr, pluginArrSize) != LIBLO_OK) { - for (size_t i = 0; i < pluginArrSize; i++) - delete[] pluginArr[i]; - delete[] pluginArr; + if (lo_set_load_order(gh, loadOrder, numPlugins) != LIBLO_OK) { const char * e = nullptr; string err; lo_get_error_message(&e); @@ -699,11 +685,33 @@ namespace loot { throw error(error::liblo_error, err); } + lo_destroy_handle(gh); + } + + void Game::SetLoadOrder(const std::list& loadOrder) const { + + size_t pluginArrSize = loadOrder.size(); + char ** pluginArr = new char*[pluginArrSize]; + int i = 0; + for (const auto &plugin : loadOrder) { + pluginArr[i] = new char[plugin.length() + 1]; + strcpy(pluginArr[i], plugin.c_str()); + ++i; + } + + try { + SetLoadOrder(pluginArr, pluginArrSize); + } + catch (error &e) { + for (size_t i = 0; i < pluginArrSize; i++) + delete[] pluginArr[i]; + delete[] pluginArr; + throw e; + } + for (size_t i = 0; i < pluginArrSize; i++) delete[] pluginArr[i]; delete[] pluginArr; - - lo_destroy_handle(gh); } void Game::RedatePlugins() { diff --git a/src/backend/game.h b/src/backend/game.h index 13cec264..30329d34 100644 --- a/src/backend/game.h +++ b/src/backend/game.h @@ -131,6 +131,7 @@ namespace loot { void GetLoadOrder(std::list& loadOrder) const; void SetLoadOrder(const std::list& loadOrder) const; //Modifies game load order, even though const. + void SetLoadOrder(const char * const * const loadOrder, const size_t numPlugins) const; // For API. void RefreshActivePluginsList(); void RedatePlugins(); //Change timestamps to match load order (Skyrim only). From 134a4b1dd421a8e5e152c7e07b40bb468c71918d Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Fri, 26 Sep 2014 18:08:05 +0100 Subject: [PATCH 9/9] Implemented loot_sort_plugins. --- src/api/api.cpp | 52 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/src/api/api.cpp b/src/api/api.cpp index 307e7782..9665b7b8 100644 --- a/src/api/api.cpp +++ b/src/api/api.cpp @@ -94,7 +94,9 @@ struct _loot_db_int : public loot::Game { extAddedTagIds(nullptr), extRemovedTagIds(nullptr), extMessageArray(nullptr), - extMessageArraySize(0) { + extMessageArraySize(0), + extStringArray(nullptr), + extStringArraySize(0) { this->SetDetails("", "", "", "", gamePath, "").Init(); } @@ -113,6 +115,12 @@ struct _loot_db_int : public loot::Game { delete[] extMessageArray[i].message; //Gotta clear those allocated strings. delete[] extMessageArray; } + + if (extStringArray != nullptr) { + for (size_t i = 0; i < extStringArraySize; i++) + delete[] extStringArray[i]; //Gotta clear those allocated strings. + delete[] extStringArray; + } } loot::MetadataList rawUserMetadata; @@ -122,6 +130,9 @@ struct _loot_db_int : public loot::Game { char ** extTagMap; + char ** extStringArray; + size_t extStringArraySize; + unsigned int * extAddedTagIds; unsigned int * extRemovedTagIds; @@ -369,6 +380,45 @@ LOOT_API unsigned int loot_sort_plugins(loot_db db, if (db == nullptr || sortedPlugins == nullptr || numPlugins == nullptr) return c_error(loot_error_invalid_args, "Null pointer passed."); + //Clear existing array allocation. + if (db->extStringArray != nullptr) { + for (size_t i = 0; i < db->extStringArraySize; ++i) { + delete[] db->extStringArray[i]; + } + delete[] db->extStringArray; + db->extStringArray = nullptr; + } + + //Initialise output. + *numPlugins = 0; + *sortedPlugins = nullptr; + + try { + // Always reload all the plugins. + db->LoadPlugins(false); + + //Sort plugins into their load order. + std::list plugins = db->Sort(loot_lang_any, [](const std::string& message) {}); + + db->extStringArraySize = plugins.size(); + db->extStringArray = new char*[db->extStringArraySize]; + + size_t i = 0; + for (const auto &plugin : plugins) { + db->extStringArray[i] = ToNewCString(plugin.Name()); + ++i; + } + } + catch (loot::error &e) { + return c_error(e); + } + catch (std::bad_alloc& e) { + return c_error(loot_error_no_mem, e.what()); + } + + *numPlugins = db->extStringArraySize; + *sortedPlugins = db->extStringArray; + return loot_ok; }