Files
geutebruck/SOURCES/GeViScope_SDK_text/GeViScope_SDK_pages_021-030.txt
Administrator 14893e62a5 feat: Geutebruck GeViScope/GeViSoft Action Mapping System - MVP
This MVP release provides a complete full-stack solution for managing action mappings
in Geutebruck's GeViScope and GeViSoft video surveillance systems.

## Features

### Flutter Web Application (Port 8081)
- Modern, responsive UI for managing action mappings
- Action picker dialog with full parameter configuration
- Support for both GSC (GeViScope) and G-Core server actions
- Consistent UI for input and output actions with edit/delete capabilities
- Real-time action mapping creation, editing, and deletion
- Server categorization (GSC: prefix for GeViScope, G-Core: prefix for G-Core servers)

### FastAPI REST Backend (Port 8000)
- RESTful API for action mapping CRUD operations
- Action template service with comprehensive action catalog (247 actions)
- Server management (G-Core and GeViScope servers)
- Configuration tree reading and writing
- JWT authentication with role-based access control
- PostgreSQL database integration

### C# SDK Bridge (gRPC, Port 50051)
- Native integration with GeViSoft SDK (GeViProcAPINET_4_0.dll)
- Action mapping creation with correct binary format
- Support for GSC and G-Core action types
- Proper Camera parameter inclusion in action strings (fixes CrossSwitch bug)
- Action ID lookup table with server-specific action IDs
- Configuration reading/writing via SetupClient

## Bug Fixes
- **CrossSwitch Bug**: GSC and G-Core actions now correctly display camera/PTZ head parameters in GeViSet
- Action strings now include Camera parameter: `@ PanLeft (Comment: "", Camera: 101028)`
- Proper filter flags and VideoInput=0 for action mappings
- Correct action ID assignment (4198 for GSC, 9294 for G-Core PanLeft)

## Technical Stack
- **Frontend**: Flutter Web, Dart, Dio HTTP client
- **Backend**: Python FastAPI, PostgreSQL, Redis
- **SDK Bridge**: C# .NET 8.0, gRPC, GeViSoft SDK
- **Authentication**: JWT tokens
- **Configuration**: GeViSoft .set files (binary format)

## Credentials
- GeViSoft/GeViScope: username=sysadmin, password=masterkey
- Default admin: username=admin, password=admin123

## Deployment
All services run on localhost:
- Flutter Web: http://localhost:8081
- FastAPI: http://localhost:8000
- SDK Bridge gRPC: localhost:50051
- GeViServer: localhost (default port)

Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-31 18:10:54 +01:00

394 lines
21 KiB
Plaintext
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

