geutebruck/geutebruck-api/specs/002-geviset-file-format/database-vs-setfile-comparison.md

Database vs .SET File Structure Comparison

Date: 2025-12-12 Purpose: Document differences between GeViSoft Database and .SET configuration file

Executive Summary

GeViSoft uses TWO distinct storage systems:

1. GeViDB.mdb (Access Database) - Stores runtime event logs
2. .set File (Binary Format) - Stores configuration and action mapping rules

They serve different purposes and have different structures.

---

GeViSoft Database (GeViDB.mdb)

Access Method

Option 1: .NET SDK Wrapper (Recommended)

var db = new GeViDatabase();
db.Create("localhost", "sysadmin", "plainTextPassword");  // No encoding needed!
db.RegisterCallback();
var result = db.Connect();

// Query actions
db.SendQuery(new GeViDBQ_CreateActionQuery(0), out GeViMessage answer);

Password Encoding: ✅ NOT REQUIRED - The .NET wrapper (GeViProcAPINET_4_0.dll) handles password encoding internally. The Create() method signature explicitly says plainTextPassword.

Option 2: Direct OleDB Access

string connectionString = "Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\GEVISOFT\DATABASE\GeViDB.mdb;Mode=Read;";
// Direct SQL queries to Alarms, Actions tables

Database Structure

Tables:

• Alarms - Alarm definitions
• Actions - Runtime action event log
• (Other configuration tables)

Actions Table Content:

PK	Action Data	Purpose
1	DataBaseReady()	System initialization event
4	SystemError(0,1000,203,"GEVISERVER: dongle not found")	System error log
5	SystemWarning(0,1000,206,"DEMO MODE GRANTED...")	System warning
15	UserLogin(1,"sysadmin","","127.0.0.1")	User authentication log

Key Characteristics:

• Stores runtime events and logs
• NOT action mapping configuration
• Grows over time as events occur
• Query-able with SQL or SDK queries

---

.SET File (Binary Configuration)

Access Method

SetupClient API:

// PASSWORD ENCODING REQUIRED for native API!
var encodedPassword = new StringBuilder(256);
GeViAPI_EncodeString(encodedPassword, password, 256);

GeViAPI_SetupClient_Create(out handle, alias, address, username,
    encodedPassword.ToString(), "", "");
GeViAPI_SetupClient_Connect(handle, out result, 10000);
GeViAPI_SetupClient_ReadSetup(handle, out buffer, out size, 60000);

Password Encoding: ❌ REQUIRED for SetupClient native API! Must call GeViAPI_EncodeString() before passing password.

Binary Format Structure

.set File (281,714 bytes)
├── Header: "GeViSoft Parameters" (length-prefixed)
├── Sections (multiple)
│   ├── Alarms
│   ├── Cameras
│   ├── GeViIO
│   ├── Clients
│   └── Action Mapping Rules
│       ├── "Rules" marker (05 52 75 6C 65 73)
│       ├── Trigger Conditions
│       └── Action Strings
│           ├── Format: 07 01 40 <len_2bytes_LE> <data>
│           └── Examples:
│               • "GSC ViewerConnectLive V <- C"
│               • "GNG PanLeft_101027"
│               • "GSC warning: demo mode for 100 min"

Action Mappings Extracted: 64 rules with 107 action strings

Examples:

{
  "id": 1,
  "fileOffset": 253894,
  "actions": [
    "GSC ViewerConnectLive V <- C",
    "GNG ViewerConnectLive V <- C_101027"
  ]
}

Key Characteristics:

