geutebruck/geutebruck-api/SDK_ALARM_QUERY_APPROACH.md

SDK Alarm Query Approach

Discovery Summary

After extracting and analyzing the GeViSoft .NET SDK API documentation (2403 HTML files from CHM), I found the correct approach to read action mappings from the live GeViSoft instance.

Key Finding

SetupClient functions are NOT exposed in the .NET SDK. The SDK documentation explicitly states:

"The SetupClient functions are used by GeViSet to change the server setup. They are usually not of interest for SDK developers."

Instead, the SDK provides State Query actions to read alarm configurations.

The Solution: State Queries

Action mappings in GeViSoft are stored as Alarms. We can query them using these state query actions:

Available Query Actions

Action	Description (German → English)	Purpose
GeViSQ_GetFirstAlarm	Liefert die Information zu dem ersten Alarm	Get first alarm information
GeViSQ_GetNextAlarm	Liefert die Information zu dem naechsten Alarm	Get next alarm information
GeViSQ_GetAlarms	Liefert die Information zum bestimmten Alarm	Get specific alarm by ID
GeViSQ_GetAlarmsByName	Liefert die Information zum bestimmten Alarm	Get specific alarm by name
GeViDBQ_CreateAlarmQuery	Startet eine Abfrage ueber die Alarmtabelle	Start query over alarm table

How to Enumerate All Alarms

// 1. Create query for first alarm
var query = new GeViSQ_GetFirstAlarm(
    initActiveOnly: false,    // false = all alarms (not just active)
    initEnabledOnly: false     // false = both enabled and disabled
);

// 2. Send query to GeViServer
await geviDatabase.SendMessageAsync(query);

// 3. Register callback to receive answer
geviDatabase.OnNewGeViSA_FirstAlarm += HandleFirstAlarmAnswer;

// 4. Iterate through remaining alarms
geviDatabase.OnNewGeViSA_NextAlarm += HandleNextAlarmAnswer;

// In handlers, send GeViSQ_GetNextAlarm to get subsequent alarms

Implementation Plan

Phase 1: Alarm Query Service (C# SDK Bridge)

Create AlarmQueryService.cs:

public class AlarmQueryService
{
    private readonly GeViDatabaseWrapper _database;
    private readonly List<AlarmInfo> _alarmCache = new();

    public async Task<List<AlarmInfo>> GetAllAlarmsAsync()
    {
        _alarmCache.Clear();

        // Send first alarm query
        var query = new GeViSQ_GetFirstAlarm(false, false);
        await _database.SendMessageAsync(query);

        // Wait for answers (with timeout)
        // Answers arrive via callbacks

        return _alarmCache;
    }

    private void HandleFirstAlarmAnswer(GeViSA_FirstAlarmEventArgs e)
    {
        // Parse alarm data
        var alarm = ParseAlarmData(e);
        _alarmCache.Add(alarm);

        // Request next alarm
        var nextQuery = new GeViSQ_GetNextAlarm();
        _database.SendMessageAsync(nextQuery);
    }

    private void HandleNextAlarmAnswer(GeViSA_NextAlarmEventArgs e)
    {
        if (e.HasMoreAlarms)
        {
            var alarm = ParseAlarmData(e);
            _alarmCache.Add(alarm);

            // Request next
            var nextQuery = new GeViSQ_GetNextAlarm();
            _database.SendMessageAsync(nextQuery);
        }
    }
}

Phase 2: Identify Action Mapping Alarms

Not all alarms are action mappings. Need to filter by:

• Alarm type/category
• Input action field presence
• Output actions field presence

Example alarm structure (from GeViDB.mdb):

ID: 12345
Name: "Motion Detection Auto-Route"
Type: "Action Mapping" (or similar type ID)
InputAction: "VMD_Start(101038)"
OutputActions: ["CrossSwitch(101038, 1, 0)"]
Enabled: true

Phase 3: Update ActionMappingHandler

Modify ActionMappingHandler.cs:

public class ActionMappingHandler
{
    private readonly AlarmQueryService _alarmQuery;

    public async Task<List<ActionMappingConfig>> GetAllActionMappingsAsync()
    {
        // Query all alarms from GeViServer
        var allAlarms = await _alarmQuery.GetAllAlarmsAsync();

        // Filter to only action mapping type alarms
        var actionMappings = allAlarms
            .Where(IsActionMapping)
            .Select(MapToActionMappingConfig)
            .ToList();

        return actionMappings;
    }

    private bool IsActionMapping(AlarmInfo alarm)
    {
        // Filter logic:
        // - Has input action
        // - Has output actions
        // - Type indicates it's an action mapping
        return !string.IsNullOrEmpty(alarm.InputAction) &&
               alarm.OutputActions?.Any() == true;
    }
}

Phase 4: Callback Registration

Need to investigate:

1. What answer types are returned by these queries
2. How to register callbacks for alarm answers
3. What fields are available in the answer objects

Next Steps

1. Find alarm answer event types - Search for GeViSA_FirstAlarm, GeViSA_NextAlarm event args
2. Understand alarm data structure - What fields are available?
3. Test query execution - Send a GetFirstAlarm query and inspect the response
4. Implement full enumeration - Iterate through all alarms
5. Filter for action mappings - Identify which alarms are action mappings
6. Map to gRPC model - Convert alarm data to ActionMappingConfig

Advantages of This Approach

✅ Uses official SDK API (not direct database access) ✅ Reads LIVE data from GeViServer (not stale database copy) ✅ Same data that GeViSet would see ✅ Respects GeViServer's locking and transaction handling ✅ Can receive real-time updates via alarm events

Questions to Resolve

1. Answer event types: What are the exact event arg types for alarm query answers?
2. Alarm fields: What properties are available on alarm answer objects?
3. Action mapping identification: How to distinguish action mapping alarms from other alarm types?
4. Write operations: How to create/update/delete alarms (action mappings)?
5. Real-time updates: Can we subscribe to alarm change notifications?

Documentation Files

Extracted CHM documentation location:

C:\DEV\COPILOT\geutebruck-api\docs\chm-extracted\

Key files:

• class_g_e_u_t_e_b_r_u_e_c_k_1_1_ge_vi_soft_s_d_k_n_e_t_1_1_actions_wrapper_1_1_ge_vi_database-members.html - All GeViDatabase methods
• class_g_e_u_t_e_b_r_u_e_c_k_1_1_ge_vi_soft_s_d_k_n_e_t_1_1_actions_wrapper_1_1_state_queries_1_1_ge_vi_s_q___get_first_alarm.html - GetFirstAlarm documentation