shellmatta/api/shellmatta.h

/*
 * Copyright (c) 2019 - 2024 Stefan Strobel <stefan.strobel@shimatta.net>
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */

/**
 * @file    shellmatta.h
 * @brief   API definition of the Shellmatta terminal implementation
 * @author  Stefan Strobel <stefan.strobel@shimatta.net>
 */

/**
 * @addtogroup shellmatta_api Shellmatta API description
 * @{
 */

#ifndef _SHELLMATTA_H_
#define _SHELLMATTA_H_

#include <stdint.h>
#include <stdbool.h>

/* global defines */


/*
 * Define the printf format specifier for all GCC versions > 3.3
 * This will let the compiler know that shellmatta_printf() is a function taking printf-like format specifiers.
 */
#ifndef SHELLMATTA_ATTR_FORMAT
#   if ((__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 3)))
#       define SHELLMATTA_ATTR_FORMAT(fmt, args) __attribute__((__format__(__printf__, fmt, args)))
#   else
#       define SHELLMATTA_ATTR_FORMAT(fmt, args)
#   endif
#else
#   define SHELLMATTA_ATTR_FORMAT(fmt, args)
#endif

/**
 * @brief definition of a shellmatta handle
 */
typedef void* shellmatta_handle_t;

/**
 * @brief definition of shellmatta return codes
 */
typedef enum
{
    SHELLMATTA_OK           = 0u,   /**< everything is OK               */
    SHELLMATTA_ERROR            ,   /**< error occured                  */
    SHELLMATTA_CONTINUE         ,   /**< the function is not over       */
    SHELLMATTA_USE_FAULT        ,   /**< parameter error - wrong usage  */
    SHELLMATTA_DUPLICATE        ,   /**< duplicate command              */
    SHELLMATTA_BUSY                 /**< command is busy keep calling   */
} shellmatta_retCode_t;

/**
 * @brief definition of shellmatta insert mode
 */
typedef enum
{
    SHELLMATTA_MODE_INSERT      = 0u,   /**< insert mode    */
    SHELLMATTA_MODE_OVERWRITE   ,       /**< overwrite mode */
} shellmatta_mode_t;

/**
 * @brief definition of shellmatta optionparser agument type
 */
typedef enum
{
    SHELLMATTA_OPT_ARG_NONE     = 0u,   /**< no argument expected   */
    SHELLMATTA_OPT_ARG_REQUIRED,        /**< argument is required   */
    SHELLMATTA_OPT_ARG_OPTIONAL,        /**< argument is optional   */
} shellmatta_opt_argtype_t;

/**
 * @brief definition of shellmatta optionparser agument type
 */
typedef struct
{
    const char                  *paramLong; /**< long parameter string      */
    const char                  paramShort; /**< short parameter char       */
    shellmatta_opt_argtype_t    argtype;    /**< argument type expected     */
} shellmatta_opt_long_t;

/**
 * @brief definition of shellmatta optionparser structure
 */
typedef struct
{
    uint32_t    argStart;   /**< start of the arguments of the command  */
    uint32_t    offset;     /**< current offset of the option parser    */
    uint32_t    nextOffset; /**< offset of the next hunk                */
    uint32_t    len;        /**< length of the current hunk             */
} shellmatta_opt_t;

/**
 * @brief shellmatta command function definition
 * @param[in]   handle      pointer to the instance which is calling the cmd
 * @param[in]   arguments   argument string called to run this command beginning
 *                          with the command itself
 * @param[in]   length      length of the argument string
 */
typedef shellmatta_retCode_t (*shellmatta_cmdFct_t)(const shellmatta_handle_t   handle,
                                                    const char                  *arguments,
                                                    uint32_t                    length);

/**
 * @brief shellmatta write function definition
 * @param[in]   data        data to be written to the output
 * @param[in]   length      length of the data to be written
 */
typedef shellmatta_retCode_t (*shellmatta_write_t)(const char* data, uint32_t length);

#ifdef SHELLMATTA_AUTHENTICATION
/**
 * @brief user role matrix
 */
typedef struct
{
    uint32_t    userId;     /**< id of the user (!= 0)                              */
    bool        superuser;  /**< allow the user to access all commands              */
    const char  *username;  /**< name of the user role                              */
    const char  *password;  /**< password of the user role or NULL (custom auth)    */
} shellmatta_auth_user_t;

/**
 * @brief typedefinition of one line of the authentication table
 */
