From 5ed55acb8aec2442f987b5ed2a18cb17dcd81360 Mon Sep 17 00:00:00 2001 From: dokutan <54861821+dokutan@users.noreply.github.com> Date: Thu, 1 Apr 2021 00:11:19 +0200 Subject: [PATCH] Remove unused code, add API documentation --- README.md | 2 +- doc/api.md | 23 +++++++++ makefile | 1 + src/macrodevice-lua.cpp | 112 ++++++++++++++++++---------------------- 4 files changed, 74 insertions(+), 64 deletions(-) create mode 100644 doc/api.md diff --git a/README.md b/README.md index d0d9f4c..ba3d547 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ macrodevice-lua -c your-config.lua -f ### Lua config -To handle the incoming events and execute commands a Lua script is needed. For the details look at ``examples/example.lua``. +To handle the incoming events and execute commands a Lua script is needed. For the details look at ``examples/example.lua`` and ``doc/api.md``. To easily create the input handler function for your lua script, edit ``examples/create-config.lua`` and execute ``` diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 0000000..724fe26 --- /dev/null +++ b/doc/api.md @@ -0,0 +1,23 @@ +# macrodevice Lua API + +## ``macrodevice.drop_root(uid, gid)`` +uid: integer, gid: integer + +Drops root permissions by setting the real and effective user and group ids to uid and gid. + +Returns 1 in case of failure, otherwise 0 + +## ``macrodevice.drop_root(username)`` +username: string + +Drops root permissions by setting the real and effective user and group ids to uid and gid of the user with the given username. + +Returns 1 in case of failure, otherwise 0 + +## ``macrodevice.open(backend, settings, event_handler)`` +backend: string, settings: table, event_handler: function + +Opens the device specified by the settings table using the given backend. event_handler is the callback function that gets called for every incoming event. + +## ``macrodevice.version`` +A string containing the version of macrodevice. \ No newline at end of file diff --git a/makefile b/makefile index c1879e2..5a17351 100644 --- a/makefile +++ b/makefile @@ -58,6 +58,7 @@ install: mkdir $(DOC_DIR)/macrodevice | true cp ./examples/example.lua $(DOC_DIR)/macrodevice cp ./doc/backends.md $(DOC_DIR)/macrodevice + cp ./doc/api.md $(DOC_DIR)/macrodevice uninstall: rm -f $(BIN_DIR)/macrodevice-lua diff --git a/src/macrodevice-lua.cpp b/src/macrodevice-lua.cpp index a4ce7b1..4bfd57d 100644 --- a/src/macrodevice-lua.cpp +++ b/src/macrodevice-lua.cpp @@ -42,7 +42,6 @@ extern "C" #include } - // version defined in makefile #ifndef VERSION_STRING #define VERSION_STRING "undefined" @@ -71,51 +70,35 @@ extern "C" #include "backends/macrodevice-xindicator.h" #endif - -// global variables -//********************************************************************** -std::vector device_threads; // threads for event handling -int thread_number = 0; // used to identify threads TODO! remove? -std::mutex mutex_lua, mutex_open_device; - // help message //********************************************************************** -void print_help() -{ - std::cout << "macrodevice-lua options:\n\n"; - std::cout << "-h --help\tprint this message\n"; - std::cout << "-c --config\tlua file to be loaded (required)\n"; - std::cout << "-f --fork\tfork into the background\n"; - std::cout << "-u --user\tuser id to drop privileges to (requires -g)\n"; - std::cout << "-g --group\tgroup id to drop privileges to (requires -u)\n"; - std::cout << "\nLicensed under the GNU GPL v3 or later\n"; -} +const std::string help_message = R"(macrodevice-lua options: +-h --help print this message +-c --config lua file to be loaded (required) +-f --fork fork into the background +-u --user user id to drop privileges to (requires -g) +-g --group group id to drop privileges to (requires -u) -// lua stack dump for debugging purposes -//********************************************************************** -void stack_dump( lua_State *l ) -{ - std::cout << "------\n"; - for( int i = lua_gettop( l ); i > 0; i-- ){ - - std::cout << i << "\t" << lua_typename( l, lua_type( l, i ) ); - - if( lua_isnumber( l, i ) ){ - std::cout << "\t" << lua_tonumber( l, i ) << "\n"; - } else if( lua_isstring( l, i ) ){ - std::cout << "\t" << lua_tostring( l, i ) << "\n"; - } else{ - std::cout << "\n"; - } - - } - std::cout << "------\n"; -} +Licensed under the GNU GPL v3 or later +)"; -// drop root privileges to a specified user and group id +// global variables //********************************************************************** +/// Threads for event handling, one thread per device +std::vector device_threads; + +/// Used as an identifier for each thread +int thread_number = 0; + +/// Mutex for interactions with the Lua state +std::mutex mutex_lua; + +/// This mutex gets lock when opening a new device +std::mutex mutex_open_device; + +/// Drop root permissions to the given user and group id int drop_root( uid_t uid, gid_t gid ) { // important: set gid before uid @@ -139,9 +122,9 @@ int drop_root( uid_t uid, gid_t gid ) return 0; } - -// template function to handle the device management and macro execution +// functions //********************************************************************** +/// Thread function to open a specified device and pass the incoming events to the callback function template< class T > int run_macros( T device, lua_State *L, std::map settings, std::string callback_registry_key ) { // pass settings to the device object @@ -221,9 +204,8 @@ template< class T > int run_macros( T device, lua_State *L, std::map lock( mutex_open_device ); @@ -359,6 +340,25 @@ static int lua_open_device( lua_State *L ) return 0; } +/// Makes the macrodevice table available to the Lua state +inline void lua_register_macrodevice( lua_State *L ) +{ + lua_newtable( L ); // create new table + + lua_pushstring( L, "open" ); // index + lua_pushcfunction( L, lua_open_device ); // value + lua_settable( L, -3 ); // table[index] = value, pops index and value + + lua_pushstring( L, "drop_root" ); // index + lua_pushcfunction( L, lua_drop_root ); // value + lua_settable( L, -3 ); // table[index] = value, pops index and value + + lua_pushstring( L, "version" ); // index + lua_pushstring( L, VERSION_STRING ); // value + lua_settable( L, -3 ); // table[index] = value, pops index and value + + lua_setglobal( L, "macrodevice" ); // name table, pops table from stack +} // main function //********************************************************************** @@ -387,7 +387,7 @@ int main( int argc, char *argv[] ) switch( c ) { case 'h': - print_help(); + std::cout << help_message; return 0; break; case 'c': @@ -436,21 +436,7 @@ int main( int argc, char *argv[] ) // make macrodevice functions available to Lua - lua_newtable( L ); // create new table - - lua_pushstring( L, "open" ); // index - lua_pushcfunction( L, lua_open_device ); // value - lua_settable( L, -3 ); // table[index] = value, pops index and value - - lua_pushstring( L, "drop_root" ); // index - lua_pushcfunction( L, lua_drop_root ); // value - lua_settable( L, -3 ); // table[index] = value, pops index and value - - lua_pushstring( L, "version" ); // index - lua_pushstring( L, VERSION_STRING ); // value - lua_settable( L, -3 ); // table[index] = value, pops index and value - - lua_setglobal( L, "macrodevice" ); // name table, pops table from stack + lua_register_macrodevice( L ); { // lock lua mutex