LuaService.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2015 Raritan Inc. All rights reserved.
 */
 
/**
 * Lua-Service
 *
 * Lua-Service is a service that you can use to upload and execute a Lua script.
 *
 * When the service is starting, a cleanup is done first. That means
 * still running scripts will be killed and it will be tested for which script
 * an option is given. If something does not match, the script or option
 * will be deleted.
 *
 * After the service is launched, ScriptOptions::autoStart will be evaluated for
 * each script. If the flag is \c true, the script is going to be executed with a
 * delay of Environment::autoStartDelay milliseconds.
 *
 * You can download and upload a script with Manager::getScript() and Manager::setScript().
 * On upload, if the script name is already taken, the old script will be overwritten.
 * Otherwise, a new script will be created.
 *
 * Use Manager::startScript() to execute a Lua script and Manager::terminateScript() to stop a script.
 * If ScriptOptions::autoRestart is set to \c true, the script restarts automatically
 * after it has exited.
 *
 * To get the output for a script use Manager::getScriptOutput(). The output
 * is limited to Environment::outputBufferSize bytes and mapped to a virtual
 * address. On the first query, call the method with starting address zero. After
 * that use the returned address \c nAddr for the next request.
 *
 * A script can be called with arguments, see ScriptOptions and Manager::startScriptWithArgs().
 */
module luaservice {
 
    /**
     * A structure that describes the state of a script.
     *
     * When a script is uploaded the new #execState is #STAT_NEW, #exitType and
     * #exitStatus are not valid.
     *
     * When the #execState is changed to #STAT_TERMINATED, #exitType and #exitStatus
     * will be set.
     */
    structure ScriptState {
 
        /** Execution state of a script */
        enumeration ExecState {
            STAT_NEW,          ///< the script never ran (after uploading or system (re)start)
            STAT_RUNNING,      ///< script is running
            STAT_TERMINATED,   ///< script is terminated
            STAT_RESTARTING    ///< script is terminated and restarts after the Environment::restartInterval
        };
 
        /** Describes the type of #exitStatus */
        enumeration ExitType {
            EXIT_CODE,     ///< #exitStatus is an exit code
            SIGNAL         ///< #exitStatus is a signal
        };
 
        ExecState execState;   ///< execution state of the script
        ExitType  exitType;    ///< type of exit status
        int       exitStatus;  ///< exit code or signal
    };
 
    /** Script options */
    structure ScriptOptions {
        map <string, string> defaultArgs;   ///< default arguments passed to the Lua script
        boolean autoStart;                  ///< starts a script after system booting
        boolean autoRestart;                ///< restarts a script after termination or crash
    };
 
    /**
     * Environment represents two kinds of information:
     * - limit (l)
     * - current status (cs)
     *
     * A limit of zero means no limit. The unit of size
     * is byte. The unit of time is millisecond.
     */
    structure Environment {
        int maxScriptMemoryGrowth;///< maximum virtual memory growth per script (l)
        int maxAmountOfScripts;   ///< number of scripts that can be stored (l)
        int amountOfScripts;      ///< number of scripts that are stored (cs)
        int maxScriptSize;        ///< maximum size of a script file (l)
        int maxAllScriptSize;     ///< maximum size of all script files (l)
        int allScriptSize;        ///< size of all script files (cs)
        int outputBufferSize;     ///< output buffer size per script (l)
        int restartInterval;      ///< minimum delay to next (re)start (cs)
        int autoStartDelay;       ///< minimum delay to auto-start a script
    };
 
    /**
     * There is a single manager instance.
     */
    interface Manager {
 
        /** Error codes */
        constant int NO_ERROR                          =  0; ///< no error
        constant int ERR_INVALID_NAME                  =  1; ///< script name is invalid
        constant int ERR_NO_SUCH_SCRIPT                =  2; ///< script name not found
        constant int ERR_MAX_SCRIPT_NUMBERS_EXCEEDED   =  3; ///< maximum amount of stored script files is reached
        constant int ERR_MAX_SCRIPT_SIZE_EXCEEDED      =  4; ///< maximum size of a script file is reached
        constant int ERR_MAX_ALL_SCRIPT_SIZE_EXCEEDED  =  5; ///< maximum size of all script files is reached
        constant int ERR_NOT_TERMINATED                =  6; ///< script is not terminated
        constant int ERR_NOT_RUNNING                   =  7; ///< script is not running
        constant int ERR_INVALID_ADDR                  =  8; ///< address parameter is wrong
        constant int ERR_TOO_MANY_ARGUMENTS            = 10; ///< too many arguments
        constant int ERR_ARGUMENT_NOT_VALID            = 11; ///< the argument has one or more invalid characters
 
        /**
         * Upload a script to instance
         *
         * If there is a script with the same name the new script will replace
         * the existing script (script must be in \c STAT_NEW or \c STAT_TERMINATED).
         *
         * @param name    The name of the script file
         * @param script  The script file packed in a string
         * @param options The options for the script
         *
         * @return #NO_ERROR                           if OK
         * @return #ERR_INVALID_NAME                   if script name is invalid
         * @return #ERR_MAX_SCRIPT_SIZE_EXCEEDED       if the size of the new script is greater than the maximum file size
         * @return #ERR_MAX_ALL_SCRIPT_SIZE_EXCEEDED   if maximum size of all script files is reached
         * @return #ERR_MAX_SCRIPT_NUMBERS_EXCEEDED    if maximum amount of script files is reached
         * @return #ERR_NOT_TERMINATED                 if trying to replace a running script
         */
        int setScript(in string name, in string script, in ScriptOptions options);
 
