594e1d9812
Fixed a bug that caused the host to not respond to any commands when a module is present. CmdExecutor::loadMods() had a malformed 'for' loop that caused the command executor to infinite loop. Also re-formed the way the external command loaders (modules) are constructed. Instead, the modules are also intialized at the same time as the internal command loader. The CmdExecutor::loadModFile() and CmdExecutor::unloadModFile() functions now load and unload modules via the module name instead of the path to the module main file. The documentation for ASYNC_ENABLE_MOD and ASYNC_DISABLE_MOD updated to reflect this change. Also part of the module contruction re-form, it fixed a bug that caused the command loaders to operate in a thread different from the command executor. CmdExecutor::loadMods() was refactored into cmdExecutor::buildCmdLoaders(), added the internal command loader to it and have it so this function gets called only when the command executor successfully moves to it's own thread. Fixed a bug that caused the session to crash only when a module is present. It turns out the qobject_cast() function used in CmdExecutor::loadModFile() only pulled the surface class ModCommandLoader so any attempt to access the base class functions from CommandLoader caused the session to crash so to fix this, ModCommandLoader was merged into CommandLoader. The Command loader documentation and test module were updated to reflect this change. Fixed a bug that auto removed any modules that were installed when the host is restarted. The issue was in TCPServer::syncModPath() that used the modules's main file without a suffix when the file did indeed have a suffix, causing the function to think the module no longer exists and remove all of it's files from the host file system. The original intent for this function was to keep the module database table in sync with what was actually in the host file system. It was decided that this is not necessary so the function was removed altogether. Also changed up the way the module files are deleted. The TCPSever class will now use the module name instead of the path to the module's main library file and will use a single use ModDeleteTimer for each module that was requested to be deleted instead of a single continuous timer constantly checking for modules to delete. The ls_cmds command will now list the commands in alphabetical order of the command names and fixed a bug with the -find option that would display nothing if an exact match to any text in the table could not be found. Fixed a bug found in the deployed application that would segmentation fault on startup due to certain library files being included in the deployed installation directory. Updated the linux_build.sh script to include only libsqlite, libQT5, libssl and libicu files. It will no longer blindly copy all library files from the dev machine and then remove files the setup script thinks the application might or might not need. Any module built on import rev1 will simply not work and no attempt will be made to make it work so the host new minimum import rev is now rev2. this update is mustly just bug fixes; nothing that would require any client behaviour changes so just the host patch is bumped. 1.0.0 --> 1.0.1
5.9 KiB
2.1 Command Loaders
Every command object (Command_Objects) defined in the host must have a unique command name atteched to it. Command loaders have the very simple job of creating these objects via the requested command name. The host use command names to determine if the current session is allowed to load them or not and command loaders are used to relate those command names with the command objects themselves.
When the host CmdExecutor determines that it can indeed load the commands based on the command names, it will then assign command ids to all command objects that were successfully built from the command loader. Each command loader can have a total of 256 command objects. Internally defined commands start at command id: 256 - 512 and module defined commands start at command id: 513 and up.
2.2 CommandLoader Class
The CommandLoader class itself defines a few virtual functions that make the command name to command object relationship possible:
ExternCommand *cmdObj(QString cmdName)
This function is used to create the ExternCommand object associated with the command name passed by the QString parameter and return a pointer to it. If the command name is invalid, doesn't exists or fails to contruct the object for some reason, return nullptr. The command object can have a parent or orphaned, just make sure it never gets deleted at any time; the host will handle that externally. It is safe to use the command loader itself as the parent.
QStringList cmdList()
This function needs to return a QStringList of all of command names that this loader can actually load when the cmdObj() function is called. the host uses this list to enforce user access filtering of the command objects using the built in permission id system.
QStringList pubCmdList()
This funtion needs to work the same way as cmdList() except the loader can this function to name any commands that can be accessed by un-logged in clients. aka, public commands. Note: the commands listed here must also be listed in cmdList() or else the commands will not get loaded at all.
QStringList rankExemptList()
The loader can use this function to return a QStringList of all of command names that need to be exempt from host ranking system (section 5.2). Commands listed here will be allowed to load/run regardless of what host rank the current user is.
bool hostRevOk(quint64 rev)
When the host calls this function, it will pass the import rev that it supports in the quint64 parameter. Use this function to return if this rev is acceptable or not. The host will give up loading the module if the rev is not acceptable.
quint64 rev()
Use this function to return the import rev that this module supports. The host will decide if it is acceptable or not.
QString lastError()
The host will call this function if a command object fails to load or if hostRevOk() returns false so it can log the error message returned by it to the host database.
void modPath(QString path)
The host will call this function after successfully negotiating the import rev. The QString parameter passed into this will have the absolute path to the module's install directory. You can use this path to load additional files that came bundled the module.
void aboutToDelete()
The host will call this function before calling deleteLater(). All command objects at this point should already be deleted, use this opportunity to free any resources related to the loader itself. Unload any additional lib files that the loader may have used.
Here's a few notes to consider when using this class:
- Never self delete or explicitly delete the command loader or any of the command objects it sucessfully creates at any time. The host
CmdExecutorobject will handle the life cycle of these objects externally. - Command ids are assigned in alphabetical order of the command names returned by
cmdList(). The command ids will remain constant as long as the command names also remain constant. All clients are recommended to rely on the ASYNC_ADD_CMD and ASYNC_RM_CMD async commands to keep track of the command ids and names (section 6.2).
2.3 Modules
External commands are added to the host through modules based on low level QT plugins. Each module must define a CommandLoader class in it's main library file and the file itself must be named 'main' with a library file extension that the host platform supports (main.so, main.dll, etc..). Modules are installed using the add_mod internal command that supports extracting the module's library files from an archive file (.zip, .tar, etc...) or just a single library file (.so, .dll, .a, etc...).
In the case of an archive file, it extracts all of the files from the the archive file while preserving the directory tree so you can bundle additional files that your module depends on but as mentioned before, a library file named 'main' must be present on the base directory.
A template and an example of a module can be found in the 'modules/Tester' directory of the source code of this project. It provides the command.cpp and command.h files that contain the CommandLoader and ExternCommand classes that are needed to create a module. Also feel free to copy the command.cpp and command.h files from 'src/commands' if you prefer.
2.4 The Import Rev
The import rev is a single digit versioning system for external modules that help the host determine if it is compatible with the module it is attempting to load or not. Bumps to this rev is usually triggered by significant changes to the CommandLoader class. Compatibility negotiation is a two way communication between the host CmdExecutor and the module itself using the virtual functions described in section 2.2.