diff --git a/docs/BOSS API Readme.html b/docs/BOSS API Readme.html new file mode 100644 index 00000000..486f99d8 --- /dev/null +++ b/docs/BOSS API Readme.html @@ -0,0 +1,303 @@ + + +BOSS API Readme + + + +
+This documentation is a work in progress, covering an API that is also still a work in progress, and is subject to change. Userlist loading and access has not yet been implemented. The minimal file write doesn't include dirty messages yet. +
+ +

BOSS API Readme

+ +

Contents

+
    +
  1. Introduction +
  2. Variable Types +
  3. Memory Management +
  4. API Codes +
  5. Functions +
      +
    1. Error Handling Functions +
    2. Version Functions +
    3. Lifecycle Management Functions +
    4. Database Loading Functions +
    5. Database Access Functions +
    +
  6. Examples +
  7. Credits +
  8. License +
+ +

Introduction

+

BOSS 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 BOSS supplies is stored in its masterlist, which is maintained by the BOSS team using information provided by mod authors and users. Users can also add to and modify the metadata used by BOSS through the use of userlist files. The BOSS API provides a way for third-party developers to access this metadata for use in their own programs. +

Note: The BOSS API is not thread-safe. Thread safety is a goal, but has not yet been implemented. + +

Variable Types

+

The API uses character strings and unsigned integers for data input/output. +

+

The API also provides two new structures: +typedef struct _boss_db_int * boss_db; +

The boss_db structure is used by the API to abstract the internal state of a database while still providing type safety. +typedef struct { + unsigned int type; + const char * message; +} boss_message; + +

The boss_message structure gives the type of a message and the message string itself. + +

Memory Management

+

The 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 boss_destroy_db is called, except the string allocated by boss_get_error_message, which must be freed by calling boss_cleanup. + +

API Codes

+

The following codes are used to signal how a function completes. + + +
Return CodeDescription +
BOSS_API_OK The function completed successfully. +
BOSS_API_ERROR_LIBLO_ERRORThere was an error in reading the active plugins list. +
BOSS_API_ERROR_FILE_WRITE_FAILA file could not be written to. +
BOSS_API_ERROR_PARSE_FAILThere was an error parsing the file. +
BOSS_API_ERROR_CONDITION_EVAL_FAIL There was an error evaluating the conditionals in a metadata file. +
BOSS_API_ERROR_REGEX_EVAL_FAIL There was an error evaluating the regular expressions in a metadata file. +
BOSS_API_ERROR_NO_MEMThe API was unable to allocate the required memory. +
BOSS_API_ERROR_INVALID_ARGS Invalid arguments were given for the function. +
BOSS_API_ERROR_NO_TAG_MAPNo Bash Tag map has been generated yet. +
BOSS_API_RETURN_MAXMatches the value of the highest-numbered return code. +
+

The following codes are used with boss_create_db to specify the game that the API acts for. + + +
Game CodeGame +
BOSS_API_GAME_TES4The Elder Scrolls IV: Oblivion +
BOSS_API_GAME_TES5The Elder Scrolls V: Skyrim +
BOSS_API_GAME_FO3Fallout 3 +
BOSS_API_GAME_FONVFallout: New Vegas +
+

The following codes are used by the boss_message type to specify the type of a particular message. + + +
Message Type CodeGame +
BOSS_API_MESSAGE_SAYA general note. +
BOSS_API_MESSAGE_WARNA warning message. +
BOSS_API_MESSAGE_ERRORAn error message. +
+ +

Functions

+ +

Error Handling Functions

+
+unsigned int boss_get_error_message (char ** message); +

Outputs a string detailing the last error encountered. +

+
+
+void boss_cleanup (); +

Frees the memory allocated to the error message string, if boss_get_error_message has been called. +

+ +

Version Functions

+
+bool boss_is_compatible (const unsigned int versionMajor, + const unsigned int versionMinor, + const unsigned int versionPatch); +

Checks if the API version in use is compatible with the given API version. Abstracts BOSS API stability policy away from clients. +

+
+
+unsigned int boss_get_version (unsigned int * versionMajor, + unsigned int * versionMinor, + unsigned int * versionPatch); +

Gets the version numbers of the API in use. +

+
+ +

Lifecycle Management Functions

+
+unsigned int boss_create_db (boss_db * db, + const unsigned int clientGame, + const char * gamePath); +

Creates a database for the specified game. You can create multiple databases. +

+
+
+void boss_destroy_db (boss_db db); +

Destroys the given database, freeing any memory allocated during its use. +

+
+ +