typedef struct
{
    const char*    cmd;           /**< command to grand access to               */
    const uint32_t *userIds;      /**< list of user ids with access to the cmd  */
    const uint32_t userIdslength; /**< length of the user list                  */
} shellmatta_auth_perm_t;

/**
 * @brief login states
 */
typedef enum
{
    SHELLMATTA_AUTH_IDLE,       /**< authentication system waits    */
    SHELLMATTA_AUTH_USERNAME,   /**< input of username              */
    SHELLMATTA_AUTH_PASSWORD    /**< input of password              */
} shellmatta_auth_state_t;

/**
 * @brief log actions - passed to the log function
 */
typedef enum
{
    SHELLMATTA_AUTH_EVENT_NONE,         /**< no event (init value)      */
    SHELLMATTA_AUTH_EVENT_LOGIN,        /**< successful login event     */
    SHELLMATTA_AUTH_EVENT_LOGIN_FAILED, /**< failed login event         */
    SHELLMATTA_AUTH_EVENT_LOGOUT,       /**< succesful logout event     */
} shellmatta_auth_log_event_t;

/**
 * @brief custom shellmatta authentication method
 * @param[in]   userId      user id to log in (name of the user role)
 * @param[in]   password    password for the login
 * @return      userId if password was correct - otherwise 0
 */
typedef shellmatta_retCode_t (*shellmatta_auth_check_t)(const uint32_t userId, const char* password);

/**
 * @brief shellmatta authentication log method - will be called whenever a login attempt is done
 * @param[in]   userId  userId to be logged in (0 on unknown user)
 * @param[in]   event   event type to be logged (e.g. successful login)
 */
typedef void (*shellmatta_auth_log_t)(const uint32_t userId, shellmatta_auth_log_event_t event);

#endif

/**
 * @brief structure of one shellmatta command
 */
typedef struct shellmatta_cmd
{
    char                    *cmd;       /**< command name                           */
    char                    *cmdAlias;  /**< command alias                          */
    char                    *helpText;  /**< help text to print in "help" command   */
    char                    *usageText; /**< usage text - printed on "help cmd"     */
    shellmatta_cmdFct_t     cmdFct;     /**< pointer to the cmd callack function    */
#ifdef SHELLMATTA_AUTHENTICATION
    shellmatta_auth_perm_t  *authLink;  /**< internally used - pointer to perm list */
#endif
    struct shellmatta_cmd   *next;      /**< pointer to next command or NULL        */
} shellmatta_cmd_t;

/**
 * @brief shellmatta ymodem cancel callback definition
 */
typedef void (*shellmatta_ymodem_cancel_t)(void);

/**
 * @brief shellmatta ymodem header receive callback definition
 * @param[in]   fileSize    file size of the file to be received
 * @param[in]   fileName    file name of the file to be received
 */
typedef void (*shellmatta_ymodem_recvHeader_t)(uint32_t fileSize, char* fileName);

/**
 * @brief shellmatta ymodem packet receive callback definition
 * @param[in]   data        received data
 * @param[in]   packetSize  size of the data in the packet
 * @param[in]   packetNum   number of the received packet
 */
typedef void (*shellmatta_ymodem_recvPacket_t)(uint8_t *data, uint32_t packetSize, uint32_t packetNum);

/**
 * @brief shellmatta ymodem transmission complete callback definition
 * @param[in]   result      #SHELLMATTA_OK
 *                          #SHELLMATTA_ERROR - missing data
 */
typedef void (*shellmatta_ymodem_complete_t)(shellmatta_retCode_t result);

/**
 * @brief state enumeration for ymodem receive state machine
 */
typedef enum
{
    SHELLMATTA_YMODEM_INACTIVE,         /**< YModem module not initialised  */
    SHELLMATTA_YMODEM_WAIT_FOR_START,   /**< waiting for start of header    */
    SHELLMATTA_YMODEM_RECEIVE_HEADER,   /**< reading header data            */
    SHELLMATTA_YMODEM_RECEIVE_DATA,     /**< reading payload                */
    SHELLMATTA_YMODEM_RECEIVE_CRC,      /**< reading crc                    */
    SHELLMATTA_YMODEM_WAIT_FOR_END      /**< wait until EOTs stop           */
} shellmatta_ymodem_state_t;

/** @brief packet structure that holds several information about its content */
typedef struct
{
    uint16_t size;          /**< site of the packet (128 or 1024)     */
    uint8_t packetNumber;   /**< packet number in this packet         */
    uint8_t* packetData;    /**< pointer to the data of this packet   */
    uint16_t crc;           /**< crc checksum in this packet          */
} shellmatta_ymodem_packet_t;

