geutebruck/geutebruck-api/SETUPCLIENT_SOLUTION.md

SetupClient Solution - Action Mapping Configuration

Date: 2025-12-11 Discovery: How to read/write action mapping configuration like GeViSet

---

🎯 The Correct Approach

GeViSet uses SetupClient API (NOT State Queries, NOT Database Queries) to read/write configuration.

Native C++ SDK Functions

// From GeViProcAPI.dll

// 1. Create setup client
bool GeViAPI_SetupClient_Create(
    HGeViSetupClient &SetupClient,
    const char *Aliasname,
    const char *Address,
    const char *Username,
    const char *Password,
    const char *Username2,
    const char *Password2
)

// 2. Connect to GeViServer
bool GeViAPI_SetupClient_Connect(
    HGeViSetupClient SetupClient,
    TConnectResult &ConnectResult,
    TGeViConnectProgress ACallback,
    void *AInstance
)

// 3. READ configuration from GeViServer (including action mappings!)
bool GeViAPI_SetupClient_ReadSetup(
    HGeViSetupClient SetupClient,
    void *HFile  // File handle to write config to
)

// 4. WRITE configuration back to GeViServer (modified action mappings)
bool GeViAPI_SetupClient_WriteSetup(
    HGeViSetupClient SetupClient,
    void *HFile  // File handle to read config from
)

// 5. Disconnect
bool GeViAPI_SetupClient_Disconnect(HGeViSetupClient SetupClient)

// 6. Destroy
bool GeViAPI_SetupClient_Destroy(HGeViSetupClient SetupClient)

---

📖 How It Works (GeViSet Workflow)

1. Connect to GeViServer using SetupClient
2. Read Setup → Downloads entire configuration to a file
3. Modify action mappings in the configuration file (XML or binary)
4. Write Setup → Uploads modified configuration back
5. Disconnect

The configuration file contains:

• Action mappings (input → output actions)
• Alarm settings
• Client configurations
• All server settings

---

⚠️ .NET SDK Status

Checked: The .NET SDK (GeViProcAPINET_4_0.dll) does NOT wrap SetupClient functions.

Evidence:

• Searched 4,046 types in SDK
• Found 0 classes with "SetupClient" pattern
• Found setup structs but no SetupClient wrapper

---

✅ Solution Options

Option 1: P/Invoke to Native DLL (Recommended)

Create a C# wrapper that calls the native GeViProcAPI.dll directly:

using System.Runtime.InteropServices;

public class GeViSetupClient
{
    [DllImport("GeViProcAPI.dll", CallingConvention = CallingConvention.Cdecl)]
    private static extern bool GeViAPI_SetupClient_Create(
        out IntPtr setupClient,
        string aliasname,
        string address,
        string username,
        string password,
        string username2,
        string password2
    );

    [DllImport("GeViProcAPI.dll", CallingConvention = CallingConvention.Cdecl)]
    private static extern bool GeViAPI_SetupClient_Connect(
        IntPtr setupClient,
        out int connectResult,
        IntPtr callback,  // Can be IntPtr.Zero
        IntPtr instance
    );

    [DllImport("GeViProcAPI.dll", CallingConvention = CallingConvention.Cdecl)]
    private static extern bool GeViAPI_SetupClient_ReadSetup(
        IntPtr setupClient,
        IntPtr hFile  // File handle from kernel32.CreateFile
    );

    [DllImport("GeViProcAPI.dll", CallingConvention = CallingConvention.Cdecl)]
    private static extern bool GeViAPI_SetupClient_WriteSetup(
        IntPtr setupClient,
        IntPtr hFile
    );

    [DllImport("GeViProcAPI.dll", CallingConvention = CallingConvention.Cdecl)]
    private static extern bool GeViAPI_SetupClient_Disconnect(IntPtr setupClient);

    [DllImport("GeViProcAPI.dll", CallingConvention = CallingConvention.Cdecl)]
    private static extern bool GeViAPI_SetupClient_Destroy(IntPtr setupClient);
}

Option 2: Use Existing GeViSet Executable

Call GeViSet.exe as a subprocess to export/import configuration:

// This approach uses GeViSet's command-line interface (if available)
// Or automate GUI using Windows API