================================================================================
GeViScope_SDK.pdf - Pages 21 to 30
================================================================================
────────────────────────────────────────────────────────────────────────────────
Page 21
────────────────────────────────────────────────────────────────────────────────
Backgroundinformation
InGeViScopesystemsactionsareusedtocommunicatebetweentheGeViScopeserver
andanyclientapplication.Allavailableactionscanbedividedintothreegroups:
Notificationactions(forexample“UserLogin”),commandactions(forexample“Viewercon-
nectlive”)andlogicalactions(theseactionsarenotdirectlycreatedbytheGeViScope
serverandtheydontdirectlyresultinanyreactionintheGeViScopeserver,forexample
“Customaction”).
Allactionsaregroupedindifferentcategories.Thecategory“Vieweractions”containsall
actionsthatarerelevantforremotecontrollingGSCView.
TogetnotificationsaboutGSCViewactivities,oneoftheoptions“Sendnotificationactions”
intheprofilemanagerofGSCViewhastobeset.Allpossiblenotificationactionsarecol-
lectedintheactioncategory“Viewernotifications”.
────────────────────────────────────────────────────────────────────────────────
Page 22
────────────────────────────────────────────────────────────────────────────────
Moredetailedinformationaboutallavailableactionscanbefoundinthetopic“Actiondoc-
umentation”(especiallyVieweractionsandViewernotifications).
PleasebeawareofthefactthatGSCViewisworkinginanasynchronousmode.Ifacustom
applicationsendsanaction,thatdependsontheresultoftheprevioussentactiontheremay
betheneedforinsertingapausetimebeforesendingthesecondaction(e.g.sendaction
“Viewerconnectlive”,waitonesecond,sendaction“Viewerprintpicture”).GSCViewdoes
nothaveaninputqueueforremotecontrolactions.
Supporteddevelopmentplatforms
TheSDKisdesignedandtestedtobeusedwiththefollowingdevelopmentenvironments:
l CodeGearC++Builder6©
l CodeGearC++Builder2009©
l CodeGearDelphi7©
l CodeGearDelphi2005©
l CodeGearDelphi2009©
l MicrosoftVisualStudio2005,C++,MFC©
l MicrosoftVisualStudio2008,C++,MFC©
l MicrosoftVisualStudio2005,C++/CLI©
l Microsoft.NET ©(wrapperclassesarecontainedinthe“Examples”folder)
────────────────────────────────────────────────────────────────────────────────
Page 23
────────────────────────────────────────────────────────────────────────────────
Guidelinesandhints
Introduction
ItisrecommendedtobefamiliarwiththeGeViScopesystemandthepossibilitiesofmodern
videosurveillancesystemsandvideomanagementsystems.Beforestartingprogramming
yourcustomGeViScopeclientyoushouldknowbasicsofvideoformats,videocom-
pression,GeViScopeevents,GeViScopeactionsandtheprinciplesofaclient-servernet-
workcommunication.
ThefollowingsectionssupportyouwithsomesuggestionsandhintsaboutusingtheSDK
interfaces.
Generalhints
IfyourapplicationneedstolistentoeventsandactionspleaseusetheapplicationPLCSim-
ulator.exethatyoucanfindonYourGeViScopedevice.Thissoftwareallowsyoutostart
actionsandeventswhichmightbeusedbyyourprogram.
YoushouldworkanddosometestswitharealGeViScopedeviceorwiththevirtualtest
environmentbelongingtotheSDK.Createsomeeventsandactions,startthemwith
PLCSimulator.exe.
StartingthesetupsoftwareGSCSetup.exewiththecommandlineparameter/utilitieswill
offeryouthepossibilitytoopenDBITesttodiscoverthedatabasestructureandtoevaluate
andtestselectstatementsagainstthedatabase.Additionallythistooloffersyouthepos-
sibilitytostarttheregistryeditortoevaluatetheinternalstructureoftheGeViScopesetup.
MakesuretodeleteallobjectsthatarecreatedinsideofDLLs.Theobjects
themselvesshouldalwaysofferaDestroy()orFree()methodforthat.
Callbackfunctions,whicharecalledoutoftheSDKDLLs,arecalledfromthreads,which
werecreatedinsidetheDLLs.Variablesandpointersthatarepassedasargumentsofthe
callbackmaynotbeusedoutsidethecallbackcontext.Theyareonlyvalidfortheduration
ofthecallbackcall.
StructuresthatareusedasargumentsforSDKfunctionsshouldalwaysbeinitializedbythe
functionmemset().Aftersettingallthestructureelementstozero,thesizeorstructsizeele-
menthastobeinitializedwiththesizeof()function.
MPEG-2filesthatwerecreatedbySDKfunctionscanpossiblynotbeplayedwiththewin-
dowsmediaplayer.ThereasonisamissingMPEG-2decoder.WerecommendusingDVD
playersoftwarelikePowerDVDortheVCLMediaPlayersoftware.
Workingwithhandlesandinstances
IntegralpartoftheSDKareunitsthatgivetheuseracomfortableaccesstotheplainfunc-
tionsoftheDLL,e.g.GSCDBI.h/.cpp/.pas.Intheseunitsclassesencapsulateaccessto
instancesofobjectswhicharecreatedinsidetheDLL.Tohaveaccessfromoutsidethe
DLL(customapplication)totheinsideresidinginstances,handlesareused.Theunitshave
tobeaddedtotheprojectrespectivelytothesolutiontoavoidlinkererrors.
────────────────────────────────────────────────────────────────────────────────
Page 24
────────────────────────────────────────────────────────────────────────────────
Afterworkwithinstancesisfinished,theinstanceshavetobedeletedbycallingtheirdes-
troy()orfree()method.Otherwisetherewillbememoryleaksleft.
UsingtheplainexportedfunctionsoftheDLLisnotrecommended.Togetaccesstofull
functionalityyoushouldusetheunitsinstead(pasfilesorh/cppfiles).
Thefollowingexample(inpseudocode)shouldillustratetheabovefacts:
 //defineahandletoaserverobject
 HGscServerMyServer;
