Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
LuaService.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2015 Raritan Inc. All rights reserved.
4 */
5
6/**
7 * Lua-Service
8 *
9 * Lua-Service is a service that you can use to upload and execute a Lua script.
10 *
11 * When the service is starting, a cleanup will be happend at first. That means
12 * still running scripts will be killed and it will be tested for which script is
13 * an option given. Does here something not match, then the script or the option
14 * will be deleted.
15 *
16 * After the service is launched, the option 'autoRestart' will be for any script
17 * evaluated. If the flag is 'true', the script is going to be executed with a
18 * short delay (Environment->autoStartDelay).
19 *
20 * You can download and upload a script with the commands getScript() and setScript().
21 * When on uploading the script name is not present a new script will be created.
22 * If the name is already taken, then the old script will be overwritten.
23 *
24 * Use startScript() to execute a lua script and terminateScript() to stop a script.
25 * If the option 'autoRestart' is set to 'true', then the script starts automatically
26 * after it has exited.
27 *
28 * To get the output for a script use the command getScriptOutput(). The output
29 * is limited to 'Environment->outputBufferSize' bytes and mapped to a virtual
30 * address. On the first query call the method with starting address zero. After
31 * that use the returned address 'nAddr' for the next request.
32 *
33 * A script can be called with arguments (see options and startWithArgs).
34 */
35module luaservice {
36
37 /**
38 * A structure that descripts the state of a script.
39 *
40 * When a script is uploaded the new execState is STAT_NEW. exitCode and
41 * signal is not valid.
42 *
43 * When the execState is changing to STAT_TERMINATED then exitCode and signal
44 * will be set.
45 */
46 structure ScriptState {
47
48 /** execution state for a scripts */
49 enumeration ExecState {
50 STAT_NEW, ///< the script never ran (after uploading or system (re)start)
51 STAT_RUNNING, ///< script state is running
52 STAT_TERMINATED, ///< script state is terminated
53 STAT_RESTARTING ///< script is terminated and restarts after 'restart interval'
54 };
55
56 /** Descripts the type of exitStatus */
57 enumeration ExitType {
58 EXIT_CODE, ///< exitStatus is an exit code
59 SIGNAL ///< exitStatus is a signal
60 };
61
62 ExecState execState; ///< execution state of the script
63 ExitType exitType; ///< type of exit code
64 int exitStatus; ///< exit status or signal
65 };
66
67 /** some script options */
68 structure ScriptOptions {
69 map <string, string> defaultArgs; ///< default arguments are passed to the lua script
70 boolean autoStart; ///< starts a script after system booting
71 boolean autoRestart; ///< restarts a script after termination or crash
72 };
73
74 /**
75 * The struct represents two kinds of information:
76 * - limit (l)
77 * - current status (cs)
78 * Is a limit set to zero then there is no limit set. The unit of size
79 * is byte. The unit of interval is millisecond.
80 */
81 structure Environment {
82 int maxScriptMemoryGrowth;///< maximum virtual memory growth per script (l)
83 int maxAmountOfScripts; ///< number of scripts that can be stored (l)
84 int amountOfScripts; ///< number of scripts that are stored (cs)
85 int maxScriptSize; ///< maximum size of a script file (l)
86 int maxAllScriptSize; ///< maximum size of all script files (l)
87 int allScriptSize; ///< size of all script files (cs)
88 int outputBufferSize; ///< output buffer size per script (l)
89 int restartInterval; ///< minimum delay to next (re)start (cs)
90 int autoStartDelay; ///< minimum delay to 'autoStart' a script
91 };
92
93 /**
94 * There is a single manager instance.
95 */
96 interface Manager {
97
98 /** Error codes */
99 constant int NO_ERROR = 0; ///< no Error
100 constant int ERR_INVALID_NAME = 1; ///< script name is invalid
101 constant int ERR_NO_SUCH_SCRIPT = 2; ///< script name not found
102 constant int ERR_MAX_SCRIPT_NUMBERS_EXCEEDED = 3; ///< maximum amount of stored script files is reached
103 constant int ERR_MAX_SCRIPT_SIZE_EXCEEDED = 4; ///< maximum size of a script file is reached
104 constant int ERR_MAX_ALL_SCRIPT_SIZE_EXCEEDED = 5; ///< maximum size of all script files is reached
105 constant int ERR_NOT_TERMINATED = 6; ///< script is not terminated
106 constant int ERR_NOT_RUNNING = 7; ///< script is not running
107 constant int ERR_INVALID_ADDR = 8; ///< address parameter is wrong
108 constant int ERR_TOO_MANY_ARGUMENTS = 10; ///< too many arguments
109 constant int ERR_ARGUMENT_NOT_VALID = 11; ///< the argument has one or more invalid characters
110
111 /**
112 * Upload a script to instance
113 *
114 * If there is a script with the same name the new script will replace
115 * the existing script (script must be in STAT_NEW or STAT_TERMINATED).
116 *
117 * @param name The name of the script file
118 * @param script The script file packed in a string
119 * @param options Options that can be set or not
120 *
121 * @return NO_ERROR if OK
122 * @return ERR_INVALID_NAME if script name is invalid
123 * @return ERR_MAX_SCRIPT_SIZE_EXCEEDED if the size of the new script is greater then the maximum file size
124 * @return ERR_MAX_ALL_SCRIPT_SIZE_EXCEEDED if maximum size of all script files is reached
125 * @return ERR_MAX_SCRIPT_NUMBERS_EXCEEDED if maximum amount of script files is reached
126 * @return ERR_NOT_TERMINATED if try to replace a running script
127 */
128 int setScript(in string name, in string script, in ScriptOptions options);
129
130 /**
131 * To download a script file to user.
132 *
133 * @param name The name of an existing script
134 *
135 * @return NO_ERROR if OK
136 * @return ERR_INVALID_NAME if script name is invalid
137 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
138 */
139 int getScript(in string name, out string script);
140
141 /**
142 * Returns all script names in a string vector.
143 *
144 * If there are no scripts the vector is empty.
145 *
146 * @return A vector with all script names.
147 */
148 vector<string> getScriptNames();
149
150 /**
151 * Deletes a script.
152 *
153 * @param name The name of the script
154 *
155 * @return NO_ERROR if OK
156 * @return ERR_INVALID_NAME if script name is invalid
157 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
158 * @return ERR_NOT_TERMINATED if try to delete a running script
159 */
160 int deleteScript(in string name);
161
162 /**
163 * Sets new options for a script.
164 *
165 * @param name The name of the script
166 * @param options The new options
167 *
168 * @return NO_ERROR if OK
169 * @return ERR_INVALID_NAME if script name is invalid
170 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
171 * @return ERR_TOO_MANY_ARGUMENTS if the size of the map is to big
172 * @return ERR_ARGUMENT_NOT_VALID if a string in the arguments is not
173 */
174 int setScriptOptions(in string name, in ScriptOptions options);
175
176 /**
177 * Returns the options for a script.
178 *
179 * @param name The name of the script
180 * @param options The return value
181 *
182 * @return NO_ERROR if OK
183 * @return ERR_INVALID_NAME if script name is invalid
184 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
185 */
186 int getScriptOptions(in string name, out ScriptOptions options);
187
188 /**
189 * To query the environment information.
190 *
191 * @return a struct with the environment information
192 */
193 Environment getEnvironment();
194
195 /**
196 * To get output from a script as a string
197 *
198 * The output is stored in a string buffer with a defined size. The buffer is addressable with an
199 * (virtual) address. The address will be increased ervery time when the buffer will be filled.
200 *
201 * To get the output for the first time just call with address zero and then use the returned nAddr
202 * argument.
203 *
204 * If iAddr is negative then the last n bytes will be returned, e.g. -9 returns the last 9 characters.
205 * If iAddr is zero then the whole available buffer will be returned.
206 * If iAddr is positive then the returned buffer starts at this address.
207 * If iAddr is equal to nAddr then there is no data available
208 * If iAddr and oAddr is not equal then there were data lost (execption: first call with zero).
209 *
210 * @param name The name of the script
211 * @param iAddr The virtual start address where the returned output should begin.
212 * @param oAddr The virtual address from where the string starts.
213 * @param nAddr The virtual address for the next query.
214 * @param more A boolean whitch indicates if there is more data available.
215 *
216 * @return NO_ERROR if OK
217 * @return ERR_INVALID_NAME if file name is invalid
218 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
219 * @return ERR_INVALID_ADDR if iAddr is negative and the absolute value of parameter iAddr is greater as the limit
220 */
221 int getScriptOutput(in string name, in long iAddr, out long oAddr, out long nAddr, out string oString, out boolean more);
222
223 /**
224 * Clear the output buffer of a script.
225 *
226 * @param name The name of the script
227 *
228 * @return NO_ERROR if OK
229 * @return ERR_INVALID_NAME if file name is invalid
230 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
231 */
232 int clearScriptOutput(in string name);
233
234 /**
235 * To start a script
236 *
237 * The function starts a lua script.
238 *
239 * @return NO_ERROR if OK
240 * @return ERR_INVALID_NAME if file name is invalid
241 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
242 * @return ERR_NOT_TERMINATED if the script is running or restarting
243 */
244 int startScript(in string name);
245
246 /**
247 * To start a script with arguments
248 *
249 * The function starts a lua script. Additionally you can add arguments which are available from the
250 * lua script. This args will override the default arguments. All args are stored in a global table
251 * called ARGS in lua.
252 *
253 * @return NO_ERROR if OK
254 * @return ERR_INVALID_NAME if file name is invalid
255 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
256 * @return ERR_NOT_TERMINATED if the script is running or restarting
257 * @return ERR_TOO_MANY_ARGUMENTS if the size of the map is to big
258 * @return ERR_ARGUMENT_NOT_VALID if a string in the arguments is not valid
259 */
260 int startScriptWithArgs(in string name, in map<string, string> arguments);
261
262 /**
263 * To stop a script
264 *
265 * This command stops a running or restarting script. After terminating the option autorestart will
266 * not be evaluated.
267 *
268 * @return NO_ERROR if OK
269 * @return ERR_INVALID_NAME if file name is invalid
270 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
271 * @return ERR_NOT_RUNNING if the script is not running or restarting
272 */
273 int terminateScript(in string name);
274
275 /**
276 * Returns the state for a single script.
277 *
278 * @param name The script name
279 * @param state The state of the script
280 *
281 * @return NO_ERROR if OK
282 * @return ERR_INVALID_NAME if file name is invalid
283 * @return ERR_NO_SUCH_SCRIPT if there is no script with the name
284 */
285 int getScriptState(in string name, out ScriptState state);
286
287
288 /**
289 * Returns the state for all scripts. If the map is empty then there are no scripts on the machine.
290 *
291 * @return A map<string name, ScriptState state> with name and state for all available scripts.
292 */
293 map<string, ScriptState> getScriptStates();
294 };
295
296}
luaservice::Manager
There is a single manager instance.
Definition LuaService.idl:96
luaservice::Manager::ERR_NO_SUCH_SCRIPT
constant int ERR_NO_SUCH_SCRIPT
script name not found
Definition LuaService.idl:101
luaservice::Manager::ERR_NOT_TERMINATED
constant int ERR_NOT_TERMINATED
script is not terminated
Definition LuaService.idl:105
luaservice::Manager::ERR_MAX_SCRIPT_NUMBERS_EXCEEDED
constant int ERR_MAX_SCRIPT_NUMBERS_EXCEEDED
maximum amount of stored script files is reached
Definition LuaService.idl:102
luaservice::Manager::getScriptStates
map< string, ScriptState > getScriptStates()
Returns the state for all scripts.
luaservice::Manager::NO_ERROR
constant int NO_ERROR
Error codes.
Definition LuaService.idl:99
luaservice::Manager::setScriptOptions
int setScriptOptions(in string name, in ScriptOptions options)
Sets new options for a script.
luaservice::Manager::getScriptNames
vector< string > getScriptNames()
Returns all script names in a string vector.
luaservice::Manager::ERR_NOT_RUNNING
constant int ERR_NOT_RUNNING
script is not running
Definition LuaService.idl:106
luaservice::Manager::ERR_INVALID_ADDR
constant int ERR_INVALID_ADDR
address parameter is wrong
Definition LuaService.idl:107
luaservice::Manager::ERR_INVALID_NAME
constant int ERR_INVALID_NAME
script name is invalid
Definition LuaService.idl:100
luaservice::Manager::getScript
int getScript(in string name, out string script)
To download a script file to user.
luaservice::Manager::ERR_MAX_SCRIPT_SIZE_EXCEEDED
constant int ERR_MAX_SCRIPT_SIZE_EXCEEDED
maximum size of a script file is reached
Definition LuaService.idl:103
luaservice::Manager::setScript
int setScript(in string name, in string script, in ScriptOptions options)
Upload a script to instance.
luaservice::Manager::getScriptOutput
int getScriptOutput(in string name, in long iAddr, out long oAddr, out long nAddr, out string oString, out boolean more)
To get output from a script as a string.
luaservice::Manager::terminateScript
int terminateScript(in string name)
To stop a script.
luaservice::Manager::ERR_TOO_MANY_ARGUMENTS
constant int ERR_TOO_MANY_ARGUMENTS
too many arguments
Definition LuaService.idl:108
luaservice::Manager::getScriptState
int getScriptState(in string name, out ScriptState state)
Returns the state for a single script.
luaservice::Manager::startScript
int startScript(in string name)
To start a script.
luaservice::Manager::deleteScript
int deleteScript(in string name)
Deletes a script.
luaservice::Manager::getScriptOptions
int getScriptOptions(in string name, out ScriptOptions options)
Returns the options for a script.
luaservice::Manager::startScriptWithArgs
int startScriptWithArgs(in string name, in map< string, string > arguments)
To start a script with arguments.
luaservice::Manager::getEnvironment
Environment getEnvironment()
To query the environment information.
luaservice::Manager::ERR_MAX_ALL_SCRIPT_SIZE_EXCEEDED
constant int ERR_MAX_ALL_SCRIPT_SIZE_EXCEEDED
maximum size of all script files is reached
Definition LuaService.idl:104
luaservice::Manager::ERR_ARGUMENT_NOT_VALID
constant int ERR_ARGUMENT_NOT_VALID
the argument has one or more invalid characters
Definition LuaService.idl:109
luaservice::Manager::clearScriptOutput
int clearScriptOutput(in string name)
Clear the output buffer of a script.
luaservice
Lua-Service.
Definition LuaService.idl:35
luaservice::Environment
The struct represents two kinds of information:
Definition LuaService.idl:81
luaservice::Environment::maxAmountOfScripts
int maxAmountOfScripts
number of scripts that can be stored (l)
Definition LuaService.idl:83
luaservice::Environment::restartInterval
int restartInterval
minimum delay to next (re)start (cs)
Definition LuaService.idl:89
luaservice::Environment::allScriptSize
int allScriptSize
size of all script files (cs)
Definition LuaService.idl:87
luaservice::Environment::amountOfScripts
int amountOfScripts
number of scripts that are stored (cs)
Definition LuaService.idl:84
luaservice::Environment::maxAllScriptSize
int maxAllScriptSize
maximum size of all script files (l)
Definition LuaService.idl:86
luaservice::Environment::autoStartDelay
int autoStartDelay
minimum delay to 'autoStart' a script
Definition LuaService.idl:90
luaservice::Environment::outputBufferSize
int outputBufferSize
output buffer size per script (l)
Definition LuaService.idl:88
luaservice::Environment::maxScriptSize
int maxScriptSize
maximum size of a script file (l)
Definition LuaService.idl:85
luaservice::Environment::maxScriptMemoryGrowth
int maxScriptMemoryGrowth
maximum virtual memory growth per script (l)
Definition LuaService.idl:82
luaservice::ScriptOptions
some script options
Definition LuaService.idl:68
luaservice::ScriptOptions::autoRestart
boolean autoRestart
restarts a script after termination or crash
Definition LuaService.idl:71
luaservice::ScriptOptions::autoStart
boolean autoStart
starts a script after system booting
Definition LuaService.idl:70
luaservice::ScriptOptions::defaultArgs
map< string, string > defaultArgs
default arguments are passed to the lua script
Definition LuaService.idl:69
luaservice::ScriptState
A structure that descripts the state of a script.
Definition LuaService.idl:46
luaservice::ScriptState::ExitType
ExitType
Descripts the type of exitStatus.
Definition LuaService.idl:57
luaservice::ScriptState::SIGNAL
@ SIGNAL
exitStatus is a signal
Definition LuaService.idl:59
luaservice::ScriptState::EXIT_CODE
@ EXIT_CODE
exitStatus is an exit code
Definition LuaService.idl:58
luaservice::ScriptState::execState
ExecState execState
execution state of the script
Definition LuaService.idl:62
luaservice::ScriptState::exitType
ExitType exitType
type of exit code
Definition LuaService.idl:63
luaservice::ScriptState::exitStatus
int exitStatus
exit status or signal
Definition LuaService.idl:64
luaservice::ScriptState::ExecState
ExecState
execution state for a scripts
Definition LuaService.idl:49
luaservice::ScriptState::STAT_RESTARTING
@ STAT_RESTARTING
script is terminated and restarts after 'restart interval'
Definition LuaService.idl:53
luaservice::ScriptState::STAT_TERMINATED
@ STAT_TERMINATED
script state is terminated
Definition LuaService.idl:52
luaservice::ScriptState::STAT_NEW
@ STAT_NEW
the script never ran (after uploading or system (re)start)
Definition LuaService.idl:50
luaservice::ScriptState::STAT_RUNNING
@ STAT_RUNNING
script state is running
Definition LuaService.idl:51