/* * Copyright (c) 2019 - 2024 Stefan Strobel * * 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 */ /** * @addtogroup shellmatta_api Shellmatta API description * @{ */ #ifndef _SHELLMATTA_H_ #define _SHELLMATTA_H_ #include #include /* 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_PAUSE /**< pause after a packet */ } 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 */ 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 /** @} */