//createaserverobjectinstanceinsidetheDLLand
 //getahandletoit
 MyServer=DBICreateRemoteserver();
 ...
//workwiththeobjectinstancewiththehelpofthehandle
 MyServer->Connect();
 ...
 //defineahandletoaPLCobject
 HGscPLCPLC;
  //createaPLCobjectinstanceinsidetheDLLand
 //getahandletoit
 PLC=MyServer.CreatePLC();
 ...
//workwiththeobjectinstancewiththehelpofthehandle
 PLC->OpenPushCallback(...);
 ...
//destroyPLCobject
 PLC->Destroy();
 ...
 //destroyserverobject
 MyServer->Destroy();
InteractionbetweenDBIandMediaPlayer
TheDBIinterfacegivesaccesstoGeViScopeserverfunctionality.Aftercreatingan
instancewiththefunctionDBICreateRemoteserver()aconnectiontotheservercanbe
establishedbycallingthemethodConnect()oftheserverobjectinstance.
Thefollowingmethodsofaserverobjectinstancecanbecalledtogetaccesstodifferent
kindsoffunctions(notacompletelist):
────────────────────────────────────────────────────────────────────────────────
Page 25
────────────────────────────────────────────────────────────────────────────────
Method Function
CreateDataSet(),
CreateDataPacket()
Fetchdatafromserverdatabase
CreateLiveStream() Fetchlivedatafromserver
CreateRegistry() Fetchsetupdatafromserver(mediachannelinformation,event
information,…)
CreatePLC() Listento,createandsendactions
Theexample(inpseudocode)ofthepreviouschaptershouldillustratetheabovefacts.
TheMediaPlayerinterfaceofferssimpletouseobjectstodisplayliveandrecordedvideoin
windowscontrols.Aviewerobjectinstanceneedstobecreatedbycalling
GMPCreateViewer().Theviewerneedsahandletoawindowscontrolandahandletoa
serverobjectinstance.Ithandlesfetchingdata,decompressingdataanddisplayingvideoin
thelinkedwindowscontrolbyitself.
Thefollowingmethodsofaviewerobjectinstancecanbecalledtogetaccesstodifferent
kindsoffunctions(notacompletelist):
Method Function
ConnectDB() Fetchvideodatafromthedatabaseanddisplayitinanyplaymoderequired.
Filterandsearchcriteriacanoptionallybedefined.
SetPlayMode
(pmPlayNextEvent)
Displaythenextavailableeventpictures
Thefollowingexample(inpseudocode)showshowtocreateavieweranduseitafter-
wards:
//defineahandletoaviewerobject
 HGscViewerMyViewer;
//createaviewerobjectinstanceinsidetheDLLand
//getahandletoit
 MyViewer=GMPCreateViewer(WindowHandle,...);
//defineastructurewithdataneededtolink
//theviewertoamediachannelintheserver
 TMPConnectDataMyViewerConnectData;
  //handletotheserverobjectinstance
 MyViewerConnectData.Connection=MyServer;
 MyViewerConnectData.ServerType=ctGSCServer;
 MyViewerConnectData.MediaType=mtServer;
 //IDofthemediachannelthatshouldbedisplayed
 MyViewerConnectData.MediaChID=...