/**
 * @brief definition of shellmatta ymodem instance
 */
typedef struct
{
    shellmatta_ymodem_state_t state;                            /**< current stat of the ymodem module              */
    uint32_t byteCounter;                                       /**< internal counter for processing input data     */
    uint32_t packetCounter;                                     /**< counter of the totally received packets        */
    uint32_t totalBytesReceived;                                /**< counter of the totally received bytes          */
    uint32_t fileSize;                                          /**< size of the file received in packet 0          */
    bool pauseRequested;                                        /**< pause requested from the application           */
    uint32_t pollCyclesLeft;                                    /**< number of poll cycles left before ending       */
    shellmatta_ymodem_packet_t packet;                          /**< currently processed packet                     */
    shellmatta_ymodem_cancel_t cancelCallback;                  /**< callback to pass cancel events                 */
    shellmatta_ymodem_recvHeader_t recvHeaderCallback;          /**< callback to pass received header data          */
    shellmatta_ymodem_recvPacket_t recvPacketCallback;          /**< callback to pass received data                 */
    shellmatta_ymodem_complete_t transmissionCompleteCallback;  /**< callback to be called on a complete transfer   */
} shellmatta_ymodem_t;

#ifdef SHELLMATTA_TRANSPORT

/**
 * @brief definition of shellmatta transport layer states
 */
typedef enum
{
    SHELLMATTA_TRANSPORT_STATE_WAIT = 0u    ,   /**< wait for start of header   */
    SHELLMATTA_TRANSPORT_STATE_GET_HEADER   ,   /**< read in header             */
    SHELLMATTA_TRANSPORT_STATE_GET_PAYLOAD  ,   /**< read in payload            */
    SHELLMATTA_TRANSPORT_STATE_GET_CRC      ,   /**< read crc and process data  */
} shellmatta_transport_state_t;


/** @brief max length of a plain data payload */
#define SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH           ((uint8_t)(255))

/**
 * @brief shellmatta transport crc function definition for custom crcs
 * @param[in]   data        data to calculate the crc of
 * @param[in]   size        size of the data in bytes
 */
typedef uint32_t (*shellmatta_transport_crc_t)(const char* data, const uint32_t size);

/**
 * @brief structure of one shellmatta transport header
 */
typedef struct __attribute__((__packed__))
{
    uint8_t startOfHeader;      /** start of header field               */
    uint8_t protocolVersion;    /** protocol version of the packet      */
    uint8_t packetType;         /** type of the packet                  */
    uint8_t payloadLength;      /** length of the payload               */
    uint8_t source;             /** source of the packet                */
    uint8_t destination;        /** destination of the packet           */
    uint8_t sequenceH2S;        /** sequence counter host to shellmatta */
    uint8_t sequenceS2H;        /** sequence counter shellmatta to host */
} shellmatta_transport_header_t;

/**
 * @brief structure of one shellmatta transport packet
 */
typedef struct __attribute__((__packed__))
{
    shellmatta_transport_header_t   header;                                         /**< header of the packet   */
    char                            payload[SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH]; /**< payload of the packet  */
    uint32_t                        crc;                                            /**< crc of the packet      */
} shellmatta_transport_packet_t;

/**
 * @brief structure of one shellmatta transport layer instance
 */
typedef struct
{
    shellmatta_transport_state_t    state;              /**< current state of the transport layer reception */
    bool                            active;             /**< is transport layer communication active        */
    bool                            disableAutoFlush;   /**< enforce manual flushing                        */
    bool                            mandatory;          /**< is the transport layer enforced                */
    bool                            suspendOptional;    /**< forces the transport layer to not run optional */
    uint8_t                         sequenceH2S;        /**< sequence counter host to shellmatta            */
    uint8_t                         sequenceS2H;        /**< sequenc counter shellmatta to host             */
    uint32_t                        headerIndex;        /**< read index of the header                       */
    uint32_t                        payloadIndex;       /**< read index of the payload                      */
    uint32_t                        crcIndex;           /**< read index of the checksum                     */
    shellmatta_transport_packet_t   inPacket;           /**< buffer for the received packets                */
    shellmatta_transport_packet_t   outPacket;          /**< buffer for the sent packets                    */
    shellmatta_write_t              writeFct;           /**< shellmatta write function                      */
    shellmatta_transport_crc_t      customCrcFct;       /**< use this function to calculate crcs            */
} shellmatta_transport_layer_t;

#endif

/**
 * @brief structure of one shellmatta instance
 */
