Skip to content

File wsh_shell.c

FileList > src > wsh_shell.c

Go to the source code of this file

  • #include "wsh_shell.h"

Public Functions

Type Name
WshShell_Bool_t WshShell_Auth (WshShell_t * pShell, const WshShell_Char_t * pcLogin, const WshShell_Char_t * pcPass)
Attempt to authenticate a user with given login credentials.
void WshShell_DeAuth (WshShell_t * pShell, const WshShell_Char_t * pcReason)
De-authenticate the currently logged-in user.
WSH_SHELL_RET_STATE_t WshShell_Init (WshShell_t * pShell, const WshShell_Char_t * pcDevName, const WshShell_Char_t * pcCustomHeader, WshShellExtCallbacks_t * pExtClbks)
Initialize a shell instance.
void WshShell_InsertChar (WshShell_t * pShell, const WshShell_Char_t symbol)
Process a new character entered by the user.
WshShell_Bool_t WshShell_IsAuth (const WshShell_t * pcShell)
Check if a user is currently authenticated.
WshShell_Bool_t WshShell_SessionArm (WshShell_t * pShell, WshShell_U32_t reboots)
Arm cross-reboot login persistence for the current user.
WshShell_Bool_t WshShell_SessionIsKeepActive (WshShell_t * pShell)
Whether an armed keep-session is currently active (budget remaining).
WshShell_U32_t WshShell_SessionRebootsLeft (WshShell_t * pShell)
Remaining reboot budget of the armed session, or 0 if none.
WshShell_Bool_t WshShell_SessionRestore (WshShell_t * pShell)
Restore a previously armed login without a password prompt.

Public Static Functions

Type Name
void WshShell_AuthHandler (WshShell_t * pShell)
void WshShell_ExitInteractive (WshShell_t * pShell)
void WshShell_InvitationPrint (const WshShell_t * pcShell)
void WshShell_StringHandler (WshShell_t * pShell)
void WshShell_StringInteractHandler (WshShell_t * pShell)
void WshShell_Stub_ExtClbk (void * pCtx)
void WshShell_SymbolHandler (WshShell_t * pShell, const WshShell_Char_t symbol)

Macros

Type Name
define SHELL_SAVE_PREV_AND_RETURN (pShell, sym) /* multi line expression */
define WSH_SHELL_INTER_CMD_EXISTS (_sh_) ((\_sh\_)->Interact.Handler != NULL)
define WSH_SHELL_TMP_LOGIN_IS_EMPTY (_sh_) ((\_sh\_)->TmpAuth.Login[0] == 0)
define WSH_SHELL_TMP_PASS_IS_EMPTY (_sh_) ((\_sh\_)->TmpAuth.Pass[0] == 0)
define WSH_SHELL_USER_IS_AUTH (_sh_) ((\_sh\_)->CurrUser != NULL)

Public Functions Documentation

function WshShell_Auth

Attempt to authenticate a user with given login credentials. 

1
2
3
4
5
WshShell_Bool_t WshShell_Auth (
    WshShell_t * pShell,
    const WshShell_Char_t * pcLogin,
    const WshShell_Char_t * pcPass
)

Updates the current user context on success, or leaves it unchanged on failure.

Parameters:

  • pShell Shell instance.
  • pcLogin User name.
  • pcPass Password.

Returns:

Is auth OK?

function WshShell_DeAuth

De-authenticate the currently logged-in user. 

1
2
3
4
void WshShell_DeAuth (
    WshShell_t * pShell,
    const WshShell_Char_t * pcReason
)

Resets the user context and optionally triggers the DeAuth callback.

Parameters:

  • pShell Shell instance.
  • pcReason Reason or source of deauth.

function WshShell_Init

Initialize a shell instance. 

1
2
3
4
5
6
WSH_SHELL_RET_STATE_t WshShell_Init (
    WshShell_t * pShell,
    const WshShell_Char_t * pcDevName,
    const WshShell_Char_t * pcCustomHeader,
    WshShellExtCallbacks_t * pExtClbks
)

Initializes internal subsystems, assigns device name and optional header, and installs optional external callbacks.

Parameters:

  • pShell Pointer to the shell instance.
  • pcDevName Device name (e.g., "ttyS0" or "shell0").
  • pcCustomHeader Optional welcome banner for this instance. When NULL, WSH_SHELL_HEADER is used: either the one defined in wsh_shell_cfg.h or the built-in wsh-shell logo.
  • pExtClbks Pointer to external callback structure (can be NULL).

Returns:

Initialization status code.

function WshShell_InsertChar

Process a new character entered by the user. 