//linktheviewertoamediachannelanddisplaylivedata
 MyViewer->ConnectDB(MyViewerConnectData,pmPlayStream,...);
 //destroyviewerobject
  MyViewer->Destroy();
BesidetheviewerobjectclassthereisanotherclassintheMediaPlayerinterface:Theoff-
screenviewerobjectclass.Ifyouwanttodecompressmedia,whichshouldnotbe
────────────────────────────────────────────────────────────────────────────────
Page 26
────────────────────────────────────────────────────────────────────────────────
displayedwiththehelpoftheviewerobject,youcanusetheoffscreenviewerobject.An
instancecanbecreatedwiththefunctionGMPCreateOffscreenViewer().Theoffscreen
viewerobjectinstanceprovidesnearlythesamefunctionalityastheviewerobjectclass
does.Thevideofootageisnotrenderedinawindow,itisdecompressedinaspecialDecom-
pBufferobjectinstance.Afterthedecompressionisdoneinsidetheoffscreenviewer,the
hostingapplicationcanbenotifiedwiththehelpofacallbackfunction.Insidethecallback
thedecompressedimagecanbeaccessed.
TheDecompBufferclassencapsulatesspecialfunctionsforeffectivedecompressing.Soit
isrecommendtouseit.Creatinganinstanceofthebuffercanbereachedbycallingthefunc-
tionGMPCreateDecompBuffer().Theinstancecanbeusedforasmanydecompressions
asneeded.ThemethodGetBufPointer()givesaccesstotherawpicturedatainsidethebuf-
fer.
Hereisashortexample(inpseudocode)howtoworkwithanoffscreenviewerobject:
 //defineahandletoaDecompBufferobject
 HGscDecompBufferMyDecompBuffer;
 //createaDecompBufferobjectinstanceinsidetheDLLand
 //getahandletoit
 MyDecompBuffer=GMPCreateDecompBuffer();
 //defineahandletoaoffscreenviewerobject
 HGscViewerMyOffscreenViewer;
 //createanoffscreenviewerobjectinstanceinsidetheDLLand
 //getahandletoit
 MyOffscreenViewer=GMPCreateOffscreenViewer(MyDecompBuffer);
 //setcallbackoftheoffscreenviewerobject
 MyOffscreenViewer.SetNewOffscreenImageCallBack(NewOff-
screenImageCallback);
 //defineastructurewithdataneededtolink
 //theoffscreenviewertoamediachannelintheserver
 TMPConnectDataMyOffscreenViewerConnectData;
//handletotheserverobjectinstance
 MyOffscreenViewerConnectData.Connection=MyServer;
 MyOffscreenViewerConnectData.ServerType=ctGSCServer;
 MyOffscreenViewerConnectData.MediaType=mtServer;
 //IDofthemediachannelthatshouldbedecompressed
 MyOffscreenViewerConnectData.MediaChID=...
//linktheoffscreenviewertoamediachannelanddecompresslivedata
 MyOffscreenViewer->ConnectDB(MyOffscreenViewerConnectData,pmPlayStream,
...);
 ...
 //destroyoffscreenviewerobject
 MyOffscreenViewer->Destroy();
 //destroyDecompBufferobject
────────────────────────────────────────────────────────────────────────────────
Page 27
────────────────────────────────────────────────────────────────────────────────
 MyDecompBuffer->Destroy();
 ...
 //callbackfunction,thatiscalledafterimageshavebeendecompressed
 ...
 //getarawpointertothepictureintheDecompBuffer
 //object
 MyDecompBuffer->GetBufPointer(BufferPointer,...);
 //copythepictureintoawindowsbitmapresource
 //forexample
 SetDIBits(...,BitmapHandle,...,BufferPointer,...,DIB_RGB_COLORS);
 ...