• Stores configuration and rules
• Defines trigger → action mappings
• Static configuration (doesn't grow)
• Can be exported/imported with GeViSet application
• Binary format requires parsing

---

Comparison Table

Aspect	Database (GeViDB.mdb)	.SET File
Purpose	Runtime event logging	Configuration storage
Content	System events, user logins, errors	Action mapping rules, system config
Password Encoding	❌ NOT needed (.NET wrapper)	✅ REQUIRED (native SetupClient API)
Access Method	GeViDatabase + SendQuery	SetupClient_ReadSetup
Data Type	Event logs (dynamic)	Configuration rules (static)
Size	Grows over time	Fixed per configuration
Format	MS Access Database	Proprietary binary
Queryable	SQL / SDK queries	Binary parsing only
Example Content	UserLogin(1,"sysadmin"...)	"GSC ViewerConnectLive V <- C"

---

Password Encoding Summary

When Encoding IS Required

SetupClient Native API:

// C/C++ or P/Invoke
GeViAPI_EncodeString(encodedPassword, plainPassword, 256);
GeViAPI_SetupClient_Create(..., encodedPassword, ...);

Why: The native GeViProcAPI.dll requires pre-encoded passwords.

When Encoding is NOT Required

.NET SDK Wrapper:

// C# using .NET wrapper
var db = new GeViDatabase();
db.Create(server, username, plainTextPassword);  // Handles encoding internally

Why: The .NET wrapper (GeViProcAPINET_4_0.dll) calls GeViAPI_EncodeString internally.

---

Use Cases

Use Database When:

• Querying recent system events
• Checking user login history
• Monitoring system errors/warnings
• Real-time event tracking

Use .SET File When:

• Exporting/importing configuration
• Backing up action mapping rules
• Bulk editing action mappings
• Understanding configured rules (not events)

---

Tools Developed

1. QueryGeViDatabase

Purpose: Query database for runtime events Method: .NET SDK wrapper Password: Plain text (wrapper handles encoding)

QueryGeViDatabase.exe localhost sysadmin masterkey

Output:

• System events
• User logins
• Errors/warnings
• 100+ action event logs

2. DiagnoseSetupClient + GeViSetEditor

Purpose: Read/parse .set configuration file Method: Native SetupClient API Password: Manually encoded with GeViAPI_EncodeString

GeViSetEditor.exe to-json setup_config.dat output.json

Output:

• 64 action mapping rules
• 107 action strings
• Complete configuration in JSON

---

Findings

1. Database does NOT contain action mapping configuration

   • Only stores runtime event logs
   • Cannot use database queries to read action mapping rules

2. .SET file is the ONLY source for action mapping configuration

   • Must use SetupClient API
   • Must parse binary format
   • Contains all 64 action mapping rules

3. Password encoding depends on API layer:

   • .NET wrapper: No encoding needed
   • Native API: Encoding required
   • Both work, different use cases

4. Two distinct data flows:

   Configuration Flow:
   GeViSet App → .SET File → SetupClient API → Binary Parser → JSON
   
   Events Flow:
   GeViServer → Database → SendQuery → Event Logs
   

---

Recommendations

1. For Action Mapping Management:

   • Use SetupClient API to read .set files
   • Parse binary format to extract mappings
   • Export to JSON/Excel for editing
   • Rebuild .set file and write back

2. For Event Monitoring:

   • Use GeViDatabase queries
   • No binary parsing needed
   • Direct SQL or SDK queries

3. Password Handling:

   • Use .NET wrapper when possible (simpler)
   • Only use native API when .NET wrapper doesn't support the operation
   • Always encode passwords for native SetupClient API

---

Next Steps

1. ✅ Completed:

   • Database connection (both methods)
   • SetupClient connection with password encoding
   • Binary parser for .set files
   • JSON export of action mappings

2. In Progress:

   • Excel export for user-friendly editing
   • Enhanced parser for trigger conditions

3. Future:

   • Add/modify/delete action mappings
   • Binary writer for modifications
   • Web UI for configuration management

---

References

• SetupClient API: C:\GEVISOFT\Examples\VS2010CPP\GeViSoftSDK\Include\GeViProcAPI.h
• .NET Wrapper: C:\GEVISOFT\GeViProcAPINET_4_0.dll
• Database: C:\GEVISOFT\DATABASE\GeViDB.mdb
• Research Notes: geutebruck-api/specs/002-geviset-file-format/research.md