        /**
         * To download a script file.
         *
         * @param name The name of an existing script
         *
         * @return #NO_ERROR             if OK
         * @return #ERR_INVALID_NAME     if script name is invalid
         * @return #ERR_NO_SUCH_SCRIPT   if there is no script with the name
         */
        int getScript(in string name, out string script);
 
        /**
         * Returns all script names in a string vector.
         *
         * If there are no scripts the vector is empty.
         *
         * @return A vector with all script names.
         */
        vector<string> getScriptNames();
 
        /**
         * Deletes a script.
         *
         * @param name The name of the script
         *
         * @return #NO_ERROR             if OK
         * @return #ERR_INVALID_NAME     if script name is invalid
         * @return #ERR_NO_SUCH_SCRIPT   if there is no script with the name
         * @return #ERR_NOT_TERMINATED   if trying to delete a running script
         */
        int deleteScript(in string name);
 
        /**
         * Sets new options for a script.
         *
         * @param name    The name of the script
         * @param options The new options
         *
         * @return #NO_ERROR                      if OK
         * @return #ERR_INVALID_NAME              if script name is invalid
         * @return #ERR_NO_SUCH_SCRIPT            if there is no script with the name
         * @return #ERR_TOO_MANY_ARGUMENTS        if the size of the map is to big
         * @return #ERR_ARGUMENT_NOT_VALID        if a string in the arguments is not valid
         */
        int setScriptOptions(in string name, in ScriptOptions options);
 
        /**
         * Returns the options for a script.
         *
         * @param name    The name of the script
         * @param options The options of the script
         *
         * @return #NO_ERROR             if OK
         * @return #ERR_INVALID_NAME     if script name is invalid
         * @return #ERR_NO_SUCH_SCRIPT   if there is no script with the name
         */
        int getScriptOptions(in string name, out ScriptOptions options);
 
        /**
         * To query the environment information.
         *
         * @return the environment information
         */
        Environment getEnvironment();
 
        /**
         * To get output from a script as a string
         *
         * The output is stored in a string buffer with a defined size. The buffer is addressable with an
         * (virtual) address. The address will be increased every time the buffer gets filled.
         *
         * To get the output for the first time just call with address zero.
         * Use the returned \c nAddr in following calls.
         *
         * If \c iAddr is negative the last n bytes will be returned, e.g. -9 returns the last 9 characters.
         * If \c iAddr is zero the whole available buffer will be returned.
         * If \c iAddr is positive the returned buffer starts at this address.
         * If \c iAddr is equal to \c nAddr there is no data available.
         * If \c iAddr and \c oAddr are not equal there was data lost (exception: first call with zero).
         *
         * @param name  The name of the script
         * @param iAddr The virtual start address where the returned output should begin
         * @param oAddr The virtual address from where the string starts
         * @param nAddr The virtual address for the next query
         * @param more  A boolean which indicates if there is more data available
         *
         * @return #NO_ERROR                      if OK
         * @return #ERR_INVALID_NAME              if file name is invalid
         * @return #ERR_NO_SUCH_SCRIPT            if there is no script with the name
         * @return #ERR_INVALID_ADDR              if \c iAddr is negative and its absolute value is greater than the limit
         */
        int getScriptOutput(in string name, in long iAddr, out long oAddr, out long nAddr, out string oString, out boolean more);
 
        /**
         * Clear the output buffer of a script.
         *
         * @param name The name of the script
         *
         * @return #NO_ERROR                      if OK
         * @return #ERR_INVALID_NAME              if file name is invalid
         * @return #ERR_NO_SUCH_SCRIPT            if there is no script with the name
         */
        int clearScriptOutput(in string name);
 
        /**
         * Start a script
         *
         * @return #NO_ERROR             if OK
         * @return #ERR_INVALID_NAME     if file name is invalid
         * @return #ERR_NO_SUCH_SCRIPT   if there is no script with the name
         * @return #ERR_NOT_TERMINATED   if the script is running or restarting
         */
        int startScript(in string name);
 
        /**
         * Start a script with arguments
         *
         * The method starts a Lua script. You can add arguments depending on the Lua script.
         * The arguments will override the default arguments. All arguments are stored in a global table
         * called \c ARGS in Lua.
         *
         * @return #NO_ERROR                      if OK
         * @return #ERR_INVALID_NAME              if file name is invalid
         * @return #ERR_NO_SUCH_SCRIPT            if there is no script with the name
         * @return #ERR_NOT_TERMINATED            if the script is running or restarting
         * @return #ERR_TOO_MANY_ARGUMENTS        if the size of the map is to big
         * @return #ERR_ARGUMENT_NOT_VALID        if a string in the arguments is not valid
         */
        int startScriptWithArgs(in string name, in map<string, string> arguments);
 
        /**
         * Stop a script
         *
         * This method stops a running or restarting script. After terminating, ScriptOptions::autoRestart will
         * \e not be evaluated.
         *
         * @return #NO_ERROR             if OK
         * @return #ERR_INVALID_NAME     if file name is invalid
         * @return #ERR_NO_SUCH_SCRIPT   if there is no script with the name
         * @return #ERR_NOT_RUNNING      if the script is not running or restarting
         */
        int terminateScript(in string name);
 
        /**
         * Returns the state for a single script.
         *
         * @param name  The script name
         * @param state The state of the script
         *
         * @return #NO_ERROR             if OK
         * @return #ERR_INVALID_NAME     if file name is invalid
         * @return #ERR_NO_SUCH_SCRIPT   if there is no script with the name
         */
        int getScriptState(in string name, out ScriptState state);
 
 
        /**
         * Returns the state for all scripts. If the map is empty then there are no scripts on the machine.
         *
         * @return A map with names as keys and states as values for all available scripts.
         */
        map<string, ScriptState> getScriptStates();
    };
 
}