Enumerationofsetupdata
GeViScopeServerresourcescanbeenumeratedbycustomapplications.Thesetupobject,
whichcanbeinstantiatedbycallingtheservermethodCreateRegistry(),offersfunctionality
forthis.
Enumerationofresourcesnormallyisdoneinfoursteps:
1. DefineanarrayoftypeGSCSetupReadRequestwiththeonlyelement“/”.This
causesthemethodReadNodes()totransferthewholesetupfromtheservertothe
customapplication.
2. CallthemethodReadNodes()ofthesetupobjecttogetthewholesetupfromthe
server.
3. CalloneoftheGet…()methodsofthesetupobjecttogetanarrayofGUIDsrep-
resentingthelistofresources.TherearedifferentGet…()methods,e.g.GetMe-
diaChannels()orGetEvents().
4. UsetheGUIDarraytoreceivetheresourcesdatabycallingGet…Settings()meth-
ods,e.g.GetMediaChannelSettings()orGetEventSettings().
Hereisanexample(inpseudocode),thatshowshowtoenumeratethemediachannels:
 ...
//connecttotheserver
 MyServer->Connect();
 ...
//defineahandletoasetupobject
 HGscRegistryMySetup;
 //createasetupobjectinstanceinsidetheDLLand
 //getahandletoit
 MySetup=MyServer->CreateRegistry();
//defineaarrayforthesetupreadrequest
 GscSetupReadRequestSetupReadRequest[1];
 SetupReadRequest[0].NodeName="/";
────────────────────────────────────────────────────────────────────────────────
Page 28
────────────────────────────────────────────────────────────────────────────────
//readthesetupdatafromtheserver
 MySetup->ReadNodes(&SetupReadRequest,...);
 //defineaGUIDarrayfortheGUIDsofthe
 //existingmediachannels
 GuidDynArrayMediaChannels;
//gettheGUIDarrayoutofthesetupdata
 MySetup->GetMediaChannels(MediaChannels);
//getthedataofeachsinglemediachannel
foreachMediaChannelGUIDinMediaChannels
 MySetup->GetMediaChannelSettings(MediaChannelGUID,
 MediaChannelID,
  GlobalNumber,
 ...);
 ...
//destroysetupobject
 MySetup->Destroy();
//destroyserverobject
 MyServer->Destroy();
  ...
Pleasenotethatespeciallythemediachannelscanbeenumeratedbyusingtheglobalfunc-
tionGMPQueryMediaChannelList()oftheMediaPlayerinterfaceaswell.
PLC,actionsandevents
ThePLC(PrcessLogicControl)objectsupportsyouwithfunctionalityforhandlingnoti-
fications,actionsandevents.ThemethodCreatePLC()oftheserverobjectclasscreatesa
handletoaPLCobjectinsidetheDBIDLL.
ThefollowingmethodsofaPLCobjectinstancecanbecalledtogetaccesstodifferent
kindsoffunctions(notacompletelist):
Method Function
SendAction() Sendanactiontotheconnectedserver
StartEvent() Startaneventoftheconnectedserver
SubscribeActions() Subscribealistofactionsthatshouldbenotifiedbyaregisteredcallback
function
OpenPushCallback
()
Registeracallbackfunction,thatiscalledifannotificationarrivesora
eventstarts/stopsorifoneofthesubscribedactionsarrives
ToreceiveNotificationsandactionsacallbackfunctioncanberegisteredwiththemethod
OpenPushCallback().Afterreceivinganaction,theactionshouldbedecodedanddis-
patchedbytheaninstanceoftheclassGSCActionDispatcher.Theactiondispatchergives
youasimplewaytoreactonspecificactions.Hereisashortexample(inpseudocode):
────────────────────────────────────────────────────────────────────────────────
Page 29
────────────────────────────────────────────────────────────────────────────────
 //initializationcode:
 ...
 //connecttotheserver
 MyServer->Connect();
 ...
//defineahandletoaPLCobject
 HGSCPLCPLC;
 //createaPLCobjectinstanceinsidetheDLLand
 //getahandletoit
 PLC=MyServer.CreatePLC();
  ...
 //linkyourcallbackfunctionforacustomaction
 //totheactiondispatcher,sothatthecallbackfunction
 //iscalledautomaticallyifacutsomactionarrives
 ActionDispatcher->OnCustomAction=this->MyCustomActionHandler;
 //registeracallbackfunctionfornotifications,
 //eventsandactions(thiscallbackfunctiondispatches
 //allreceivedactionswiththehelpofthe
 //GSCActionDispatcher)
 PLC->OpenPushCallback(...);
 ...
