loot/libloot
0
0
Fork 0
mirror of https://github.com/loot/libloot.git synced 2026-07-27 14:16:01 -07:00
Code Issues Packages Projects Releases Wiki Activity

Switched API documentation to Doxygen since it's easier to maintain.

Browse Source 
Not as good-looking though. :(
This commit is contained in:
WrinklyNinja
2013-07-27 12:12:37 +01:00
parent b11ebd6aac
commit e50d4f0f68
6 changed files with 2049 additions and 451 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2
View File
@@ -46,6 +46,8 @@ Thumbs.db
*.opensdf
externals/
build/
docs/html
docs/latex
out/
bin/
ipch/
docs/BOSS API Readme.html
-351
View File
@@ -1,351 +0,0 @@
<!DOCTYPE html>
<meta charset="utf-8">
<title>BOSS API Readme</title>
<style>
body {
font:10pt/1.5 Helvetica,sans-serif;
text-rendering:optimizeLegibility;}
p, ul, li {margin:1.5em 0;}
h1,h3,h2 {font-weight:normal;}
h1{
font-size:36pt;
line-height:0.5;
margin-top:1.125em;
margin-bottom:0.375em;}
h2{
font-size:24pt;
line-height:0.75;
margin-top:3em;
margin-bottom:1.5em;}
h3{
font-size:18pt;
line-height:1;
margin-top:3.5em;
margin-bottom:1em;}
ul, ol {margin-top:0.5em; margin-bottom:1em;}
li {margin:0.75em 0;}
a:link {text-decoration:none;}
a:hover {text-decoration:underline;}
ol ol {list-style:lower-alpha;}
code {display:inline-block; padding:0 3px; background:#eee;}
td, th {border:1px solid #ddd; padding: 5px; vertical-align:top;}
table {border-collapse:collapse; margin:1.5em; margin-bottom: 3em; background:#fafafa;}
thead {background:#99CCFF;}
code.box {border-radius:5px; border:1px solid #ccc; padding:0.75em; white-space:pre; overflow-x:auto; display:table; margin:1.5em;}
blockquote {border-radius:3px; border:1px solid #0c0; padding:5px; background:#7e7; display:table;margin:1.5em;}
a[href^="http"]:after {padding-left:2px; content: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAVklEQVR4Xn3PgQkAMQhDUXfqTu7kTtkpd5RA8AInfArtQ2iRXFWT2QedAfttj2FsPIOE1eCOlEuoWWjgzYaB/IkeGOrxXhqB+uA9Bfcm0lAZuh+YIeAD+cAqSz4kCMUAAAAASUVORK5CYII=);}
span[title] {border-bottom: 1px dotted; font-family: sans-serif; cursor:help;}
abbr {cursor:help; border-bottom: 1px dotted black;}
#warning {background:#fbb; padding:10px 5px;margin:-8px;}
var {color:#8B4513;}
.dfn {display:block; margin-bottom:4.5em; font-style:normal;}
</style>
<!-- BOSS
A plugin load order optimiser for games that use the esp/esm plugin system.
Copyright (C) 2012–2013 WrinklyNinja
This file is part of BOSS.
BOSS is free software: you can redistribute
it and/or modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
BOSS is distributed in the hope that it will
be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with BOSS. If not, see
<http://www.gnu.org/licenses/>.
-->
<div id="warning">
This documentation is a work in progress, covering an API that is also still a work in progress, and is subject to change. Userlist access has not yet been implemented.
</div>
<h1>BOSS API Readme</h1>
<h2>Contents</h2>
<ol>
<li><a href="#intro">Introduction</a>
<li><a href="#types">Variable Types</a>
<li><a href="#memory">Memory Management</a>
<li><a href="#codes">API Codes</a>
<li><a href="#func">Functions</a>
<ol>
<li><a href="#func-error">Error Handling Functions</a>
<li><a href="#func-version">Version Functions</a>
<li><a href="#func-lifecycle">Lifecycle Management Functions</a>
<li><a href="#func-load">Database Loading Functions</a>
<li><a href="#func-access">Database Access Functions</a>
</ol>
<li><a href="#examples">Examples</a>
<li><a href="#credits">Credits</a>
<li><a href="#license">License</a>
</ol>
<h2 id="intro">Introduction</h2>
<p>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.
<p>This metadata that BOSS supplies is stored in its <em>masterlist</em>, 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 <em>userlist</em> files. The BOSS API provides a way for third-party developers to access this metadata for use in their own programs.
<p><b>Note:</b> The BOSS API is not thread-safe. Thread safety is a goal, but has not yet been implemented.
<h2 id="types">Variable Types</h2>
<p>The API uses character strings and unsigned integers for data input/output.
<ul>
<li>All strings are null-terminated byte character strings encoded in UTF-8.
<li>All codes are unsigned integers at least 16 bits in size.
<li>All array sizes are unsigned integers at least 16 bits in size.
<li>File paths are case-sensitive if and only if the underlying file system is case-sensitive.
</ul>
<p>The API also provides two new structures:
<code class="box">typedef struct _boss_db_int * boss_db;</code>
<p>The <code>boss_db</code> structure is used by the API to abstract the internal state of a database while still providing type safety.
<code class="box">typedef struct {
unsigned int type;
const char * message;
} boss_message;
</code>
<p>The <code>boss_message</code> structure gives the type of a message and the message string itself.
<h2 id="memory">Memory Management</h2>
<p>The API manages the memory of strings and arrays it returns internally, so such strings and arrays should not be deallocated by the client.
<p>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.).
<p>All allocated memory is freed when <a href="#boss_destroy_db">boss_destroy_db</a> is called, except the string allocated by <a href="#boss_get_error_message">boss_get_error_message</a>, which must be freed by calling <a href="#boss_cleanup">boss_cleanup</a>.
<h2 id="codes">API Codes</h2>
<p>The following codes are used to signal how a function completes.
<table>
<thead><tr><th>Return Code<th>Description
<tbody>
<tr><td>BOSS_API_OK<td> The function completed successfully.
<tr><td>BOSS_API_ERROR_LIBLO_ERROR<td>There was an error in reading the active plugins list.
<tr><td>BOSS_API_ERROR_FILE_WRITE_FAIL<td>A file could not be written to.
<tr><td>BOSS_API_ERROR_PARSE_FAIL<td>There was an error parsing the file.
<tr><td>BOSS_API_ERROR_CONDITION_EVAL_FAIL<td> There was an error evaluating the conditionals in a metadata file.
<tr><td>BOSS_API_ERROR_REGEX_EVAL_FAIL<td> There was an error evaluating the regular expressions in a metadata file.
<tr><td>BOSS_API_ERROR_NO_MEM<td>The API was unable to allocate the required memory.
<tr><td>BOSS_API_ERROR_INVALID_ARGS<td> Invalid arguments were given for the function.
<tr><td>BOSS_API_ERROR_NO_TAG_MAP<td>No Bash Tag map has been generated yet.
<tr><td>BOSS_API_ERROR_PATH_NOT_FOUND<td>A file or folder path could not be found.
<tr><td>BOSS_API_RETURN_MAX<td>Matches the value of the highest-numbered return code.
</table>
<p>The following codes are used with <a href="#boss_create_db">boss_create_db</a> to specify the game that the API acts for.
<table>
<thead><tr><th>Game Code<th>Game
<tbody>
<tr><td>BOSS_API_GAME_TES4<td>The Elder Scrolls IV: Oblivion
<tr><td>BOSS_API_GAME_TES5<td>The Elder Scrolls V: Skyrim
<tr><td>BOSS_API_GAME_FO3<td>Fallout 3
<tr><td>BOSS_API_GAME_FONV<td>Fallout: New Vegas
</table>
<p>The following codes are used by the <code>boss_message</code> type to specify the type of a particular message.
<table>
<thead><tr><th>Message Type Code<th>Game
<tbody>
<tr><td>BOSS_API_MESSAGE_SAY<td>A general note.
<tr><td>BOSS_API_MESSAGE_WARN<td>A warning message.
<tr><td>BOSS_API_MESSAGE_ERROR<td>An error message.
</table>
<p>The following codes are used with <a href="#boss_eval_lists">boss_eval_lists</a> to specify the language that should be used when evaluating messages.
<table>
<thead><tr><th>Language Code<th>Description
<tbody>
<tr><td>BOSS_API_LANG_AUTO<td>Allow any language messages.
<tr><td>BOSS_API_LANG_ENG<td>Allow only English language messages.
</table>
<h2 id="func">Functions</h2>
<h3 id="func-error">Error Handling Functions</h3>
<div class="dfn" id="boss_get_error_message">
<code class="box">unsigned int boss_get_error_message (const char ** const message);</code>
<p>Outputs a string detailing the last error encountered.
<ul>
<li><var>message</var> - A pointer to the error string outputted.
</ul>
</div>
<div class="dfn" id="boss_cleanup">
<code class="box">void boss_cleanup ();</code>
<p>Frees the memory allocated to the error message string, if <a href="#boss_get_error_message">boss_get_error_message</a> has been called.
</div>
<h3 id="func-version">Version Functions</h3>
<div class="dfn" id="boss_is_compatible">
<code class="box">bool boss_is_compatible (const unsigned int versionMajor,
const unsigned int versionMinor,
const unsigned int versionPatch);</code>
<p>Checks if the API version in use is compatible with the given API version. Abstracts BOSS API stability policy away from clients.
<ul>
<li><var>versionMajor</var> - The major version number (<b>major</b>.minor.patch) to check.
<li><var>versionMinor</var> - The minor version number (major.<b>minor</b>.patch) to check.
<li><var>versionPatch</var> - The patch version number (major.minor.<b>patch</b>) to check.
</ul>
</div>
<div class="dfn" id="boss_get_version">
<code class="box">unsigned int boss_get_version (unsigned int * const versionMajor,
unsigned int * const versionMinor,
unsigned int * const versionPatch);</code>
<p>Gets the version numbers of the API in use.
<ul>
<li><var>versionMajor</var> - A pointer to the major version number (<b>major</b>.minor.patch).
<li><var>versionMinor</var> - A pointer to the minor version number (major.<b>minor</b>.patch).
<li><var>versionPatch</var> - A pointer to the patch version number (major.minor.<b>patch</b>).
</ul>
</div>
<h3 id="func-lifecycle">Lifecycle Management Functions</h3>
<div class="dfn" id="boss_create_db">
<code class="box">unsigned int boss_create_db (boss_db * const db,
const unsigned int clientGame,
const char * const gamePath);</code>
<p>Creates a database for the specified game. You can create multiple databases.
<ul>
<li><var>db</var> - A pointer to the database to be created.
<li><var>clientGame</var> - A game code specifying for which game you want to create a database.
<li><var>gamePath</var> - A string giving the path to the game's main folder, ie. the one in which the game's executable lies, or <code>null</code>. If <code>null</code>, then the API will attempt to detect the game folder location itself using the game's registry entries.
</ul>
</div>
<div class="dfn" id="boss_destroy_db">
<code class="box">void boss_destroy_db (boss_db db);</code>
<p>Destroys the given database, freeing any memory allocated during its use.
<ul>
<li><var>db</var> - The database to be destroyed.
</ul>
</div>
<h3 id="func-load">Database Loading Functions</h3>
<div class="dfn" id="boss_load_lists">
<code class="box">unsigned int boss_load_lists (boss_db db,
const char * const masterlistPath,
const char * const userlistPath);</code>
<p>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.
<ul>
<li><var>db</var> - The database the function acts on.
<li><var>masterlistPath</var> - A string containing the relative or absolute path to the masterlist file that should be loaded.
<li><var>userlistPath</var> - A string containing the relative or absolute path to the userlist file that should be loaded, or <code>null</code>. If <code>null</code>, no userlist will be loaded.
</ul>
</div>
<div class="dfn" id="boss_eval_lists">
<code class="box">unsigned int boss_eval_lists (boss_db db, const unsigned int language);</code>
<p>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.
<ul>
<li><var>db</var> - The database the function acts on.
<li><var>language</var> - The language code that is used for message language comparisons.
</ul>
</div>
<h3 id="func-access">Database Access Functions</h3>
<div class="dfn" id="boss_get_tag_map">
<code class="box">unsigned int boss_get_tag_map (boss_db db,
char *** const tagMap,
size_t * const numTags);</code>
<p>Outputs an array of the Bash Tags that are suggested in the masterlist and userlist. This function must be called prior to calling <a href="#boss_get_plugin_tags">boss_get_plugin_tags</a> to ensure that the latter can return the Tags using the correct array indicies.
<ul>
<li><var>db</var> - The database the function acts on.
<li><var>tagMap</var> - 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 <a href="#boss_get_plugin_tags">boss_get_plugin_tags</a> is called.
<li><var>numTags</var> - A pointer to the size of the <var>tagMap</var> array. <code>0</code> if <var>tagMap</var> is <code>null</code>.
</ul>
</div>
<div class="dfn" id="boss_get_plugin_tags">
<code class="box">unsigned int boss_get_plugin_tags (boss_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);</code>
<p>Outputs the Bash Tags suggested for addition and removal by the masterlist and userlist. <a href="#boss_get_tag_map">boss_get_tag_map</a> must be called before this to ensure that the Bash Tag UIDs outputted by this function can be matched up to name strings.
<ul>
<li><var>db</var> - The database the function acts on.
<li><var>plugin</var> - The filename of the plugin to look up Bash Tag suggestions for.
<li><var>tags_added</var> - A pointer to the outputted array of UIDs of the Bash Tags suggested for addition to the specified plugin. <code>null</code> if no Bash Tag additions are suggested.
<li><var>numTags_added</var> - A pointer to the size of the <var>tags_added</var> array. <code>0</code> if <var>tags_added</var> is <code>null</code>.
<li><var>tags_removed</var> - A pointer to the outputted array of UIDs of the Bash Tags suggested for removal from the specified plugin. <code>null</code> if no Bash Tag removals are suggested.
<li><var>numTags_removed</var> - A pointer to the size of the <var>tags_removed</var> array. <code>0</code> if <var>tags_removed</var> is <code>null</code>.
<li><var>userlistModified</var> - <code>true</code> if the Bash Tag suggestions were modified by the data in the userlist, <code>false</code> otherwise.
</ul>
</div>
<div class="dfn" id="boss_get_plugin_messages">
<code class="box">unsigned int boss_get_plugin_messages (boss_db db,
const char * const plugin,
boss_message ** const messages,
size_t * const numMessages);</code>
<p>Outputs the messages associated with the given plugin in the masterlist and/or userlist.
<ul>
<li><var>db</var> - The database the function acts on.
<li><var>plugin</var> - The filename of the plugin to look up messages for.
<li><var>messages</var> - A pointer to the outputted array of messages associated with the specified plugin, given as <code>boss_message</code> structures. <code>null</code> if the plugin has no messages associated with it.
<li><var>numMessages</var> - A pointer to the size of the <var>messages</var> array. <code>0</code> if <var>messages</var> is <code>null</code>.
</ul>
</div>
<div class="dfn" id="boss_write_minimal_list">
<code class="box">unsigned int boss_write_minimal_list (boss_db db,
const char * const outputFile,
const bool overwrite);</code>
<p>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.
<ul>
<li><var>db</var> - The database the function acts on.
<li><var>outputFile</var> - The path to which the file shall be written.
<li><var>overwrite</var> - If <code>true</code> and <var>outputFile</var> already exists, the existing file will be overwritten. If <code>false</code> and <var>outputFile</var> already exists, no data will be written. Otherwise, data will be written to <var>outputFile</var>.
</ul>
</div>
<h2 id="examples">Examples</h2>
<p>The following is a short program that will print out a list of dirty messages for a given plugin.
<code class="box">#include "api.h"
#include &lt;cstddef&gt;
#include &lt;cstring&gt;
#include &lt;iostream&gt;
int main(int argc, char *argv[]) {
boss_db db;
unsigned int ret;
boss_message * messages;
size_t numMessages;
if (argc != 2) {
std::cout &lt;&lt; "Invalid args.";
return -1;
}
//Creating a database for Oblivion, using path stored in Registry.
ret = boss_create_db(&amp;db, BOSS_API_GAME_TES4, NULL);
//Load a masterlist that's in the current working directory.
ret = boss_load_lists(db, "masterlist.yaml", NULL);
//We only want the messages that are relevant to the current install.
ret = boss_eval_lists(db);
//Now fetch the messages for the plugin given as the program's argument.
ret = boss_get_plugin_messages(db, argv[1], &amp;messages, &amp;numMessages);
//Dirty messages are of the warning type and contain the substring "dirty edits".
for (size_t i = 0; i &lt; numMessages; ++i) {
if (messages[i].type == BOSS_API_MESSAGE_WARN &amp;&amp;
strstr(messages[i].message, "dirty edits") != NULL) {
std::cout &lt;&lt; messages[i].message &lt;&lt; std::endl;
}
}
return 0;
}
</code>
<h2 id="credits">Credits</h2>
<p>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.
<p>The BOSS API is written in C/C++ and makes use of the <a href="http://www.boost.org/">Boost</a>, <a href="http://code.google.com/p/yaml-cpp/">yaml-cpp</a> and <a href="http://github.com/WrinklyNinja/libloadorder/">libloadorder</a> libraries.
<h2 id="license">License</h2>
<p>This document is part of the BOSS documentation.<br>
Copyright (C) 2013 WrinklyNinja<br>
See the file <q>BOSS ReadMe.html</q> for copying conditions.
docs/BOSS Readme.html
+3 -4
View File
@@ -114,7 +114,6 @@ This documentation is a work in progress, covering an application that is also s
<li><a href="#appendix-permissions">File Permissions</a>
</ol>
<li><a href="#history">Version History</a>
<li><a href="BOSS%20API%20Readme.html">API Readme</a> (separate document)
<li><a href="BOSS%20Metadata%20Syntax.html">Metadata Syntax</a> (separate document)
</ol>
@@ -221,7 +220,7 @@ This documentation is a work in progress, covering an application that is also s
<tbody>
<tr><td>Enable User Changes<td>If this is checked, BOSS will use the metadata you supplied when sorting the current plugin. Otherwise, your metadata will be ignored.
<tr><td>Priority<td>This is a very rough control for determining how far up or down the load order a plugin should go. Plugins with equal priority will be compared as normal by the sorting algorithm, but plugins with a larger priority value will load later in the load order than plugins with a smaller priority value, unless the former depends on the latter or the latter is explicity told to load after the former. Plugins have a default priority of <code>0</code>.
<tr><td>Requirements<td>This is a list of files that are required by the current plugin for it to function correctly. BOSS will refuse to sort your load order if any of the listed files are missing, and will instead display an error message detailing the problem.
<tr><td>Requirements<td>This is a list of files that are required by the current plugin for it to function correctly. BOSS will refuse to sort your load order if any of the listed files are missing, and will instead display an error message detailing the problem.
<p>Any file, not just plugins, can be listed here, and each file has three sub-fields:
<ul>
<li>The <var>filename</var> is the path, relative to the game's Data folder, of the file to be checked for. This sub-field is required.
@@ -238,7 +237,7 @@ This documentation is a work in progress, covering an application that is also s
<li>The <var>type</var> is fairly self-explanatory, and is used to provide messages of varying severity with appropriate emphasis in BOSS's report.
<li>The <var>content</var> is the actual message text.
<li>The <var>condition</var> is, like for the corresponding file sub-field, used to determine if the message should be displayed. If left blank, the message is displayed.
<li>The <var>language</var> is the language BOSS runs in that the message will be displayed for. For example, if the message language is set to <code>English</code> and BOSS is running in German, then the message will not be displayed. If left unspecified, the message will be shown no matter what language BOSS is running in.
<li>The <var>language</var> is the language BOSS runs in that the message will be displayed for. For example, if the message language is set to <code>English</code> and BOSS is running in German, then the message will not be displayed. If left unspecified, the message will be shown no matter what language BOSS is running in.
</ul>
<p>If a message's condition determines that the message should be displayed, but the language is specified and doesn't match the language BOSS is running in, then the message will not be displayed. However, if the condition determines the message should not be displayed and the language matches the language BOSS is running in, the message will still not be displayed.
<tr><td>Bash Tags<td>A list of Bash Tags. These are used by the <abbr title="Wrye Bash, Wrye Flash or Wrye Flash NV">Wrye *ash</abbr> utilities when generating a Bashed Patch. BOSS's metadata includes Bash Tag addition and removal suggestions, and any Bash Tags that came with the plugin are also displayed.
@@ -285,7 +284,7 @@ This documentation is a work in progress, covering an application that is also s
<tr><td>BOSS Folder Name<td>The sub-folder which BOSS uses to store the game's files in. Each game must be given a unique sub-folder.
<tr><td>Master File<td>The game's main master file. This is specified as it must load before all other plugins. Note that Skyrim-based games will always load Skyrim.esm first, so this column must always be set to <q>Skyrim.esm</q> for such games.
<tr><td id="settingsMasterlistURL">Online Masterlist URL<td>The URL of the online masterlist that BOSS uses to update its local copy. If set to an empty string, masterlist updating will be skipped.
<tr><td>Install Path<td>The path to the game's folder, in which the Data folder lies.
<tr><td>Install Path<td>The path to the game's folder, in which the Data folder lies.
<tr><td>Install Path Registry Key<td>The registry key, in <code>HKEY_LOCAL_MACHINE</code>, that contains the install path of the game. This may be used to obtain the install path of a game the first time BOSS runs for it.
</table>
<p>Note that for Skyrim, multiple copies or Total Conversions will all edit the same <code>plugins.txt</code> file, and so they lack the level of independence that is achievable for other games.
docs/Doxyfile
+1784
View File
File diff suppressed because it is too large Load Diff
docs/api_index.dox
+20
View File
@@ -0,0 +1,20 @@
/**
@mainpage
@author WrinklyNinja
@version 3.0.0
@copyright The BOSS API is distributed under the GNU General Public License v3.0. For the full text of the license, see the Licenses.txt file included in the source archive.
@section intro_sec 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.
All further API documentation is contained within the documentation for api.h.
@section credit_sec 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 by WrinklyNinja in C/C++ and makes use of the <a href="http://code.google.com/p/yaml-cpp/">yaml-cpp</a> and <a href="http://github.com/WrinklyNinja/libloadorder/">libloadorder</a> libraries and some of the <a href="http://www.boost.org/">Boost</a> libraries.
*/
src/api/api.h
+240 -96
View File
@@ -21,6 +21,29 @@
<http://www.gnu.org/licenses/>.
*/
/**
@file api.h
@brief This file contains the API frontend.
@note The BOSS 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 BOSS 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 BOSS 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().
*/
#ifndef __BOSS_API_H__
#define __BOSS_API_H__
@@ -66,142 +89,240 @@ extern "C"
// Types
////////////////////////
// All API strings are uint8_t* strings encoded in UTF-8. Strings returned
// by the API should not have their memory freed by the client: the API will
// clean up after itself.
// All API numbers and error codes are unsigned int integers.
// Abstracts the definition of BOSS's internal state while still providing
// type safety across the API.
/**
@brief A structure that holds all game-specific data used by the BOSS 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 _boss_db_int * boss_db;
// boss_message structure gives the type of message and it contents.
/**
@brief A structure that holds the type of a message and the message string itself.
@var boss_message::type The type of the message, specified using one of the message type codes given below.
@var boss_message::message The message string itself.
*/
typedef struct {
unsigned int type;
const char * message;
} boss_message;
// The following are the possible codes that the API can return.
BOSS_API extern const unsigned int boss_ok;
BOSS_API extern const unsigned int boss_error_liblo_error;
BOSS_API extern const unsigned int boss_error_file_write_fail;
BOSS_API extern const unsigned int boss_error_parse_fail;
BOSS_API extern const unsigned int boss_error_condition_eval_fail;
BOSS_API extern const unsigned int boss_error_regex_eval_fail;
BOSS_API extern const unsigned int boss_error_no_mem;
BOSS_API extern const unsigned int boss_error_invalid_args;
BOSS_API extern const unsigned int boss_error_no_tag_map;
BOSS_API extern const unsigned int boss_error_path_not_found;
BOSS_API extern const unsigned int boss_error_no_game_detected;
/*********************//**
@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.
*************************/
///@{
BOSS_API extern const unsigned int boss_ok; ///< The function completed successfully.
BOSS_API extern const unsigned int boss_error_liblo_error; ///< There was an error in performing a load order operation.
BOSS_API extern const unsigned int boss_error_file_write_fail; ///< A file could not be written to.
BOSS_API extern const unsigned int boss_error_parse_fail; ///< There was an error parsing the file.
BOSS_API extern const unsigned int boss_error_condition_eval_fail; ///< There was an error evaluating the conditionals in a metadata file.
BOSS_API extern const unsigned int boss_error_regex_eval_fail; ///< There was an error evaluating the regular expressions in a metadata file.
BOSS_API extern const unsigned int boss_error_no_mem; ///< The API was unable to allocate the required memory.
BOSS_API extern const unsigned int boss_error_invalid_args; ///< Invalid arguments were given for the function.
BOSS_API extern const unsigned int boss_error_no_tag_map; ///< No Bash Tag map has been generated yet.
BOSS_API extern const unsigned int boss_error_path_not_found; ///< A file or folder path could not be found.
BOSS_API extern const unsigned int boss_error_no_game_detected; ///< The given game could not be found.
/**
@brief An error occurred during a Subversion operation.
@details This code should never be seen client-side, as the API does not use any Subversion processes, but is provided in the interests of completeness and in case of library bugs returning it.
*/
BOSS_API extern const unsigned int boss_error_subversion_error;
/**
@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.
*/
BOSS_API extern const unsigned int boss_return_max;
// The following are the games identifiers used by the API.
BOSS_API extern const unsigned int boss_game_tes4;
BOSS_API extern const unsigned int boss_game_tes5;
BOSS_API extern const unsigned int boss_game_fo3;
BOSS_API extern const unsigned int boss_game_fonv;
///@}
// BOSS message types.
BOSS_API extern const unsigned int boss_message_say;
BOSS_API extern const unsigned int boss_message_warn;
BOSS_API extern const unsigned int boss_message_error;
/*******************//**
@name Game Codes
@brief Used with boss_create_db().
***********************/
///@{
BOSS_API extern const unsigned int boss_game_tes4; ///< Game code for The Elder Scrolls IV: Oblivion.
BOSS_API extern const unsigned int boss_game_tes5; ///< Game code for The Elder Scrolls V: Skyrim.
BOSS_API extern const unsigned int boss_game_fo3; ///< Game code for Fallout 3.
BOSS_API extern const unsigned int boss_game_fonv; ///< Game code for Fallout: New Vegas.
///@}
/***************************//**
@name Message Type Codes
@brief Used with the boss_message structure.
*******************************/
///@{
BOSS_API extern const unsigned int boss_message_say; ///< Denotes a generic note-type message.
BOSS_API extern const unsigned int boss_message_warn; ///< Denotes a warning message.
BOSS_API extern const unsigned int boss_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.
*/
BOSS_API extern const unsigned int boss_message_tag;
// BOSS message languages.
BOSS_API extern const unsigned int boss_lang_any;
BOSS_API extern const unsigned int boss_lang_english;
BOSS_API extern const unsigned int boss_lang_spanish;
BOSS_API extern const unsigned int boss_lang_russian;
///@}
// BOSS plugin cleanliness codes.
BOSS_API extern const unsigned int boss_needs_cleaning_no;
BOSS_API extern const unsigned int boss_needs_cleaning_yes;
BOSS_API extern const unsigned int boss_needs_cleaning_unknown;
/*******************************//**
@name Message Language Codes
@brief Used with boss_eval_lists().
***********************************/
///@{
BOSS_API extern const unsigned int boss_lang_any; ///< Tells the API to select messages of any language.
BOSS_API extern const unsigned int boss_lang_english; ///< Tells the API to preferentially select English messages.
BOSS_API extern const unsigned int boss_lang_spanish; ///< Tells the API to preferentially select Spanish messages.
BOSS_API extern const unsigned int boss_lang_russian; ///< Tells the API to preferentially select Russian messages.
///@}
/*********************************//**
@name Plugin Cleanliness Codes
@brief Used with boss_get_dirty_message().
*************************************/
///@{
BOSS_API extern const unsigned int boss_needs_cleaning_no; ///< Denotes that the plugin queried does not need cleaning.
BOSS_API extern const unsigned int boss_needs_cleaning_yes; ///< Denotes that the plugin queried needs cleaning.
BOSS_API extern const unsigned int boss_needs_cleaning_unknown; ///< Denotes that the API is unable to determine whether or not the plugin queried needs cleaning.
///@}
//////////////////////////////
// Error Handling Functions
//////////////////////////////
/*********************************//**
@name Error Handling Functions
*************************************/
///@{
// Outputs a string giving the details of the last time an error or
// warning return code was returned by a function. The string exists
// until this function is called again or until boss_cleanup is called.
/**
@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.
*/
BOSS_API unsigned int boss_get_error_message (const char ** const message);
// Frees memory allocated to error string.
/**
@brief Frees the memory allocated to the last error details string.
*/
BOSS_API void boss_cleanup ();
///@}
//////////////////////////////
// Version Functions
//////////////////////////////
// Returns whether this version of BOSS supports the API from the given
// BOSS version. Abstracts BOSS API stability policy away from clients.
/**************************//**
@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.
*/
BOSS_API bool boss_is_compatible (const unsigned int versionMajor, const unsigned int versionMinor, const unsigned int versionPatch);
// Returns the version string for this version of BOSS.
// The string exists until this function is called again or until
// CleanUpAPI is called.
/**
@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.
*/
BOSS_API unsigned int boss_get_version (unsigned int * const versionMajor, unsigned int * const versionMinor, unsigned int * const versionPatch);
////////////////////////////////////
// Lifecycle Management Functions
////////////////////////////////////
/***************************************//**
@name Lifecycle Management Functions
*******************************************/
///@{
// Explicitly manage database lifetime. Allows clients to free memory when
// they want/need to. clientGame sets the game the DB is for, and dataPath
// is the path to that game's Data folder, and is case-sensitive if the
// underlying filesystem is case-sensitive. This function also checks that
// plugins.txt and loadorder.txt (if they both exist) are in sync. If
// dataPath == NULL then the API will attempt to detect the data path of
// the specified game.
/**
@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.
*/
BOSS_API unsigned int boss_create_db (boss_db * const db, const unsigned int clientGame, const char * const gamePath);
// Destroys the given DB, freeing any memory allocated as part of its use.
/**
@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.
*/
BOSS_API void boss_destroy_db (boss_db db);
///@}
///////////////////////////////////
// Database Loading Functions
///////////////////////////////////
// Loads the masterlist and userlist from the paths specified.
/***********************************//**
@name Database Loading Functions
***************************************/
///@{
//
// Can be called multiple times. On error, the database is unchanged.
// Paths are case-sensitive if the underlying filesystem is case-sensitive.
// masterlistPath and userlistPath are files.
/**
@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. The API supports loading both v3 and v2.3 masterlists.
@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. The API only upports loading v3 userlists.
@returns A return code.
*/
BOSS_API unsigned int boss_load_lists (boss_db db, const char * const masterlistPath,
const char * const userlistPath);
// Evaluates all conditional lines and regex mods the loaded masterlist.
// This exists so that Load() doesn't need to be called whenever the mods
// installed are changed. Evaluation does not take place unless this function
// is called. Repeated calls re-evaluate the masterlist from scratch each time,
// ignoring the results of any previous evaluations. Paths are case-sensitive
// if the underlying filesystem is case-sensitive.
/**
@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.
*/
BOSS_API unsigned int boss_eval_lists (boss_db db, const unsigned int language);
///@}
//////////////////////////
// DB Access Functions
//////////////////////////
// Returns an array of the Bash Tags encounterred when loading the masterlist
// and userlist, and the number of tags in the returned array. The array and
// its contents are static and should not be freed by the client.
// The indices of the tagMap are each tag's UID.
/**********************************//**
@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 boss_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 boss_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.
*/
BOSS_API unsigned int boss_get_tag_map (boss_db db, char *** const tagMap, size_t * const numTags);
// Returns arrays of Bash Tag UIDs for Bash Tags suggested for addition and removal
// by BOSS's masterlist and userlist, and the number of tags in each array.
// The returned arrays are valid until the db is destroyed or until the Load
// function is called. The arrays should not be freed by the client. modName is
// case-insensitive. If no Tags are found for an array, the array pointer (*tagIds)
// will be NULL. The userlistModified bool is true if the userlist contains Bash Tag
// suggestion message additions.
/**
@brief Outputs the Bash Tags suggested for addition and removal by the database for the given plugin.
@details 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.
@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.
*/
BOSS_API unsigned int boss_get_plugin_tags (boss_db db, const char * const plugin,
unsigned int ** const tags_added,
size_t * const numTags_added,
@@ -209,24 +330,47 @@ BOSS_API unsigned int boss_get_plugin_tags (boss_db db, const char * const plugi
size_t * const numTags_removed,
bool * const 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.
/**
@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 boss_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.
*/
BOSS_API unsigned int boss_get_plugin_messages (boss_db db, const char * const plugin,
boss_message ** const messages,
size_t * const numMessages);
// Outputs the first warning message found for the given plugin that warns about dirty edits, and also whether the plugin should be cleaned or not, or if BOSS doesn't know (ie. no message, in which case *message == NULL). needsCleaning is one of the plugin cleanliness codes above.
/**
@brief Determines the database's knowledge of a plugin's dirtiness.
@details Outputs the first message associated with the specified plugin that is about dirty edits, and also 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 message A pointer to the message outputted.
@param needsCleaning A pointer to a plugin cleanliness code.
@returns A return code.
*/
// Outputs the first warning message found for the given plugin that warns about dirty edits (ie. no message, in which case *message == NULL). needsCleaning is one of the plugin cleanliness codes above.
BOSS_API unsigned int boss_get_dirty_message (boss_db db, const char * const plugin,
boss_message * const message,
unsigned int * const needsCleaning);
// 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
// conditions, in order to create the Wrye Bash taglist. outputFile is the path to use
// for output. If outputFile already exists, it will only be overwritten if overwrite is true.
/**
@brief 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.
@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.
*/
BOSS_API unsigned int boss_write_minimal_list (boss_db db, const char * const outputFile, const bool overwrite);
///@}
#ifdef __cplusplus
}