Skip to content

File wsh_shell.h

FileList > src > wsh_shell.h

Go to the source code of this file

Core shell interface for command parsing, user authentication, and terminal interaction. More...

  • #include "wsh_shell_autocomplete.h"
  • #include "wsh_shell_cfg.h"
  • #include "wsh_shell_cmd.h"
  • #include "wsh_shell_cmd_def.h"
  • #include "wsh_shell_esc.h"
  • #include "wsh_shell_history.h"
  • #include "wsh_shell_interact.h"
  • #include "wsh_shell_io.h"
  • #include "wsh_shell_misc.h"
  • #include "wsh_shell_promptwait.h"
  • #include "wsh_shell_ps1_custom.h"
  • #include "wsh_shell_session.h"
  • #include "wsh_shell_str.h"
  • #include "wsh_shell_types.h"
  • #include "wsh_shell_user.h"
  • #include "wsh_shell_version.h"

Classes

Type Name
struct WshShellAuthCtx_t
Temporary authentication context for login input handling.
struct WshShellExtCallbacks_t
Optional external callbacks invoked on user session changes.
struct WshShell_t
Main shell structure containing state, configuration, user context, and subsystems.

Public Types

Type Name
typedef void(* WshShell_ExtClbk_t
Type of external callback used in shell extension hooks.

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.

Macros

Type Name
define COMPILER "Unknown Compiler"
define OS_NAME WSH\_SHELL\_TARGET\_OS
define WSH_SHELL_HEADER "\ \_\_ \_\_ \_\_\_\_ \r\n\ \_ \_\_\_\_\_\_\_/ /\_ \_\_\_\_\_/ /\_ \_\_\_ / / / \r\n\\| \| /\| / / \_\_\_/ \_\_ \\\_\_\_\_\_\_/ \_\_\_/ \_\_ \\/ \_ \\/ / /\r\n\\| \|/ \|/ (\_\_ ) / / /\_\_\_\_\_(\_\_ ) / / / \_\_/ / / \r\n\\|\_\_/\|\_\_/\_\_\_\_/\_/ /\_/ /\_\_\_\_/\_/ /\_/\\\_\_\_/\_/\_/ \r\n\\r\n"

Detailed Description

This header provides the main shell object (WshShell_t), core APIs for initialization, input processing, user session management, and support for optional external callbacks.

Author:

Whoosh Embedded Team

Copyright:

Copyright (c) 2024

Public Types Documentation

typedef WshShell_ExtClbk_t

Type of external callback used in shell extension hooks. 

1
typedef void(* WshShell_ExtClbk_t) (void *pCtx);

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.

Macro Definition Documentation

define COMPILER

1
#define COMPILER `"Unknown Compiler"`

define OS_NAME

1
#define OS_NAME `WSH_SHELL_TARGET_OS`

define WSH_SHELL_HEADER

1
#define WSH_SHELL_HEADER `"\                __               __         ____  \r\n\ _      _______/ /_        _____/ /_  ___  / / /  \r\n\| | /| / / ___/ __ \\______/ ___/ __ \\/ _ \\/ / /\r\n\| |/ |/ (__  ) / / /_____(__  ) / / /  __/ / /    \r\n\|__/|__/____/_/ /_/     /____/_/ /_/\\___/_/_/    \r\n\\r\n"`

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