Database Loading Functions

+
+unsigned int boss_load_lists (boss_db db, + const char * masterlistPath, + const char * userlistPath); +

Loads the given masterlist and userlist for the game specified when the given database was created. Also frees any memory currently allocated to the given database by any access functions previously called. Can be called multiple times. If an error is encountered, the database remains unchanged. +

+
+
+unsigned int boss_eval_lists (boss_db db); +

Refreshes the active plugin list used during evaluation then evaluates all conditional and regular expression metadata entries. Repeated calls re-evaluate the metadata from scratch. This function affects the output of all the database access functions. +

+
+ +

Database Access Functions

+
+unsigned int boss_get_tag_map (boss_db db, + char *** tagMap, + size_t * numTags); +

Outputs an array of the Bash Tags that are suggested in the masterlist and userlist. This function must be called prior to calling boss_get_plugin_tags to ensure that the latter can return the Tags using the correct array indicies. +

+
+
+unsigned int boss_get_plugin_tags (boss_db db, + const char * plugin, + unsigned int ** tags_added, + size_t * numTags_added, + unsigned int ** tags_removed, + size_t * numTags_removed, + bool * userlistModified); +

Outputs the Bash Tags suggested for addition and removal by the masterlist and userlist. boss_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. +

+
+
+unsigned int boss_get_plugin_messages (boss_db db, + const char * plugin, + boss_message ** messages, + size_t * numMessages); +

Outputs the messages associated with the given plugin in the masterlist and/or userlist. +

+
+
+unsigned int boss_write_minimal_list (boss_db db, + const char * outputFile, + const bool overwrite); +

Writes a minimal metadata file that only contains plugins with Bash Tag suggestions and/or warning messages about dirtiness, plus the suggestions and messages themselves. +

+
+ +

Examples

+

The api-tester application provides a very simple usage example. Its source code is hosted with the BOSS API source code. + +

Credits

+

Thanks go to Lojack and myk002 for significant contributions during planning and beta testing, and to kaburke for beta testing of v2 of the API. +

The BOSS API is written in C/C++ and makes use of the Boost, yaml-cpp and libloadorder libraries. + +

License

+

