Crate loadorder_ffi

libloadorder-ffi

libloadorder-ffi provides a C API wrapper around libloadorder, a free software library for manipulating the load order and active status of plugins for the following games:

• TES III: Morrowind
• TES IV: Oblivion
• TES V: Skyrim
• TES V: Skyrim Special Edition
• Fallout 3
• Fallout: New Vegas
• Fallout 4

Variable Types

libloadorder-ffi uses character strings and integers for information input/output.

• All strings are null-terminated byte character strings encoded in UTF-8.
• All return, game and load order method 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.

Thread Safety

libloadorder-ffi is thread-safe. Reading and writing data for a single game handle is protected by mutual exclusion, and error messages are stored thread-locally.

Game handles operate independently, so using more than one game handle for a single game across multiple threads is not advised, as filesystem changes made when writing data are not atomic and data races may occur under such usage.

Data Caching

libloadorder caches plugin data to improve performance. Each game handle has its own unique cache, and change detection is performed whenever an API function that takes a game handle is called. If changes are detected, the necessary data are reloaded before the function operates on the data.

Edits made to a plugin will only be detected if they that plugin's timestamp changes. If edits are made and the timestamp is unchanged, the changes can only be detected by destroying the existing game handle and creating a new game handle to use.

Plugin Validity

Where libloadorder functions take one or more plugin filenames, it checks that these filenames correspond to valid plugins. libloadorder defines a valid plugin as one that:

• Ends with .esp, .esm, .esp.ghost or .esm.ghost.

• Contains a header record with:

  • The correct type (TES3 for Morrowind, TES4 otherwise).
  • A size that is not larger than the total file size.
  • Subrecords with sizes that do not together sum to larger than the expected total subrecords size.

This definition is substantially more permissive than games or other utilities may be for performance reasons, and because libloadorder uses no plugin data beyond the header record, so later corruption or invalid data would not affect its behaviour.

This permissivity does allow more strictly invalid plugins to be positioned in the load order and activated, which may cause game issues, but protecting against such circumstances is beyond the scope of libloadorder.

Valid Active Plugin Lists

Any active plugin list that is set using libloadorder must be valid, ie. it must meet all the following conditions:

• Contains only installed plugins.
• Contains no duplicate entries.
• Contains no more than 255 plugins.
• If a Skyrim or Fallout 4 load order, contains Skyrim.esm or Fallout4.esm respectively.
• If a Skyrim load order and Update.esm is installed, contains Update.esm.

Libloadorder is less strict when loading active plugin lists. If loading a Skyrim or Fallout 4 list and the relevant main master file is missing, it will be inferred to load first.

Similarly, if Update.esm is installed but not in the active list, it will be inferred to load after all other master files.

Valid Load Orders

Any load order that is set using libloadorder must be valid, ie. it must meet all the following conditions:

• Contains only installed plugins.
• Contains no duplicate entries.
• Loads all master files before all plugin files. Master bit flag value, rather than file extension, is checked.
• For Skyrim or Fallout 4, the first plugin in the load order must be Skyrim.esm or Fallout4.esm respectively.

Statics

LIBLO_ERROR_FILE_NOT_FOUND	The specified file could not be found.
LIBLO_ERROR_FILE_NOT_UTF8	The specified file is not encoded in UTF-8.
LIBLO_ERROR_FILE_PARSE_FAIL	There was an error parsing a plugin file.
LIBLO_ERROR_FILE_RENAME_FAIL	A file could not be renamed.
LIBLO_ERROR_INTERNAL_LOGIC_ERROR	The library encountered an error that should not have been possible to encounter.
LIBLO_ERROR_INVALID_ARGS	Invalid arguments were given for the function.
LIBLO_ERROR_IO_ERROR	An unknown I/O error occurred. This is used when the I/O error kind doesn't fit another error code.
LIBLO_ERROR_IO_PERMISSION_DENIED	Permission denied while trying to access a filesystem path.
LIBLO_ERROR_POISONED_THREAD_LOCK	A thread lock was poisoned.
LIBLO_ERROR_TEXT_DECODE_FAIL	Text expected to be encoded in Windows-1252 could not be decoded to UTF-8.
LIBLO_ERROR_TEXT_ENCODE_FAIL	A plugin filename contains characters that do not have Windows-1252 code points, or a character string contains a null character.
LIBLO_ERROR_TIMESTAMP_WRITE_FAIL	The modification date of a file could not be set.
LIBLO_GAME_FNV	Game code for Fallout: New Vegas.
LIBLO_GAME_FO3	Game code for Fallout 3.
LIBLO_GAME_FO4	Game code for Fallout 4.
LIBLO_GAME_TES3	Game code for The Elder Scrolls III: Morrowind.
LIBLO_GAME_TES4	Game code for The Elder Scrolls IV: Oblivion.
LIBLO_GAME_TES5	Game code for The Elder Scrolls V: Skyrim.
LIBLO_GAME_TES5SE	Game code for The Elder Scrolls V: Skyrim Special Edition.
LIBLO_METHOD_ASTERISK	The asterisk load order system, used by Fallout 4 and Skyrim Special Edition.
LIBLO_METHOD_TEXTFILE	he game handle is using the textfile-based load order system. Skyrim uses this system.
LIBLO_METHOD_TIMESTAMP	The game handle is using the timestamp-based load order system. Morrowind, Oblivion, Fallout 3 and Fallout: New Vegas all use this system.
LIBLO_OK	Success return code.
LIBLO_RETURN_MAX	Matches the value of the highest-numbered return code.
LIBLO_WARN_LO_MISMATCH	There is a mismatch between the files used to keep track of load order.

Functions

lo_create_handle⚠	Initialise a new game handle.
lo_destroy_handle⚠	Destroy an existing game handle.
lo_fix_plugin_lists⚠	Fix up the text file(s) used by the load order and active plugins systems.
lo_free_string⚠	Free memory allocated to string output.
lo_free_string_array⚠	Free memory allocated to string array output.
lo_get_active_plugins⚠	Gets the list of currently active plugins.
lo_get_error_message⚠	Get the message for the last error or warning encountered.
lo_get_indexed_plugin⚠	Get filename of the plugin at a specific load order position.
lo_get_load_order⚠	Get the current load order.
lo_get_load_order_method⚠	Get which method is used for the load order.
lo_get_plugin_active⚠	Checks if a given plugin is active.
lo_get_plugin_position⚠	Get the load order position of a plugin.
lo_get_version⚠	Gets the library version.
lo_load_current_state⚠	Load the current load order state, discarding any previously held state.
lo_set_active_plugins⚠	Sets the list of currently active plugins.
lo_set_load_order⚠	Set the load order.
lo_set_plugin_active⚠	Activates or deactivates a given plugin.
lo_set_plugin_position⚠	Set the load order position of a plugin.

Type Definitions

lo_game_handle

A structure that holds all game-specific data used by libloadorder.