Option 3: Direct File Manipulation

GeViSet stores configuration in files. You could:

1. Export config using GeViSet manually once
2. Parse the XML/binary format
3. Modify action mappings programmatically
4. Import using GeViSet or SetupClient API

---

🔬 Configuration File Format

The setup file is likely:

• XML format with action mapping definitions
• Binary format (proprietary Geutebruck format)

Need to investigate by:

1. Using SetupClient to read setup to a file
2. Inspecting the file format
3. Determining if it's XML, binary, or custom format

---

📋 Implementation Plan

Phase 1: Create P/Invoke Wrapper ✅

File: src/sdk-bridge/GeViScopeBridge/SDK/GeViSetupClient.cs

public class GeViSetupClient
{
    private IntPtr _handle;

    public async Task<bool> ConnectAsync(string address, string username, string password)
    {
        // P/Invoke to GeViAPI_SetupClient_Create
        // P/Invoke to GeViAPI_SetupClient_Connect
    }

    public async Task<byte[]> ReadSetupAsync()
    {
        // Create temp file
        // P/Invoke to GeViAPI_SetupClient_ReadSetup with file handle
        // Read file contents
        // Return as byte array
    }

    public async Task<bool> WriteSetupAsync(byte[] setupData)
    {
        // Write byte array to temp file
        // P/Invoke to GeViAPI_SetupClient_WriteSetup with file handle
        // Return success
    }
}

Phase 2: Parse Configuration Format

File: src/sdk-bridge/GeViScopeBridge/SDK/SetupConfigParser.cs

public class SetupConfigParser
{
    public SetupConfig ParseSetup(byte[] rawData)
    {
        // Determine format (XML vs binary)
        // Parse action mappings
        // Return structured config
    }

    public byte[] SerializeSetup(SetupConfig config)
    {
        // Convert back to file format
        // Return byte array
    }
}

Phase 3: Action Mapping CRUD

File: src/sdk-bridge/GeViScopeBridge/SDK/ActionMappingConfigService.cs

public class ActionMappingConfigService
{
    private readonly GeViSetupClient _setupClient;
    private readonly SetupConfigParser _parser;

    public async Task<List<ActionMapping>> GetActionMappingsAsync()
    {
        var setupData = await _setupClient.ReadSetupAsync();
        var config = _parser.ParseSetup(setupData);
        return config.ActionMappings;
    }

    public async Task<bool> SaveActionMappingsAsync(List<ActionMapping> mappings)
    {
        var config = new SetupConfig { ActionMappings = mappings };
        var setupData = _parser.SerializeSetup(config);
        return await _setupClient.WriteSetupAsync(setupData);
    }
}

---

🧪 Testing Strategy

Test 1: Read Setup

var client = new GeViSetupClient();
await client.ConnectAsync("192.168.1.100", "admin", "password");
var setupData = await client.ReadSetupAsync();

// Save to file for inspection
File.WriteAllBytes("setup_config.dat", setupData);

Test 2: Parse & Inspect

// Manually inspect setup_config.dat
// Determine if XML, JSON, binary, etc.
// Look for action mapping patterns

Test 3: Roundtrip

// Read setup
var data = await client.ReadSetupAsync();

// Write it back unchanged
var success = await client.WriteSetupAsync(data);

// Verify no changes in GeViSet

---

📚 References

Documentation

• Native SDK: C:\Gevisoft\Documentation\extracted_html\GeViSoft_API_Documentation\_ge_vi_proc_a_p_i_8h.html
• SetupClient Guide: GeViSoft_SDK_Documentation\411OverviewoftheSDKInterfaces.htm
• Action Mapping Tutorial: GeViSoft_SDK_Documentation\313Action Mapping.htm

Key Quote from SDK Docs

"The SetupClient functions are used by GeViSet to change the server setup."

This is exactly what we need!

---

⚡ Quick Start (Next Steps)

1. Create P/Invoke wrapper for SetupClient functions
2. Test reading setup to a file
3. Inspect file format (hex dump, text editor)
4. Implement parser based on format discovery
5. Test write with modified action mappings

---

Status: Solution identified, ready for implementation Complexity: Medium (P/Invoke + file parsing) ETA: 1-2 days for full implementation