This document is part of the BOSS documentation.
+Copyright (C) 2013 WrinklyNinja
+See the file BOSS ReadMe.html for copying conditions. diff --git a/src/api.cpp b/src/api.cpp index 1461ba94..57c5da06 100644 --- a/src/api.cpp +++ b/src/api.cpp @@ -42,12 +42,13 @@ const unsigned int BOSS_API_OK = 0; const unsigned int BOSS_API_ERROR_LIBLO_ERROR = 1; -const unsigned int BOSS_API_ERROR_PARSE_FAIL = 2; -const unsigned int BOSS_API_ERROR_CONDITION_EVAL_FAIL = 3; -const unsigned int BOSS_API_ERROR_REGEX_EVAL_FAIL = 4; -const unsigned int BOSS_API_ERROR_NO_MEM = 5; -const unsigned int BOSS_API_ERROR_INVALID_ARGS = 6; -const unsigned int BOSS_API_ERROR_NO_TAG_MAP = 7; +const unsigned int BOSS_API_ERROR_FILE_WRITE_FAIL = 2; +const unsigned int BOSS_API_ERROR_PARSE_FAIL = 3; +const unsigned int BOSS_API_ERROR_CONDITION_EVAL_FAIL = 4; +const unsigned int BOSS_API_ERROR_REGEX_EVAL_FAIL = 5; +const unsigned int BOSS_API_ERROR_NO_MEM = 6; +const unsigned int BOSS_API_ERROR_INVALID_ARGS = 7; +const unsigned int BOSS_API_ERROR_NO_TAG_MAP = 8; const unsigned int BOSS_API_RETURN_MAX = BOSS_API_ERROR_NO_TAG_MAP; // The following are the games identifiers used by the API. @@ -88,8 +89,7 @@ struct _boss_db_int { } boss::Game game; - std::list metadata; - std::list userMetadata; + std::list metadata, rawMetadata, userMetadata, rawUserMetadata; boost::unordered_map bashTagMap; @@ -232,8 +232,27 @@ BOSS_API unsigned int boss_load_lists (boss_db db, const char * masterlistPath, return BOSS_API_ERROR_INVALID_ARGS; } + //Also free memory. + db->bashTagMap.clear(); + delete [] db->extAddedTagIds; + delete [] db->extRemovedTagIds; + + if (db->extTagMap != NULL) { + 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 != NULL) { + for (size_t i=0; i < db->extMessageArraySize; i++) + delete [] db->extMessageArray[i].message; //Gotta clear those allocated strings. + delete [] db->extMessageArray; + } + + db->rawMetadata = temp; db->metadata = temp; db->userMetadata = userTemp; + db->rawUserMetadata = userTemp; return BOSS_API_OK; } @@ -246,20 +265,59 @@ BOSS_API unsigned int boss_load_lists (boss_db db, const char * masterlistPath, // if the underlying filesystem is case-sensitive. BOSS_API unsigned int boss_eval_lists (boss_db db) { - std::list temp = db->metadata; + std::list temp = db->rawMetadata; try { - for (std::list::iterator it=temp.begin(), endIt=temp.end(); it != endIt; ++it) { + db->game.RefreshActivePluginsList(); + for (std::list::iterator it=temp.begin(); it != temp.end(); ++it) { it->EvalAllConditions(db->game); + if (it->IsRegexPlugin()) { + boost::regex regex; + try { + regex = boost::regex(it->Name(), boost::regex::extended|boost::regex::icase); + } catch (boost::regex_error e) { + return BOSS_API_ERROR_INVALID_ARGS; + } + + for (boost::filesystem::directory_iterator itr(db->game.DataPath()); itr != boost::filesystem::directory_iterator(); ++itr) { + const std::string filename = itr->path().filename().string(); + if (boost::regex_match(filename, regex)) { + boss::Plugin p = *it; + p.Name(filename); + temp.push_back(p); + } + } + it = temp.erase(it); + --it; + } } } catch (std::runtime_error& e) { return BOSS_API_ERROR_INVALID_ARGS; } db->metadata = temp; - temp = db->userMetadata; + temp = db->rawUserMetadata; try { for (std::list::iterator it=temp.begin(), endIt=temp.end(); it != endIt; ++it) { it->EvalAllConditions(db->game); + if (it->IsRegexPlugin()) { + boost::regex regex; + try { + regex = boost::regex(it->Name(), boost::regex::extended|boost::regex::icase); + } catch (boost::regex_error e) { + return BOSS_API_ERROR_INVALID_ARGS; + } + + for (boost::filesystem::directory_iterator itr(db->game.DataPath()); itr != boost::filesystem::directory_iterator(); ++itr) { + const std::string filename = itr->path().filename().string(); + if (boost::regex_match(filename, regex)) { + boss::Plugin p = *it; + p.Name(filename); + temp.push_back(p); + } + } + it = temp.erase(it); + --it; + } } } catch (std::runtime_error& e) { return BOSS_API_ERROR_INVALID_ARGS; @@ -363,6 +421,9 @@ BOSS_API unsigned int boss_get_plugin_tags (boss_db db, const char * plugin, *numTags_added = 0; *numTags_removed = 0; + if (db->bashTagMap.empty()) + return BOSS_API_ERROR_NO_TAG_MAP; + boost::unordered_set tagsAdded, tagsRemoved; std::list::iterator pluginIt = std::find(db->metadata.begin(), db->metadata.end(), boss::Plugin(plugin)); if (pluginIt != db->metadata.end()) { diff --git a/src/api.h b/src/api.h index d0200b13..72417968 100644 --- a/src/api.h +++ b/src/api.h @@ -84,6 +84,7 @@ typedef struct { // The following are the possible codes that the API can return. BOSS_API extern const unsigned int BOSS_API_OK; BOSS_API extern const unsigned int BOSS_API_ERROR_LIBLO_ERROR; +BOSS_API extern const unsigned int BOSS_API_ERROR_FILE_WRITE_FAIL; BOSS_API extern const unsigned int BOSS_API_ERROR_PARSE_FAIL; BOSS_API extern const unsigned int BOSS_API_ERROR_CONDITION_EVAL_FAIL; BOSS_API extern const unsigned int BOSS_API_ERROR_REGEX_EVAL_FAIL; @@ -187,18 +188,18 @@ BOSS_API unsigned int boss_get_tag_map (boss_db db, char *** tagMap, size_t * nu // will be NULL. The userlistModified bool is true if the userlist contains Bash Tag // suggestion message additions. BOSS_API unsigned int boss_get_plugin_tags (boss_db db, const char * plugin, - unsigned int ** tagIds_added, - size_t * numTags_added, - unsigned int **tagIds_removed, - size_t *numTags_removed, - bool * userlistModified); + unsigned int ** tags_added, + size_t * numTags_added, + unsigned int ** tags_removed, + size_t * numTags_removed, + bool * userlistModified); // Returns the messages attached to the given plugin. Messages are valid until Load, // DestroyBossDb or GetPluginMessages are next called. plugin is case-insensitive. // If no messages are attached, *messages will be NULL and numMessages will equal 0. BOSS_API unsigned int boss_get_plugin_messages (boss_db db, const char * plugin, - boss_message ** messages, - size_t * numMessages); + boss_message ** messages, + size_t * numMessages); // Writes a minimal masterlist that only contains mods that have Bash Tag suggestions, // and/or dirty messages, plus the Tag suggestions and/or messages themselves and their diff --git a/src/game.cpp b/src/game.cpp index 2be06c1d..d90137e0 100644 --- a/src/game.cpp +++ b/src/game.cpp @@ -94,30 +94,7 @@ namespace boss { } else gamePath = fs::path(path); - lo_game_handle gh; - int ret; - char ** pluginArr; - size_t pluginArrSize; - if (id == BOSS_GAME_TES4) - ret = lo_create_handle(&gh, LIBLO_GAME_TES4, gamePath.string().c_str()); - else if (id == BOSS_GAME_TES5) - ret = lo_create_handle(&gh, LIBLO_GAME_TES5, gamePath.string().c_str()); - else if (id == BOSS_GAME_FO3) - ret = lo_create_handle(&gh, LIBLO_GAME_FO3, gamePath.string().c_str()); - else if (id == BOSS_GAME_FONV) - ret = lo_create_handle(&gh, LIBLO_GAME_FNV, gamePath.string().c_str()); - - if (ret != LIBLO_OK) - throw runtime_error("Active plugin list lookup failed."); - else { - if (lo_get_active_plugins(gh, &pluginArr, &pluginArrSize) != LIBLO_OK) - throw runtime_error("Active plugin list lookup failed."); - else { - for (size_t i=0; i < pluginArrSize; ++i) { - activePlugins.insert(string(pluginArr[i])); - } - } - } + RefreshActivePluginsList(); } } @@ -145,6 +122,33 @@ namespace boss { return GamePath() / pluginsFolderName; } + void Game::RefreshActivePluginsList() { + lo_game_handle gh; + int ret; + char ** pluginArr; + size_t pluginArrSize; + if (id == BOSS_GAME_TES4) + ret = lo_create_handle(&gh, LIBLO_GAME_TES4, gamePath.string().c_str()); + else if (id == BOSS_GAME_TES5) + ret = lo_create_handle(&gh, LIBLO_GAME_TES5, gamePath.string().c_str()); + else if (id == BOSS_GAME_FO3) + ret = lo_create_handle(&gh, LIBLO_GAME_FO3, gamePath.string().c_str()); + else if (id == BOSS_GAME_FONV) + ret = lo_create_handle(&gh, LIBLO_GAME_FNV, gamePath.string().c_str()); + + if (ret != LIBLO_OK) + throw runtime_error("Active plugin list lookup failed."); + else { + if (lo_get_active_plugins(gh, &pluginArr, &pluginArrSize) != LIBLO_OK) + throw runtime_error("Active plugin list lookup failed."); + else { + for (size_t i=0; i < pluginArrSize; ++i) { + activePlugins.insert(string(pluginArr[i])); + } + } + } + } + bool Game::IsActive(const std::string& plugin) const { return activePlugins.find(boost::to_lower_copy(plugin)) != activePlugins.end(); } diff --git a/src/game.h b/src/game.h index 7d1eb503..7218fa96 100644 --- a/src/game.h +++ b/src/game.h @@ -50,6 +50,7 @@ namespace boss { //Creates directory in BOSS folder for BOSS's game-specific files. void CreateBOSSGameFolder(); + void RefreshActivePluginsList(); bool IsActive(const std::string& plugin) const; //Caches for condition results, active plugins and CRCs. diff --git a/src/metadata.cpp b/src/metadata.cpp index 231db81e..47e3f304 100644 --- a/src/metadata.cpp +++ b/src/metadata.cpp @@ -161,6 +161,10 @@ namespace boss { return tags; } + void Plugin::Name(const std::string& n) { + name = n; + } + void Plugin::Enabled(const bool e) { enabled = e; } diff --git a/src/metadata.h b/src/metadata.h index cff6291d..43d1eb3b 100644 --- a/src/metadata.h +++ b/src/metadata.h @@ -118,6 +118,7 @@ namespace boss { std::list Messages() const; std::list Tags() const; + void Name(const std::string& name); void Enabled(const bool enabled); void Priority(const int priority); void LoadAfter(const std::list& after);