wslua_debugger.h

/* wslua_debugger.h
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */
 
#ifndef __WSLUA_DEBUGGER_H__
#define __WSLUA_DEBUGGER_H__
 
#include "ws_symbol_export.h"
#include <glib.h>
#include <stdbool.h>
 
typedef struct lua_State lua_State;
 
#ifdef __cplusplus
extern "C"
{
#endif

    typedef enum
    {
        WSLUA_DEBUGGER_OFF,     
        WSLUA_DEBUGGER_RUNNING, 
        WSLUA_DEBUGGER_PAUSED   
    } wslua_debugger_state_t;

    typedef enum
    {
        WSLUA_HIT_COUNT_MODE_FROM = 0,
        WSLUA_HIT_COUNT_MODE_EVERY = 1,
        WSLUA_HIT_COUNT_MODE_ONCE = 2,
    } wslua_hit_count_mode_t;

    typedef struct _wslua_breakpoint_t
    {
        char *file_path;          
        int64_t line;             
        bool active;              
        char *condition;          
        int64_t hit_count_target; 
        int64_t hit_count;        
        wslua_hit_count_mode_t hit_count_mode; 
        bool condition_error;     
        char *condition_error_msg;
        char *log_message;        
        bool log_also_pause;      
        int64_t last_fired_us;    
    } wslua_breakpoint_t;

    WS_DLL_PUBLIC void wslua_debugger_init(lua_State *L);

    WS_DLL_PUBLIC bool wslua_debugger_is_enabled(void);

    WS_DLL_PUBLIC void wslua_debugger_set_enabled(bool enabled);

    WS_DLL_PUBLIC void
    wslua_debugger_set_user_explicitly_disabled(bool user_wants_debugger_stay_off);

    WS_DLL_PUBLIC bool
    wslua_debugger_get_user_explicitly_disabled(void);

    WS_DLL_PUBLIC bool
    wslua_debugger_may_auto_enable_for_breakpoints(void);

    typedef void (*wslua_debugger_ui_update_cb_t)(const char *file_path,
                                                  int64_t line);

    WS_DLL_PUBLIC void
    wslua_debugger_register_ui_callback(wslua_debugger_ui_update_cb_t cb);

    WS_DLL_PUBLIC void wslua_debugger_continue(void);

    WS_DLL_PUBLIC void wslua_debugger_step_in(void);

    WS_DLL_PUBLIC void wslua_debugger_step_over(void);

    WS_DLL_PUBLIC void wslua_debugger_step_out(void);

    WS_DLL_PUBLIC void wslua_debugger_set_variable_stack_level(int32_t level);

    WS_DLL_PUBLIC void wslua_debugger_run_to_line(const char *file_path,
                                                  int64_t line);

    WS_DLL_PUBLIC void wslua_debugger_add_breakpoint(const char *file_path,
                                                     int64_t line);

    WS_DLL_PUBLIC void wslua_debugger_remove_breakpoint(const char *file_path,
                                                        int64_t line);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_active(const char *file_path, int64_t line,
                                         bool active);

    WS_DLL_PUBLIC void wslua_debugger_clear_breakpoints(void);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_condition(const char *file_path, int64_t line,
                                            const char *condition);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_hit_count_target(const char *file_path,
                                                   int64_t line,
                                                   int64_t target);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_hit_count_mode(const char *file_path,
                                                  int64_t line,
                                                  wslua_hit_count_mode_t mode);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_log_message(const char *file_path,
                                              int64_t line,
                                              const char *message);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_log_also_pause(const char *file_path,
                                                  int64_t line,
                                                  bool also_pause);

    WS_DLL_PUBLIC void
    wslua_debugger_reset_breakpoint_hit_count(const char *file_path,
                                              int64_t line);

    WS_DLL_PUBLIC void wslua_debugger_reset_all_breakpoint_hit_counts(void);

    WS_DLL_PUBLIC bool
    wslua_debugger_check_condition_syntax(const char *expression,
                                          char **err_msg);

    WS_DLL_PUBLIC void
    wslua_debugger_set_breakpoint_condition_error(const char *file_path,
                                                   int64_t line,
                                                   const char *err_msg);

    WS_DLL_PUBLIC int32_t
    wslua_debugger_get_breakpoint_state(const char *file_path, int64_t line);

    WS_DLL_PUBLIC char *wslua_debugger_canonical_path(const char *file_path);

    typedef struct
    {
        char *name;  
        char *value; 
        char *type;  
        bool can_expand; 
    } wslua_variable_t;

    typedef struct
    {
        char *source;        
        int64_t line;        
        int64_t linedefined; 
        char *name;          
    } wslua_stack_frame_t;

    WS_DLL_PUBLIC wslua_stack_frame_t *
    wslua_debugger_get_stack(int32_t *frame_count);

    WS_DLL_PUBLIC void wslua_debugger_free_stack(wslua_stack_frame_t *stack,
                                                 int32_t frame_count);

    WS_DLL_PUBLIC wslua_variable_t *
    wslua_debugger_get_variables(const char *path, int32_t *variable_count);

    WS_DLL_PUBLIC void wslua_debugger_free_variables(wslua_variable_t *vars,
                                                     int32_t variable_count);

    WS_DLL_PUBLIC unsigned wslua_debugger_get_breakpoint_count(void);

    WS_DLL_PUBLIC bool wslua_debugger_get_breakpoint(unsigned idx,
                                                     const char **file_path,
                                                     int64_t *line,
                                                     bool *active);

    WS_DLL_PUBLIC bool wslua_debugger_get_breakpoint_extended(
        unsigned idx, const char **file_path, int64_t *line, bool *active,
        const char **condition, int64_t *hit_count_target,
        int64_t *hit_count, bool *condition_error,
        const char **log_message,
        wslua_hit_count_mode_t *hit_count_mode,
        bool *log_also_pause);

    WS_DLL_PUBLIC char *
    wslua_debugger_get_breakpoint_condition_error_message(unsigned idx);

    WS_DLL_PUBLIC int32_t
    wslua_debugger_get_breakpoint_state_canonical(const char *canonical_path,
                                                  int64_t line,
                                                  bool *has_extras);

    typedef void (*wslua_debugger_log_emit_callback_t)(const char *file_path,
                                                       int64_t line,
                                                       const char *message);

    WS_DLL_PUBLIC void wslua_debugger_register_log_emit_callback(
        wslua_debugger_log_emit_callback_t callback);

    typedef void (*wslua_debugger_breakpoint_state_dirty_callback_t)(void);

    WS_DLL_PUBLIC void wslua_debugger_register_breakpoint_state_dirty_callback(
        wslua_debugger_breakpoint_state_dirty_callback_t callback);

    WS_DLL_PUBLIC void wslua_debugger_clear_breakpoint_state_dirty(void);

    typedef void (*wslua_debugger_reload_callback_t)(void);

    WS_DLL_PUBLIC void wslua_debugger_register_reload_callback(
        wslua_debugger_reload_callback_t callback);

    WS_DLL_PUBLIC bool wslua_debugger_notify_reload(void);

    typedef void (*wslua_debugger_post_reload_callback_t)(void);

    WS_DLL_PUBLIC void wslua_debugger_register_post_reload_callback(
        wslua_debugger_post_reload_callback_t callback);

    WS_DLL_PUBLIC void wslua_debugger_prepare_for_reload_init(void);

    WS_DLL_PUBLIC void wslua_debugger_notify_post_reload(void);

    WS_DLL_PUBLIC char *wslua_debugger_evaluate(const char *expression,
                                                char **error_msg);

    WS_DLL_PUBLIC bool wslua_debugger_is_paused(void);

    WS_DLL_PUBLIC void wslua_debugger_forget_lua_thread(lua_State *L);

    typedef void (*wslua_debugger_script_loaded_callback_t)(
        const char *file_path);

    WS_DLL_PUBLIC void wslua_debugger_register_script_loaded_callback(
        wslua_debugger_script_loaded_callback_t callback);

    WS_DLL_PUBLIC void
    wslua_debugger_notify_script_loaded(const char *file_path);

    typedef void (*wslua_debugger_loaded_script_callback_t)(
        const char *file_path, void *user_data);

    WS_DLL_PUBLIC void wslua_debugger_foreach_loaded_script(
        wslua_debugger_loaded_script_callback_t callback, void *user_data);

    WS_DLL_PUBLIC void wslua_debugger_set_error_break_enabled(bool enabled);

    WS_DLL_PUBLIC bool wslua_debugger_get_error_break_enabled(void);

    WS_DLL_PUBLIC bool wslua_debugger_capture_runtime_error(lua_State *L,
                                                            const char *msg);

    WS_DLL_PUBLIC bool wslua_debugger_after_pcall_failure(lua_State *L);

    WS_DLL_PUBLIC const char *wslua_debugger_consume_error_text(void);
 
    /*
     * Watch path APIs (below) take @c debugger.mutex when they touch the
     * paused Lua state. Call them from the same execution context as the Lua
     * debugger UI (typically the Qt GUI thread), matching
     * @ref wslua_debugger_get_variables and other variable accessors. Do not
     * interleave them with code that resumes the debugger or replaces
     * @c paused_L from another thread.
     */

#define WSLUA_WATCH_MAX_PATH_SEGMENTS 32

    WS_DLL_PUBLIC bool wslua_debugger_watch_spec_uses_path_resolution(
        const char *spec);

    WS_DLL_PUBLIC char *wslua_debugger_watch_variable_path_for_spec(
        const char *spec);

    WS_DLL_PUBLIC char *wslua_debugger_watch_resolved_variable_path_for_spec(
        const char *spec);

    WS_DLL_PUBLIC bool wslua_debugger_watch_read_root(
        const char *spec, char **value_out, char **type_out,
        bool *can_expand_out, char **error_msg);

    WS_DLL_PUBLIC bool wslua_debugger_read_variable_value_full(
        const char *variable_path, char **value_out, char **error_msg);
 
    /*
     * Watch expression APIs (below) evaluate an arbitrary Lua expression
     * against the paused state. They share the same instruction-count and
     * call-depth safety hooks as @ref wslua_debugger_evaluate, and run with
     * a custom @c _ENV that exposes the paused frame's locals, upvalues,
     * and globals — so a bare identifier in an expression resolves the
     * same way an unqualified path watch does.
     *
     * Use these for any spec that does not validate as a path under
     * @ref wslua_debugger_watch_spec_uses_path_resolution. Like the path
     * APIs above, they take @c debugger.mutex when they touch the paused
     * Lua state and must be called from the same execution context as the
     * Qt debugger UI (typically the GUI thread).
     */

    WS_DLL_PUBLIC bool wslua_debugger_watch_expr_read_root(
        const char *spec, char **value_out, char **type_out,
        bool *can_expand_out, char **error_msg);

    WS_DLL_PUBLIC bool wslua_debugger_watch_expr_get_variables(
        const char *spec, const char *subpath,
        wslua_variable_t **variables_out, int32_t *count_out,
        char **error_msg);

    WS_DLL_PUBLIC bool wslua_debugger_watch_expr_read_full(
        const char *spec, const char *subpath, char **value_out,
        char **error_msg);
 
#ifdef __cplusplus
}
#endif
 
#endif /* __WSLUA_DEBUGGER_H__ */