typedef struct
{
    uint32_t                        magic;              /**< magic number to check if initialized   */
    char                            *buffer;            /**< input buffer                           */
    uint32_t                        bufferSize;         /**< size of the input buffer               */
    uint32_t                        inputCount;         /**< offset of the current write operation  */
    uint32_t                        byteCounter;        /**< counter used to loop over input data   */
    uint32_t                        lastNewlineIdx;     /**< index of the lest newline              */
    uint32_t                        cursor;             /**< offset where the cursor is at          */
    uint32_t                        stdinIdx;           /**< start index of stdin in buffer         */
    uint32_t                        stdinLength;        /**< length of the stdin data               */
    char                            *historyBuffer;     /**< buffer to store the last commands      */
    uint32_t                        historyBufferSize;  /**< size of the history buffer             */
    uint32_t                        historyStart;       /**< index of the oldest stored command     */
    uint32_t                        historyEnd;         /**< index of the newest stored command     */
    uint32_t                        historyRead;        /**< index of the current search            */
    bool                            historyReadUp;      /**< flag to show the last history dir      */
    uint32_t                        tabCounter;         /**< counts the tabulator key presses       */
    uint32_t                        escapeCounter;      /**< counts the characters of an escape seq */
    char                            escapeChars[4u];    /**< buffer to save the escape characters   */
    uint32_t                        hereStartIdx;       /**< heredoc start of "<<"                  */
    uint32_t                        hereDelimiterIdx;   /**< heredoc delimiter index in input       */
    uint32_t                        hereLength;         /**< length of the heredoc delimiter        */
    bool                            echoEnabled;        /**< if true the input is printed           */
    bool                            dirty;              /**< dirty flag to show changes             */
    const char                      *prompt;            /**< prompt is printed after every command  */
    char                            delimiter;          /**< delimiter (return) to terminate a cmd  */
    shellmatta_mode_t               mode;               /**< mode of the shell                      */
    shellmatta_write_t              write;              /**< pointer to write function              */
    shellmatta_cmd_t                helpCmd;            /**< help command structure                 */
    shellmatta_cmd_t                *cmdList;           /**< pointer to the first command           */
    shellmatta_cmd_t                *continuousCmd;     /**< command to be called continuously      */
    shellmatta_cmd_t                *busyCmd;           /**< command to be polled (busy mode)       */
    bool                            cmdListIsConst;     /**< true if the #cmdList was passed during
                                                             initialization                         */
    shellmatta_opt_t                optionParser;       /**< option parser sructure                 */
    shellmatta_ymodem_t             ymodem;             /**< ymodem instance                        */
#ifdef SHELLMATTA_AUTHENTICATION
    shellmatta_auth_state_t         loginState;         /**< state variable of the login cmd        */
    shellmatta_cmd_t                loginCmd;           /**< login command structure                */
    shellmatta_cmd_t                logoutCmd;          /**< logout command structure               */
    uint32_t                        userId;             /**< user ID of the current session         */
    uint32_t                        tmpUserId;          /**< remporary user ID during input         */
    shellmatta_auth_user_t          *userPointer;       /**< pointer to the user in the user list   */
    shellmatta_auth_user_t          *userList;          /**< user list                              */
    uint32_t                        userListLength;     /**< length of the user list                */
    shellmatta_auth_perm_t          *permList;          /**< permission list                        */
    uint32_t                        permListLength;     /**< length of the permission list          */
    shellmatta_auth_check_t         checkFct;           /**< custom credential check function       */
    shellmatta_auth_log_t           logFct;             /**< auth log function                      */
#endif
#ifdef SHELLMATTA_TRANSPORT
    uint32_t                        transportBusyMark;  /**< transport processing position during
                                                             busy cmd execution                     */
    shellmatta_transport_layer_t    transportLayer;     /**< transport layer instance               */
#endif
} shellmatta_instance_t;

/**
 * @brief helper macro for the send function
 */
#ifdef SHELLMATTA_TRANSPORT
#define SHELLMATTA_WRITE(data, length)  inst->transportLayer.active == true ?                                                                   \
                                        shellmatta_transport_write((shellmatta_transport_layer_t*)&inst->transportLayer, (data), (length)) :    \
                                        inst->write((data), (length))
#else
#define SHELLMATTA_WRITE(data, length)  inst->write((data), (length))
#endif

