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

```cpp
// 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:

```csharp
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:

```csharp
// 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`

```csharp
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`

```csharp
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`

```csharp
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

```csharp
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

```csharp
// 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