//destroyPLCobject
 PLC->Destroy();
 ...
//destroyserverobject
 MyServer->Destroy();
 //callbackfunctionforallnotifications,eventsand
 //subscribedactions:
 ...
 //dispatchthereceivedactiontothelinked
 //callbackfunctions
 ActionDispatcher->Dispatch(ActionHandle);
 ...
MediachannelIDs
TheexistingmediachannelscanbedisplayedbytheviewerobjectsoftheMediaPlayer
interface.NormallythisisdonewiththemethodConnectDB().Thismethodneedsthe
────────────────────────────────────────────────────────────────────────────────
Page 30
────────────────────────────────────────────────────────────────────────────────
mediachannelIDtoidentifythemediachannel(camera)thatshouldbedisplayed.
ThemediachannelIDsaregeneratedautomaticallybytheGeViScopeserver.Everycre-
atedmediachannelgetsanIDthatisalwaysunique.Soifyouremovemediachannelsfrom
thesetupandaddthemagain,theywillsurereceivesomenewIDs.
ForthatreasonmediachannelsshouldnotbeaccessedbyconstantIDs.Itisrecommend
usingglobalnumbersinstead,becausetheycanbechangedinthesetup.Tofindthefitting
mediachannelIDforagivenglobalnumber,themediachannelsshouldbeenumeratedfrom
theserversetup.Pleaserefertochapter“Enumerationofsetupdata”inthisdocumentto
seehowthisisdone.
Thereisasimilardifficultywithevents,digitalinputsandoutputs.Eventsdonthaveglobal
numbers.Heretheeventnameshouldbeusedinstead.
Handlingconnectioncollapses
ThecallbackOpenPushCallback()ofthePLCobjectenablestolistentodifferentkindsof
notificationsfromthePLCobject.Oneisthe“plcnPushCallbackLost”notification.Itisfired
ifaconnectionisinternallydetectedascollapsed.Asareactiononthiseventyoushould
destroyorfreeallobjectsthatwerecreatedinsidetheDLLsandstartaphaseofreconnect
tries.Thereconnecttriesshouldstartevery30secondsforexample.Additionallyyour
applicationcanlistentoUDPbroadcaststhataresentbytheGeViScopeserver.Afteryour
applicationreceivedthisbroadcastitcandirectlytrytoreconnecttotheserver.Pleasebe
awareofthefact,thatbroadcastsonlyworkinLANroutersnormallyblockbroadcasts.
UsingMediaPlayerwithGeViScopeandMULTISCOPEIII
servers
GenerallytheMediaPlayerinterfacecanbeusedwithGeViScopeaswellasMULTISCOPE
IIIservers.Tolinktheserverconnectiontotheviewerobject,theconnectiondatastructure
hastobedefined.Thetypeofthestructureis“TMPConnectData”.Theelement“Server-
Type”identifiesthekindofserverwhosemediashouldbedisplayedintheviewer.
Pleasehavealookontheexample(inpseudocode)inthechapter“InteractionbetweenDBI
andMediaPlayer”inthisdocument.
Forcreatingdifferentkindofconnections,differentDLLshavetobeused.ForGeViScope
theDLL“GSCDBI.DLL”andforMULTISCOPEIIItheDLL“MscDBI.DLL”hastobe
includedintheprojectorsolutionofthecustomapplication.Theycancoexist.
HandlingaconnectiontoaMULTISCOPEIIIserverissimilartoGeViScope.Detailscanbe
foundintheMULTISCOPEIIISDKdocumentation.
UsingtheSDKwith.NET
TomaketheusageofthenativeWin32DLLseasierin.NETlanguageslikeC#orVB.NET,
theSDKcontainssomewrapperassembliesaroundtheplainSDKDLLs.