new file mode 100644
@@ -0,0 +1,140 @@
+--[[
+
+ SWUpdate IPC Lua Module Interface.
+
+ Interface specification for the Lua IPC module.
+ See: bindings/lua_swupdate.c
+
+ Copyright (C) 2022, Siemens AG
+ Author: Christian Storm <christian.storm@siemens.com>
+
+ SPDX-License-Identifier: GPL-2.0-or-later
+
+--]]
+
+---@diagnostic disable: unused-local
+-- luacheck: no unused args
+
+
+--- SWUpdate IPC Lua Module.
+--- @class lua_swupdate
+local lua_swupdate = {}
+
+
+--- Get local IPv4 network interface(s) information.
+--
+-- The returned Table contains the network interface names
+-- as keys and a space-separated IP address and subnet mask
+-- as values, e.g., {['eth0']="192.168.1.1 255.255.255.0"}.
+--
+--- @return table<string, string>
+lua_swupdate.ipv4 = function() end
+
+
+--- @class lua_swupdate.RECOVERY_STATUS
+--- Lua equivalent of `RECOVERY_STATUS` as in `include/swupdate_status.h`.
+--- @type table<string, number>
+lua_swupdate.RECOVERY_STATUS = {
+ IDLE = 0,
+ START = 1,
+ RUN = 2,
+ SUCCESS = 3,
+ FAILURE = 4,
+ DOWNLOAD = 5,
+ DONE = 6,
+ SUBPROCESS = 7,
+ PROGRESS = 8
+}
+
+
+--- @class lua_swupdate.sourcetype
+--- Lua equivalent of `sourcetype` as in `include/swupdate_status.h`.
+--- @type table<string, number>
+lua_swupdate.sourcetype = {
+ SOURCE_UNKNOWN = 0,
+ SOURCE_WEBSERVER = 1,
+ SOURCE_SURICATTA = 2,
+ SOURCE_DOWNLOADER = 3,
+ SOURCE_LOCAL = 4,
+ SOURCE_CHUNKS_DOWNLOADER = 5
+}
+
+
+--- Lua equivalent of `struct progress_msg` as in `include/progress_ipc.h`.
+--- @class progress_msg
+--- @field status number Update status, one of `lua_swupdate.RECOVERY_STATUS`'s values
+--- @field download number Downloaded data percentage
+--- @field source number Interface that triggered the update, one of `lua_swupdate.sourcetype`'s values
+--- @field nsteps number Total number of steps
+--- @field step number Current step
+--- @field percent number Percentage done in current step
+--- @field artifact string Name of image to be installed
+--- @field handler string Name of running Handler
+--- @field info string Additional information about installation
+
+
+--- @class lua_swupdate.progress
+--- SWUpdate progress socket binding.
+--
+-- The returned Class Table contains methods to
+-- interact with SWUpdate's progress socket.
+--
+lua_swupdate.progress = function()
+ return {
+ --- Connect to SWUpdate's progress socket.
+ --
+ --- @param self lua_swupdate.progress This `lua_swupdate.progress` instance
+ --- @return number | nil # The connection handle or nil in case of error
+ --- @return nil | string # nil or an error message in case of error
+ connect = function(self) end,
+
+ --- Receive data from SWUpdate's progress socket.
+ --
+ --- @param self lua_swupdate.progress This `lua_swupdate.progress` instance
+ --- @return lua_swupdate.progress | progress_msg # This `lua_swupdate.progress` instance on error or the received progress message
+ --- @return nil # nil in case of error
+ receive = function(self) end,
+
+ --- Close connection to SWUpdate's progress socket.
+ --
+ --- @param self lua_swupdate.progress This `lua_swupdate.progress` instance
+ --- @return lua_swupdate.progress # This `lua_swupdate.progress` instance
+ close = function(self) end,
+ }
+end
+
+
+--- @class lua_swupdate.control
+--- SWUpdate control socket binding.
+--
+-- The returned Class Table contains methods to
+-- interact with SWUpdate's control socket.
+--
+lua_swupdate.control = function()
+ return {
+ --- Connect to SWUpdate's control socket.
+ --
+ --- @param self lua_swupdate.control This `lua_swupdate.control` instance
+ --- @return number | nil # Connection handle or nil in case of error
+ --- @return nil | string # nil or an error message in case of error
+ connect = function(self) end,
+
+ --- Write to connected SWUpdate control socket.
+ --
+ --- @param self lua_swupdate.control This `lua_swupdate.control` instance
+ --- @param data string Chunk data to write to SWUpdate's control socket
+ --- @return boolean | nil # true or nil in case of error
+ --- @return nil | string # nil or an error message in case of error
+ write = function(self, data) end,
+
+ --- Close connection to SWUpdate's control socket.
+ --
+ --- @param self lua_swupdate.control This `lua_swupdate.control` instance
+ --- @return boolean | nil # true or nil in case of error
+ --- @return nil | string # nil or an error message in case of error
+ close = function(self) end,
+ }
+end
+
+
+return lua_swupdate
@@ -20,11 +20,16 @@ currently ``lua_swupdate.so.0.1``, is provided.
Lua Language Binding
--------------------
-The Lua language binding is realized in terms of the ``swupdate`` module that
-defines three bindings, namely for the control interface, the progress
+The Lua language binding is realized in terms of the ``lua_swupdate`` module
+that defines three bindings, namely for the control interface, the progress
interface, and a convenience function yielding a table holding all local
network interfaces including their IP addresses and submasks.
+The ``lua_swupdate`` Lua module interface specification that details what
+functionality is made available by ``bindings/lua_swupdate.c`` is found
+in ``bindings/lua_swupdate.lua``. It serves as reference, for mocking
+purposes, and type checking thanks to the EmmyLua-inspired annotations.
+
Note that, depending on the filesystem location of the Lua binding's shared
library, Lua's ``package.cpath`` may have to be adapted by setting the
environment variable ``LUA_CPATH``, modifying ``package.cpath`` prior to
@@ -35,7 +40,7 @@ instead of ``require('lua_swupdate')``.
Control Interface
.................
-The ``swupdate`` module's control interface binding conveniently makes
+The ``lua_swupdate`` module's control interface binding conveniently makes
:doc:`SWUpdate's socket-based control API <swupdate-ipc>` available to pure Lua.
The binding is captured in the ``swupdate_control`` object that is returned
@@ -86,7 +91,7 @@ The following example snippet illustrates how to use the control interface bindi
Progress Interface
..................
-The ``swupdate`` module's progress interface binding conveniently makes
+The ``lua_swupdate`` module's progress interface binding conveniently makes
:doc:`SWUpdate's socket-based progress API <progress>` available to pure Lua.
The binding is captured in the ``swupdate_progress`` object that is returned
@@ -109,6 +114,6 @@ socket.
IPv4 Interface
..............
-For convenience, the ``swupdate`` module provides the ``ipv4()`` method
+For convenience, the ``lua_swupdate`` module provides the ``ipv4()`` method
returning a table holding the local network interfaces as the table's keys and
their space-separated IP addresses plus subnet masks as respective values.
Add the `lua_swupdate` IPC Lua module interface specification. It serves as reference, for mocking purposes, and type checking thanks to the EmmyLua-inspired annotations. Signed-off-by: Christian Storm <christian.storm@siemens.com> --- bindings/lua_swupdate.lua | 140 ++++++++++++++++++++++++++++++++++++++ doc/source/bindings.rst | 15 ++-- 2 files changed, 150 insertions(+), 5 deletions(-) create mode 100644 bindings/lua_swupdate.lua