1
2
3
4
void WshShell_InsertChar (
    WshShell_t * pShell,
    const WshShell_Char_t symbol
)

Handles interactive editing, history navigation, or command execution if input is complete.

Parameters:

  • pShell Shell instance.
  • symbol Character to insert.

function WshShell_IsAuth

Check if a user is currently authenticated. 

1
2
3
WshShell_Bool_t WshShell_IsAuth (
    const WshShell_t * pcShell
)

Parameters:

  • pShell Shell instance.

Returns:

WSH_SHELL_TRUE if a user is authenticated, WSH_SHELL_FALSE otherwise.

function WshShell_SessionArm

Arm cross-reboot login persistence for the current user. 

1
2
3
4
WshShell_Bool_t WshShell_SessionArm (
    WshShell_t * pShell,
    WshShell_U32_t reboots
)

Records the current login so it can be restored without a password after up to reboots reboots. While a session is armed the integrator can also suppress the inactivity auto-logout (see WshShell_SessionIsKeepActive()). Passing 0 clears any armed session. Requires the shell to have session I/O installed (WshShellSession_Init()) and a user currently logged in.

Parameters:

  • pShell Shell instance.
  • reboots Number of reboots the login may survive (0 clears).

Returns:

true if the request was applied.

function WshShell_SessionIsKeepActive

Whether an armed keep-session is currently active (budget remaining). 

1
2
3
WshShell_Bool_t WshShell_SessionIsKeepActive (
    WshShell_t * pShell
)

The integrator can use this to block the inactivity auto-logout while the host asked to stay logged in.

Parameters:

  • pShell Shell instance.

Returns:

true if a valid session with remaining reboot budget is stored.

function WshShell_SessionRebootsLeft

Remaining reboot budget of the armed session, or 0 if none. 

1
2
3
WshShell_U32_t WshShell_SessionRebootsLeft (
    WshShell_t * pShell
)

Parameters:

  • pShell Shell instance.

Returns:

Reboots left, or 0 when no valid session is armed.

function WshShell_SessionRestore

Restore a previously armed login without a password prompt. 

1
2
3
WshShell_Bool_t WshShell_SessionRestore (
    WshShell_t * pShell
)

Intended to be called once at start-up, after the user table is attached. On success the current user and PS1 are set and the Auth callback is invoked, exactly as a normal login would. Consumes one reboot from the budget.

Parameters:

  • pShell Shell instance.

Returns:

true if a valid session was restored.

Public Static Functions Documentation

function WshShell_AuthHandler

1
2
3
static void WshShell_AuthHandler (
    WshShell_t * pShell
)

function WshShell_ExitInteractive

1
2
3
static void WshShell_ExitInteractive (
    WshShell_t * pShell
)

function WshShell_InvitationPrint

1
2
3
static void WshShell_InvitationPrint (
    const WshShell_t * pcShell
)

function WshShell_StringHandler

1
2
3
static void WshShell_StringHandler (
    WshShell_t * pShell
)

function WshShell_StringInteractHandler

1
2
3
static void WshShell_StringInteractHandler (
    WshShell_t * pShell
)

function WshShell_Stub_ExtClbk

1
2
3
static void WshShell_Stub_ExtClbk (
    void * pCtx
)

function WshShell_SymbolHandler

1
2
3
4
static void WshShell_SymbolHandler (
    WshShell_t * pShell,
    const WshShell_Char_t symbol
)

Macro Definition Documentation

define SHELL_SAVE_PREV_AND_RETURN

1
2
3
4
#define SHELL_SAVE_PREV_AND_RETURN (
    pShell,
    sym
) `/* multi line expression */`

define WSH_SHELL_INTER_CMD_EXISTS

1
2
3
#define WSH_SHELL_INTER_CMD_EXISTS (
    _sh_
) `((_sh_)->Interact.Handler != NULL)`

define WSH_SHELL_TMP_LOGIN_IS_EMPTY

1
2
3
#define WSH_SHELL_TMP_LOGIN_IS_EMPTY (
    _sh_
) `((_sh_)->TmpAuth.Login[0] == 0)`

define WSH_SHELL_TMP_PASS_IS_EMPTY

1
2
3
#define WSH_SHELL_TMP_PASS_IS_EMPTY (
    _sh_
) `((_sh_)->TmpAuth.Pass[0] == 0)`

define WSH_SHELL_USER_IS_AUTH

1
2
3
#define WSH_SHELL_USER_IS_AUTH (
    _sh_
) `((_sh_)->CurrUser != NULL)`

The documentation for this class was generated from the following file src/wsh_shell.c