shellmatta_retCode_t shellmatta_doInit( shellmatta_instance_t   *inst,
                                        shellmatta_handle_t     *handle,
                                        char                    *buffer,
                                        uint32_t                bufferSize,
                                        char                    *historyBuffer,
                                        uint32_t                historyBufferSize,
                                        const char              *prompt,
                                        const shellmatta_cmd_t  *cmdList,
                                        shellmatta_write_t      writeFct);

shellmatta_retCode_t shellmatta_resetShell( shellmatta_handle_t handle,
                                            bool                printPrompt);

shellmatta_retCode_t shellmatta_addCmd(     shellmatta_handle_t handle,
                                            shellmatta_cmd_t    *cmd);

shellmatta_retCode_t shellmatta_removeCmd(  shellmatta_handle_t     handle,
                                            const shellmatta_cmd_t  *cmd);

shellmatta_retCode_t shellmatta_configure(  shellmatta_handle_t handle,
                                            shellmatta_mode_t   mode,
                                            bool                echoEnabled,
                                            char                delimiter);

shellmatta_retCode_t shellmatta_processData(shellmatta_handle_t handle,
                                            char                *data,
                                            uint32_t            size);

shellmatta_retCode_t shellmatta_write(      shellmatta_handle_t handle,
                                            char                *data,
                                            uint32_t            length);

shellmatta_retCode_t shellmatta_read(       shellmatta_handle_t handle,
                                            char                **data,
                                            uint32_t            *length);

shellmatta_retCode_t shellmatta_opt(        shellmatta_handle_t handle,
                                            const char          *optionString,
                                            char                *option,
                                            char                **argument,
                                            uint32_t            *argLen);

shellmatta_retCode_t shellmatta_opt_long(   shellmatta_handle_t         handle,
                                            const shellmatta_opt_long_t *longOptions,
                                            char                        *option,
                                            char                        **argument,
                                            uint32_t                    *argLen);

#ifdef SHELLMATTA_TRANSPORT

shellmatta_retCode_t shellmatta_transport_configure(shellmatta_handle_t         handle,
                                                    bool                        mandatory,
                                                    bool                        disableAutoFlush,
                                                    shellmatta_transport_crc_t  customCrcFct);

shellmatta_retCode_t shellmatta_transport_reset(shellmatta_handle_t handle);

shellmatta_retCode_t shellmatta_transport_flush(shellmatta_handle_t handle);

#endif

#ifndef SHELLMATTA_STRIP_PRINTF
shellmatta_retCode_t shellmatta_printf(     shellmatta_handle_t handle,
                                            const char          *fmt,
                                            ...)
                                            SHELLMATTA_ATTR_FORMAT(2, 3);
#endif

#ifdef SHELLMATTA_AUTHENTICATION

shellmatta_retCode_t shellmatta_auth_init(                  shellmatta_handle_t     handle,
                                                            shellmatta_auth_user_t  *userList,
                                                            uint32_t                userListLength,
                                                            shellmatta_auth_perm_t  *permList,
                                                            uint32_t                permListLength,
                                                            bool                    customLogin,
                                                            shellmatta_auth_check_t checkFct,
                                                            shellmatta_auth_log_t   logFct);
shellmatta_retCode_t shellmatta_auth_login(                 shellmatta_handle_t     handle,
                                                            uint32_t                userId);
shellmatta_retCode_t shellmatta_auth_logout(                shellmatta_handle_t     handle);
uint32_t             shellmatta_auth_getLoggedInUserId(     shellmatta_handle_t     handle);
shellmatta_retCode_t shellmatta_auth_getLoggedInUserName(   shellmatta_handle_t     handle,
                                                            char                    *data,
                                                            uint32_t                *length);
shellmatta_retCode_t shellmatta_auth_chpasswd(              shellmatta_handle_t     handle,
                                                            const char              *username,
                                                            const char              *password);

#endif

shellmatta_retCode_t shellmatta_ymodem_init(    shellmatta_handle_t                 handle,
                                                uint8_t*                            recvBuffer,
                                                shellmatta_ymodem_cancel_t          cancelCallback,
                                                shellmatta_ymodem_recvHeader_t      recvHeaderCallback,
                                                shellmatta_ymodem_recvPacket_t      recvPacketCallback,
                                                shellmatta_ymodem_complete_t        transmissionCompleteCallback);

shellmatta_retCode_t shellmatta_ymodem_pause(   shellmatta_handle_t                 handle);
shellmatta_retCode_t shellmatta_ymodem_resume(  shellmatta_handle_t                 handle);
shellmatta_retCode_t shellmatta_ymodem_cancel(  shellmatta_handle_t                 handle,
                                                bool                                doCancel);

#endif

/** @} */