GeViSoft SDK Dokumentation |Documentation |Documentation |Documentatión Version 2012_1.7|Date19.07.2012 --- Page 1 --- GeViSoft SDK Introduction TheGeViSoftSDKallowsintegrating yourcustomsolutionsandproductswithGeutebrück’s GeViSoftsuite.Itincludesanapplication programming interface(API)withallnecessary DLLs,headers,exampleprojects,anddocumentation tohelpyougettingstartedwithyour integration easily. TheSDKsupportsC++andDelphi.Furthermore a.Netwrapperisincludedwhichallowsyou tousetheSDKfromC#.Itprovidesvariousexampleprojectsandsolutionsintheselan- guages. --- Page 2 --- GeViSoft GeViSoftisGeutebrück’s centralmanagement systemforvideocontrol.Itsmainfunctionis theswitchingofvideosignalsbetweendifferentcameras,monitorsandDVRsbycontrolling avideomatrixsystem.Alarmhandlingaswellastheremotecontrolofpan/tiltanddomecam- erasisafurtherfunctionality ofGeViSoft. GeViSoftcanalsobeusedtohandlegeneralpurposedigitalinputsandoutputsandthus allowsintegrating customsensortechnology andactuatingelementstotheGeutebrück sys- tem. Furthermore, differentperipherals commontovideocontrolsystems,likevideomotionanal- ysisoroperatorconsoles, canbemanaged. GeViSoft Architecture Thearchitecture ofGeViSoftfollowstheclient-serverparadigm. Theserversoftware(GeV- iServer)usualrunsonadedicated PC.ThishardwareplatformiscalledGeViStation. The combined systemofsoftwareandhardwareiscalledGeViControl. AtleastoneIOclientmusthandleconnections totheperipherals. Thisclientiscom- municating withtheGeViSoftserverandrunsonthesamemachine.ItiscalledGeViIO. TheGeViIOclientprovidestheinterfaces forthecommunication totheattachedperipherals likeaVX3matrixoraPTZ.Theseperipherals canalsobevirtualized. GeViServer andGeViIOcanbeconfigured fromtheGeViSetapplication. Theconfiguration is described indetailinchapterConfiguration ofGeViSoft. ThefollowingfigureshowsasetupofGeViSoftwithanattachedVX3,digitalIOandtwoPTZ devices. --- Page 3 --- --- Page 4 --- Figure1-GeViSoft Example Configuration Historically, therehasbeenademandtocontrolalargenumberofvideofeedswithalimited numberofmonitorsinsurveillance systems.Thishasleadtotheinventionofvideomatrixes liketheVX3,whichalloweddifferentcamerasignalstobedynamically routedtotheattached monitors.Theroutingcouldbeuserinitiatedortriggeredbyexternaleventslikealarmsordig- italinputs. Besidesthevideoroutingitwasnecessary toallowtheoperatortoremotecontrolPTZand domecamerasfromacentralconsoletoreactonalarmsorotherevents. Aconfiguration liketheonedescribed aboveisreflectedinthesetupaccording tofigure1. Nowadays analoguevideocamerasandmonitorsaregettingreplacedbyIPcamerasand PCsrunningsoftwareviewerslikeGSCView. GeViSoftallowsthehandlingofthesemodern setupsaswellsothattheycanbeintegrated seamlessly intoexistinginstallations. Figure2givesanexampleforacomplexsetupintegrating analogueaswellasdigitalcom- ponents. --- Page 5 --- Figure2-Complex GeViSoft Setup --- Page 6 --- Additional tocontrolling thecrossswitchinginsidethematrix,GeViSoftcanbeusedtocom- municatewithGeViScopes. ItispossibletoconfigureGeViSoftinsuchawaythataGeV- iScopeandtheconnected GscViews canbecontrolled justlikeananaloguevideomatrix, e.g.aVX3. Thenextchaptergivesanoverviewofthedifferentcomponents thatadduptoGeViSoft. GeViServer GeViServer isthebackendserverinaGeViSoftsystem.Italsomanagestheinternaldata- base.GeViServer usuallyrunsasaWindowsserviceonproduction machines, butcanalso bestartedasaconsoleapplication fortestingpurposesordebugging. IfinstalledbytheSDK setup,theGeViServer mustbestartedfromtheconsole. ItispossibletorunGeViServer inaclustertoincreasereliability. GeViAdmin Theapplication GeViAdmin isusedtosetuptheGeViServer database. Itcanalsobeusedto configureredundancy settingsbyclustering severalGeViServers. Furthermore, GeViScope canbeusedfordiagnostics andloadanalysis.GeViAdmin ispartoftheshippingproduct,but notoftheSDK.TheSDKinstallerautomatically setsupaGeViSoftdatabaseduringthe installation process. GeViIO TheGeViIOclientisresponsible forthecommunication withtheexternalinterfaces and peripherals. ItrunsonthesamemachineastheGeViServer. Otherinstances ofGeViIO mightrunonseparatemachines. --- Page 7 --- GeViSet GeViSetistheconfiguration toolforGeViServer. ItcanbeusedtoconfigureGeViIOclients, users,events,alarmsandallotherfunctionalities ofGeViServer, aswellasconnections to GeViScope servers.Someconfiguration stepsandoptionsinsideGeViSetareshowninthe followingchapters. GeViAPI TestClient TheGeViAPITestClientallowstestinganddebugging GeViSoftapplications. Withthistool youcansendandreceiveactionsandalarms,querythedatabase, andretrievesysteminfor- mation. --- Page 8 --- SDKIntroduction TheGeViSoftSDKprovidesyouwithanopenapplication programming interfacetotheGeV- iSoftsuiteandallowsyoutointegrateyourcustomproductswithGeutebrück’s. TheSDKincludestheDLLsandcorresponding headerfilesrequiredbyyourC++orDelphi projects.Furthermore .NetwrapperDllsareincludedwhichallowyoutousetheSDKfrom yourC#application. Severalexampleapplications helpyougettingstartedwiththeGeViSoftSDKdevelopment andmayactasafoundation foryourownsolutions. FilesandDirectory Structure Duringinstallation, theenvironment variable%GEVISOFTSDKPATH% isset.Itpointstothe rootdirectoryoftheSDKinstallation. Thevariable’svalueisdetermined bythepathchosen astheinstalldirectoryduringsetup.Usually,thisis“C:\GEVISOFT”. AllSDKdirectories are locatedinsidethisrootdirectory. Thisisa(partial)treeviewofthestandardinstallation: --- Page 9 --- --- Page 10 --- PleasenotethatthedirectoryC:/GEVISOFT/DATABASE willbecreatedwithoutregarding thechoseninstallpath.ThisdirectoryhoststheGeViSoftdatabaseGeViDB.mdb whichis hiddenbydefault. Insidethe%GEVISOFTSDKPATH% directory,astructurelikethisiscreated: lADocumentation foldercontaining allGeViSoftrelateddocumentation andmanuals. lAnExamples folderincludingsubfolders thatarenamedaccording tothecor- responding IDEandprogramming language. -Insideeachofthese,thereisaGeViScopeSDK andGeViSoftSDK folderwiththe respective IncludeandLibfoldersfortheprogramming languageaswellasthefolders withthedifferentexamples. -TheC++headersarelocatedinsidetheIncludefolderandthelibrariesinsidetheLib folder. -ForDelphi,the.pasandthe.incfilescanallbefoundinsidetheIncludefolder. The%GEVISOFTSDKPATH% directoryitselfhostsalltheexecutables, dynamiclinklibraries,and runtimefilesthatareneededbyGeViSoft. Bydefault,alltheexampleprojectswilloutputtheir generated binariesintothisfolderaswell.Thisguarantees thatallruntimedependencies are metandyourcompiledexecutables findtheneededDLLs. Additionally, the.Netwrapperassemblies Geutebrueck.GeViSoftSDKNetWrapper.dll and GscActionsNET.dll resideinthisfolder. --- Page 11 --- SDKSetup SetupofTest/Build Environment Thischapterdescribes howtosetupandconfiguretheGeViSofttestenvironment.  NOTICE Pleasenotethatyouneedadministrative privileges onthedevelopment machine. Installation ofGeViSoft TheSDKisshippedasanexecutable installer.Youjustneedtorunitonyourdevelopment machinein ordertoinstalltheSDK.  NOTICE Itishighlyrecommended toinstallGeViSoft tothedefaultpathC:/Gevisoft.  WARNING PleasemakesurethatyoudonotinstalltheSDKonaproduction GeViSoft machine asthesetup willoverwrite theinstalled GeViSoft fileswithout notice. Starting GeViServer YoucanstartGeViServer fromthecommand promptbyissuingthecommand %GEVISOFTSDKPATH%/geviserver.exe console orbyexecuting thestartserver.bat scriptinyourGeViSoftinstallation’s rootfolder.The consoleargumentforcesthesoftwaretorunasaconsoleapplication andallowsyouto --- Page 12 --- easilymonitortheserver’soutput.Onaproduction machine,GeViServer usuallyrunsasa windowsservice.  NOTICE Pleasenotethatwithout alicensedongle, theserverwillterminate aftertwohours.Youcan directly restartitwithout anyfurther restrictions. Configuration ofGeViSoft Inthischapteryouwilllearnhowtoestablishaconnection totheGeViServer withthesetup clientGeViSet(Settinguptheserverconnection ). Afterthatthereisadescription forsettingupaGeViIOclientthatprovidesavirtualvideo matrixanddigitalIO(Configuration oftheGeViIOClient).Youdonotneedtocarryoutthe stepsdescribed inthatparagraph. Theyareforreferenceonlybecausethisconfiguration is alreadydoneforyouinthedatabasethatisdeliveredwiththeSDK. Settinguptheserverconnection 1StartGeViServer byexecuting startserver.bat ifnotalready doneso 2StartGeViSet.exe 3Setuptheserverconnection aOpenFile->GeViSoft serverconnections bIfaconnection localhost exists,pressConnect andmovetostep4 cIfnoconnection existschooseConnections ->NewConnection dEnterlocalhost asthenameofthenewconnection andpresstheForward button eIntheCreateNewServerConnection window setthecomputer nametolocalhost , theusernametosysadmin .CheckSavepassword andsetthepassword tomas- terkey.SelectLocalconnection asconnection type.PresstheForward button. Choose thelocalhost connection andpressConnect --- Page 13 --- Configuration oftheGeViIOClient(reference) TheGeViIOclient’sconfiguration isalreadydoneforyouinsidethedatabasethatisshipped withtheSDK.Thestepsdescribed hereareonlyareferenceforyouifyouneedtoadaptset- tingsforyourtestenvironment. 1.IntheClientsfieldpushtheAddbuttonandaddanewGeViIOclientwiththename GeViIO_ 01. 2.SelectthenewGeViIOclientandpressConfigure. 3.MarktheclientasActiveandVirtual. 4.AddanewVX3matrixbypressing AddintheInterfaces fieldandselectingtheappro- priatetype(VX3/CX3).Nametheinterface VirtualVX3. 5.SelectthenewlycreatedVX3interfaceandpressEdit. 6.Add16newvideoinputstotheVX3interfacebypressingtheAddbuttonintheVideo inputstab.IntheNewvideoInputwindowsetCountto16andpressok.Thenew videoinputchannelsshouldshowupintheVideoinputtab. 7.Add4newvideooutputsinthesamemannerastheinputs. 8.Add8newinputcontactsand8newoutputcontactsinthesamewayyoudidforthe videoinput. 9.Sendyournewlycreatedsetuptotheserverbychoosing File->Setuptoserverorby clicking . Nowyourclientwindowshouldlooklikethis: --- Page 14 --- Connection toGeViScope (optional) IfyouhaveaGeViScope serverupandrunning,youcanconnectGeViSofttoitviaaTCP/IP connection. Ifconnected, actionscanbeexchanged betweenthetwosystems.Asan --- Page 15 --- examplethiscanbeusedtoremotecontrolGSCView. PleasenotethatyoucaninstalltheGeViScope ServerasapartofGeutebrück’s GeViScope SDKifyouhavenotdoneityet.YoucandownloadthisSDKonwww.geutebrueck.com or requestitfromtheSDKdivision. InstallingtheGeViScope SDKisaprerequisite forthescenarioandexampleinthechapter Switching Video. Youcanconfiguretheconnection toGeViScope insideGeViSet.ChoosethemenuServer-> GeViScope Connections andpressAddinthepop-upmenu.Youcanthenconfigurethecon- nectionparameters insidetheGeViScope connection window.  NOTICE PleasenotethattheAliasisusedtoaddressdifferentGeViScope serversfrominsidethe SDKwithGSCActions. SeeActionmessages –>creatingactionmessages >4.Exampleofcre- atingaGeViScope ActionMessage --- Page 16 --- FirstStepswithGeViSoft Thischapterwillleadyouthroughout yourfirststepswithGeViSoft. Youwilllearnhowtocon- necttoaGeViServer, sendsomebasicactions,andcustomize messagelogginganddisplay toyourneeds.IfyouarealreadyfamiliarwithGeViSoft, youcanskipthischapterorskim throughit. GeViAPI TestClient TheeasiestwaytotestyourGeViSoftsetupisbyusingtheGeViAPITestClient.Youcan startitfromyour%GEVISOFTSDKPATH% directory. PleasemakesurethatyourGeViServer isalreadystarted.Ifnotstartitbyexecuting the “startserver.bat” insidetheGeViSoftrootdirectory. AfterstartupconnecttotheGeViServer byaddingyourcredentials andpressingthe“Conn” button.Ifeverything worksout,the“Connected” indicatorwillbeilluminated ingreenandsev- eralmessages willpopupinthe“Communication log”.Atthispointyourcommunication is setupcorrectly. Ifyouhavefollowedtheconfiguration stepsinchapterSettingupGeViIOyouwillalreadybe abletouseGeViSoftforswitchingyourvirtualvideoI/O. CrossSwitching Video SelectthetabVideo/DigIO .Youcanswitchyourvideosignalinthefollowingway: 1.Selectanactiveinputandanactiveoutput.Thesignalwillbeswitchedbetweenthese two.YoucanseetheactiveI/OonthewindowsrighthandsidebeneaththetextVideo. a)Toselectanactiveoutput,left-clickononeofyourconfigured videooutputsinthe upperwindowarea.YoushouldseeActOutchangingwithregardtoyourselection. --- Page 17 --- b)Nowmovethemouseoverthedesiredinput(e.g.7)andright-clickontheinput. Thenumberofyourselectedinputshouldnowappearintheblacksquareaboveyour selectedoutput. 2.Clearavideooutput.Movethemouseovertheoutputtoclearandright-clickonit.The numberintheblacksquareabovetheoutputshouldvanish. --- Page 18 --- --- Page 19 ---  NOTICE Whenswitching theoutput, aCrossSwitch actionwiththechosen channels isdisplayed inthe Communication LogshowninthelowerpartoftheGeViAPI TestClient’s window. IfarealVX3wouldbeconnected toyourGeViSoftandtheinputswereconnected tovideosig- nals,youwouldswitchtherealsignaltotheaccording output(normallyamonitor).Youwill learnhowtousetheseswitchactionstoremotecontrolaGscViewinthesamewayyou woulduseananaloguematrixinthechapterSwitching Video. Manipulating DigitalI/O Similartothevideosignalsyoucanswitchdigitaloutputsandgeneratedigitalinputsignalsin yourvirtualtestclient. Generateasimulated digitalinput: Togenerateaninputmoveyourmousepointeroverthedesiredinputchannel.Aleftclick willsimulateaclosingofthecontact,arightclickanopening.Thecontacts’statesare colorcodedaccording tothistable: Color State White Unknown Red Closed Green Open Gray Unavailable Generateasimulated digitaloutput: Togenerateanoutputmovethepointeroverthedesiredoutputsignal.Left-clickingwill settheoutput’sstatetoopen,right-clickingtoclose. Theoutputs’statesarecolorcoded according tothistable: Color State White Unknown Red Closed --- Page 20 --- Green Open Yellow Alternating (CanbesetviaAlternate Contact action) Gray Unavailable Information IftheGeViIO clientwasconnected torealDIOhardware, youcouldseetheinput signals changing inrealtime.Setting oftheoutputs would result inswitching realloads. --- Page 21 --- Actions SofaryouonlyusedGeViAPITestClient’sbuilt-infunctionality tointeractwithGeViServer. InthischapteryouwilllearntouseGeViSoftactionstocontrolthesystem. GeViSoftactionscanbesentbytypingthemintothetextboxinthelowermiddleoftheGeVi- APITestClient’swindow.Youcanfindacompletelistofthepossibleactionsinthedoc- umentation. Hint Youcaninteractively generate actions andlearnabouttheirparameters bycom- posing theminGeViSet. Therefore, openGeViSet, andconnect totheserver. Thennavigate toServer ->Named actions andpressAddinthewindow that popsup.Inthewindow Named action settings youmaypressthebutton withthe threedots(“…”)totakeyoutotheAction settings menu. Thereyoucanchoose anyoftheimplemented actions andviewtheirparameters andsettings. Tofiltertheactions bycategory choose oneofthecategories from theupper leftlistbox.Hoover themouse overanyoftheparameters togeta detailed description ofit. Asanexample select Crossbar control asacategory andmovetoCrossSwitch to seethemessage’s parameters ontherightside. Thecomplete message is: CrossSwitch (IDVideoInput, IDVideoOutput, Switchmode) . CrossSwitching Video 1.Routevideofromaninputtoanoutput--Tosendthevideofrominput7tooutput3,do thefollowing: --- Page 22 --- a)TypethisactionintothetextboxinthelowermiddleoftheGeViAPITestClient windowandsendit: CrossSwitch (7,3,0) b)Makesurethatthesignalisroutedaccordingly bycheckingtheoutputinthetab Video/DigIO c)Routevideoinput3tooutputchannel2.(CrossSwitch (3,2,0)) 2.Clearvideooutput2:ClearVideoOutput (2) --- Page 23 --- Crossswitching video1 --- Page 24 --- Manipulating DigitalI/O 1.Opencontact1andclosecontact2--TheactionsOpenContact (ContactNumber) and CloseContact (ContactNumber) canbeusedtosetthedigitaloutputsfromGeViSoft. a)Toopencontact1sendtheaction:OpenContact (1) b)IntheTabVideo/DigIO ofGeViAPITestClientmakesurethattheindicationof outputonehasturnedtogreen c)Toclosecontact2sendtheaction:CloseContact (2) d)Makesurethattheoutputturnedred. 2.Simulateaclosingoftheinputcontact3andanopeningoftheinputcontact5 a)InputContact (3,true) b)Makesurethatinput3issignaling closed(redindication) c)InputContact (5,false) d)Makesurethatinput5issignaling open(greenindication) 3.Alternating acontact --Simulateaflashlightonoutput8 a)Toalternateacontact,youcanusetheactionAlternateContact (ContactID, BlinkPeriod_ in_ms,BlinkOnTime_ in_ms) b)Sendthecommand toflashthelightwithafrequency of1Hzandadutycycleof 500ms: AlternateContact (8,1000,500) --- Page 25 --- c)Checkthatthecontactisalternating –afterpressingtheRefreshbutton,theout- put8stateshouldbealternating (yellow). --- Page 26 --- --- Page 27 --- Manipulating digitalIO --- Page 28 --- GETAS InthischapteryouwilllearnaboutGETAS,theGeutebrück TelnetActionServer.The GETAScomponent allowsyoutosendandreceiveGeViSoftactionsviatelnet.Multiple clientscanconnecttooneGeViServer atatime. Thetelnetinterfaceallowsyoutoeasilyintegratesimpleapplications intoyourGeViSoftinfra- structure.Furthermore itoffersanoptiontoconnectnon-Windowsplatforms.  CAUTION Bydefault, GETASisnotactive.Toactivate GETAS, openGeViSet andnavigate toServer-> GETAS.IntheGETASsettings window, youcanthenactivate thecomponent bychecking Enable TCPport.BydefaultGETASwilllistentoport7707.Leavetheothersettings unmodified and pressOK.Sendthealteredsetuptotheserverafterwards (File->Setuptoserver).  CAUTION Toconnect toGETAS, youneedatelnetclient.YoucaneitherusetheWindows telnetclientora thirdpartyapplication likeputty.  ADVICE IfyouareusingWindows 7,thetelnetclientisnotactivated bydefault. Toactivate itgotoStart ->Control Panel->Programs andFeatures andselecttheTelnetClientfromthelistbox. NowyoucanconnecttoGeViServer andsendsomeactions. BasicGETASUsage 1.ConnecttoGeViServer viaGETAS–Openacommand window(cmd.exe) andstart telnet.Inacommand windowtype:telnetlocalhost 7707 --- Page 29 --- 2.Makesurethatyourinputisechoedlocallybyentering setlocalecho 3.Youmaywanttopressenteroncetoclearyourscreenifnecessary. 4.MakesurethatyoustartedyourGeViAPITestClientandconnected ittotheGeV- iServer 5.Sendanactiontotheserver: a)CustomAction (42,"HelloGETAS") b)Ifyoureceiveanechoofyouractionprecededbya4;fromtheGeViSoftserver, yourconfiguration isworking c)VerifythatyoucanalsoseetheactionintheGeViAPITestClient’scom- munication log.Ifyoucannotseethemessage, makesureyouareconnected and yourfiltersettingsinthetabFilterGeViSoftaresetcorrectly.Tobesure,setthe filtertoacceptallmessages. 6.Monitoractionssentbyotherclientsinyourtelnetsession: a)SendanactionfromGeViAPITestClient:CustomAction (23,"HelloGETAS client") b)Verifythatyoureceivedtheactioninyourtelnetwindow. VideoandIOControlwithGETAS 1.NowcontrolyourvirtualVX3byusingGETAS–MakesurethatGeViAPITestClient isrunningwhileyouissuecommands viatelnetandyoucanseetheVideo/DigIO tab. YourGeViIO_01configuration shouldbethesameasinchapterSettingupGeViIO. --- Page 30 --- 2.Routevideoinput7tovideooutput2: a)ConnecttotheGeViServer viatelnetinacommand windowifnotdoneityet. b)Send:CrossSwitch (7,2,0) c)MakesurethatthevideosignalisroutedcorrectlyintheVideo/DigIO tabofGeVi- APITestClient 3.Copythevideosignalfromoutput2tohaveitalsoonoutput4: a)Send:CopyCameraOnMonitor (2,4) b)Makesure,thatinput7isroutedtooutput2and4intheGeViAPITestClient 4.Clearthevideooutputonchannel2: a)Send:ClearVideoOutput (2) b)Makesurethecommand worked(GeViAPITestClient) 5.Closedigitaloutputcontact5: a)Send:CloseContact (5) b)Verifytheresultofthecommand inGeViAPITestClient GETASLimitations GETAScanbeusedforsimpleapplications orintegration ofnon-Windowsclients.Nev- erthelessthereisonelimitation. Thetelnetconnection isonlyestablished tooneserverata --- Page 31 --- time.IfGeViServer isrunninginaredundancy setup,theactionsarenotforwarded between thedifferentservers.  WARNING Ifyouplantointegrate yourGETASsolution intoacomplex setupwithmirroring, youhaveto takecareofthecommunication withthedifferent servers onyourown. Thishasnottobeconsidered ifyouareusingtheSDKfunctionality asdescribed inchapter SDKUsage.TheSDKfunctionswilltakecareofcommunicating withthevarioussystems. --- Page 32 --- ActionMapping Actionmappingcomesinhandyifyouneedtotriggeroneactionbyanother.Assumeyou wanttoswitchonabeaconifadoorisopened.Thebeaconisconnected toadigitaloutput2 andthedoortoadigitalinput3(whichopenstogetherwiththedoor).Theseactionscanbe mappedinthefollowingway. 1.InGeViSetselectServer–>Actionmapping 2.PressAddintheActionmappingwindow.TheActionmapping settingswindowwill open. 3.Pressthe…buttontoaddanewinputactionandchoosetheDigitalcontactscategory intheActionsettingswindow 4.SelecttheInputContact actionandsettheparameters GlobalContactID to3and ChangedTo tofalse.SetCaptiontodoorcontacthasopenedandpressOK. 5.Pressthe+buttontosettheoutputactionintheActionmapping settingswindow 6.Toflashabeacon,theoutputsignalmustalternatebetweenonandoff.Thiscanbe achievedwiththeAlternateContact action. 7.SettheAlternateContact action’sparameters toGlobalContactID =2,BlinkPeriod = 1000ms,andBlinkOnTime =500ms.EnterblinkthebeaconasCaption. 8.SendthesetuptotheGeViServer 9.TestthemappingbysendingtheactionInputContact (3,false)eitherbyGETASor insideGeViAPITestClient.YoushouldseethemappedactionAlternateContact (2, 1000,500)deliveredbytheGeViServer directlyafterwards. Youcanalsochecktheout- put’sstatusinGeViAPITestClient’sVideo/DigIO tabafterhittingtherefreshbutton. --- Page 33 --- 10.Toswitchoffthebeaconafterthedoorhasclosed,youneedtomapanotheraction pairinGeViSet.Forthat,mapInputContact (3,true)toCloseContact (2)andsend thesetuptotheGeViServer. 11.Checkifthebeaconisswitchedoffimmediately aftersendingtheactionInput- Contact(3,true) Pleasenotethatyoucanmapmultipleactionstooneinput.Thisallowsyoutorealizemore complexsetups. --- Page 34 --- Timer(optional) GeViSoftallowsyoutoconfiguretimerswhichcanscheduleactions,givingyouaversatile toolforcustomapplications. YoucanconfiguredifferenttypesoftimersinGeViSet.Timers internallycountin“ticks”.Eachtickequalsonemillisecond. TypesofTimers lOncetimer(singleshot)–thistimercountsdownforthenumberofmainticksafter beingstartedandattheendfirestheconfigured action lPeriodical timer–thistimerallowstriggeringactionsperiodically everytimeit reachesthenumberofmainticks.Afterfiringtheaction,thetimerrestartscounting ticksfromzero. lPeriodical timerwithembedded tick–thistimeractssimilartothesimpleperi- odicaltimer.Inaddition,itcanfireasecondactiononreachingthe“embedded tick” count.Asanexample,youcouldrealizeswitchingonandoffofabeaconlightwitha timerlikethis.Simplyclosetheoutputattheembedded tickandopenitatthemain tick. --- Page 35 --- Timer1 --- Page 36 --- Configuring aTimer 1.Torealizethebeacon’stimerselect„Server->„TimerinGeViSet. 2.Addanewtimer.Makesure,theActivecheckbox isticked.NamethetimerBea- conTimeranddescribeitasTimertotoggleabeaconondigitaloutput2 3.SettheTimertypetoPeriodical withembedded tick,themainticktooccurevery 1000ms,andtheembedded ticktooccurevery500ms.Thiswillgenerateatimerwith twotickspersecondandaspacingof500msinbetween. 4.PresstheEditbuttonOnembedded ticktosettheactionthatshalloccurwithevery embedded tick.ChoseOpenContact fortheGlobalContactID 2andgivetheactionacap- tionliketurnofbeacon. 5.Forthemaintick,settheactiontoCloseContact forthesameoutputandthecaption toturnonbeacon. 6.SendthenewsetuptotheserverandswitchtoGeViAPITestClient 7.YoucanstartthetimerbysendingtheStartTimer action.Thisactiontakestwoparam- eters,theTimerIDandtheTimerName .IfyouwanttoaddressatimerbyitsID,justsend anemptyTimerName .SendStartTimer (1,"BeaconTimer") 8.IntheVideo/DigIO tab,youshouldseethatoutput2toggleswithafrequency of1Hz. 9.Tostopthetimer,sendaStopTimer (1,"BeaconTimer") action.  NOTICE HintforusingStartTimer andStopTimer actions: GeViSoft firsttriestoevaluate thetimerbyTimerName andonlyifnonameisgivenbyID.Ifyou --- Page 37 --- useanonexisting name,thetimerwillnotbestarted, evenifyoustatetherightID.Ifyouwant tostartatimerbyID,sendanemptystringasname(e.g.StartTimer (1,"")). --- Page 38 --- Events(optional) Eventscanbeusedtocontrolcomplexbehaviorcausedbyastartconditionasatrigger.The GeViSofteventhandlingimplementation allowsaveryflexiblesetupofeventtriggersand resultingactions. --- Page 39 --- YoucanaddeventsinGeViSet(Server->Events->Add). Options forEvents Option Description Active Eventscanonlybetriggered ifmarked Active Trigger Enabled Iftriggerisenabled, theeventisrestarted iftheStartbycondition occurs again. RepeatActions IftheStartbycondition occurs, theOnstartactionisinvoked Adjustautostop timeIftheStartbycondition occurs, theelapsed Autostoptimeisresettozero Adjuststarttime Ifchecked, thestarttimeisadjusted onretriggering Stopbefore AutostopEnabled Ifenabled, theeventstopsafterthetimeframesetinStopafter Stopafter Periodoftimeafterwhichtheeventautomatically stops AutoStoponleaveof validtimerangesEventscanbeactivated forcertaintimerangesonly.Ifthisoptionis checked, theeventautomatically stopsifthevalidtimerangesareleft Timerangefield Listofallthetimerangeswheretheeventisactivated. Notethatifnotime rangeisgiven,theeventcannotbetriggered! Startby Listofactions thattriggertheevent.Ifmultiple actions areconfigured, any oftheactions willtriggertheeventonitsown(logical ORoperation) Stopby Listofactions thatterminate theevent.Ifmultiple actions areconfigured, anyoftheactions willstoptheeventonitsown(logical ORoperation) Onstart Listofactions thatareallexecuted oneventstart(logical AND) OnStop Listofactions thatareallexecuted oneventtermination (logical AND) Configuring anEvent 1.Hereisanexamplehowtoconfigureaneventthatroutesvideosignalsbasedondig- italinput--closingofcontact3triggerstheroutingofvideoinput3tovideooutput2.After 5seconds,theeventstopsandvideooutput2iscleared.Theeventwillbeconfigured for automatic retriggering. Herearethesettings: --- Page 40 --- Example ofanEvent 2.TheactionsforStartby,Onstart,andOnstopare: a)Startby:Contact3closed->InputContact (3,true) --- Page 41 --- b)Onstart:RoutevideoIn3toVideoout2->CrossSwitch (3,2,0) c) Onstop:Clearvideooutput2->ClearVideoOutput (2) 3.AfterthesetuphasbeensenttotheGeViServer, theeventcanbetestedwiththe GeViAPITestClient 4.Ifyouleftclickinputcontact3theeventisstarted.Youwillseethatvideoinputstream 3isroutedtovideooutput2.After5secondstheoutputisclearedagain.Youcanalso seetheeventbeingstartedinthecommunication log. 5.Theeventcanberetriggered. Ifyouleftclickinput3againwhiletheeventisrunning, the5secondautostoptimestartsoveragain. 6.YoucanalsostarttheeventbysendingaStartEvent message(StartEvent (ID, "MessageName") ). --- Page 42 --- Alarms(optional) Duetothelargeamountofvideocamerasconnected tomodernvideosurveillance systems, operatorscannotobserveallthestreamsatthesametime.Moreover, onlycertainincidents areofinterestorneedaction.Therefore, itishelpfulthatapreselection ofthevideomaterial showntotheuseriscarriedoutbythesystem.Oftenspecialactionshavetobetakenifapar- ticularsituationishappening. Asanexampleassumethataparkinglotwithabarrieratthe entranceisbeingmonitored. Theoperatorissupposed toopenthebarrieraftermakingsure thatawaitingvehicleisallowedtoenter.Normally, theoperatorwouldhavetowatchthe streamofthecamerapermanently andactonit.IncaseslikethisGeutebrück systemscan assistbyprovidingalarms.Alarmsareverysimilartoevents,butoffermoreversatileoptions forcustomizing anddefiningrequireduserinteraction. AlarmOptions GeViSetoffersseveraloptionsforalarms. Option Description Name Alarmname–canbeusedinactions Description Fieldforthedescription ofanalarm AlarmID Alarmidentifier --canbeusedinactions Active Alarmscanonlybetriggered ifmarked Active Priority Alarmscanhaveapriority from1(high)to10(low).Ahigherpriority alarmwilldisplace alowerpriority oneifconfigured tobeshownon thesamemonitor group Monitor Group Several monitors thatareaddressed asagroupforeasieradmin- istration Cameras Listofcameras thatarerelevant forthealarm.Theirpictures are shownonthemonitor groupincaseanalarmoccurs Retriggerable Ifchecked, thealarmcanberetriggered byitsinitialactivator. Popup(Retrigger) --- Page 43 --- Option Description Undoacknowledge (Retrigger)Ifset,thealarmhasalready beenacknowledged andthealarmis retriggered, thestatewillberesettonotacknowledged. Userspecific (Retrigger) Ifchecked, acustom listofactions canbeaddedwhichwillbe executed onaretrigger eventofthealarm StartbyAction Listofactions. Anyoftheactions willstartthealarm(logical OR) OnstartAction Listofactions. Alloftheactions willbesentonstart(logical AND) Acknowledge byAction Listofactions. Anyoftheactions willacknowledge thealarm(logical OR) Onacknowledge Action Listofactions. Alloftheactions willbesentonacknowledge (logical AND) QuitbyAction Listofactions. Anyoftheactions willquitthealarm(logical OR) OnquitAction Listofactions. Alloftheactions willbesentonquit(logical AND) Configuring anAlarm Configure analarmfortheparkinglotscenarioasdescribed above.Assumethatthedetec- tionofavehicleisdonebyasensorondigitalinput1(vehicleisdetectedonclose).After checkingifthevehiclemayentertheoperatormustopenthebarrier.Todosoheacknowl- edgesthealarmbypushingabuttonconnected todigitalinput2.Asthebarrieriscontrolled bydigitaloutput1theOnacknowledge actionmustopenthiscontact.Afterthevehiclehas passed,theoperatormustquitthealarmbypushingabuttonconnected todigitalinput3.On quitthebarriermustbeclosedbyclosingdigitaloutput1.Theparkinglotissurveilledbytwo camerasoninputs4and7.Duringthealarm,thesemustberoutedtooutputs1and2. 1.AlarmsaredisplayedinMonitorGroups.FirstdefineoneInGeViSet. a)Server->Monitorgroups->Add b)Setthegroup’sNameandDescription toMonitorGroup1 c)Addvideooutputs1and2tothegroup --- Page 44 --- d) Leavetherestofthesettingsastheyare 2.AddanewalarminGeViSet: Server->Alarms->Add a)IntheGeneraltab,setNameandDescription toParkingLot b)PresstheMonitorgroupbuttonandaddMonitorGroup1 c)AddVideoinput4andVideoinput7toCameras --- Page 45 --- AlarmSettings 1 --- Page 46 --- d)IntheActionstab,settheStartbyactiontoInputContact ,theGlobalContactID to 1andChangedTo totrue.AddtheCaptionvehicledetected e)SettheAcknowledge byactiontoInputContact ,theGlobalContactID to2and ChangedTo totrue.AddtheCaptionbuttonacknowledged pressed f) SettheOnacknowledge actiontoOpenContact ,andtheGlobalContactID to1. AddtheCaptionopeningbarrier g)SettheQuitbyactiontoInputContact ,theGlobalContactID to3andChangedTo totrue.AddtheCaptionbuttonquitpressed h)SettheOnquitactiontoCloseContact ,andtheGlobalContactID to1.Addthe Captionclosingbarrier --- Page 47 --- AlarmSettings 2 --- Page 48 --- 3.Sendthesetuptotheserver 4.TestthenewalarminGeViAPITestClient a)Clearvideooutputs1and2byright-clickingonthem. b)Simulatethearrivalofthevehiclebyleft-clickinginput1. c)Checkifthealarmistriggeredbyverifyingthatstreams4and7aredisplayedon monitors1and2.Notethattheoutputs’colorchangedtoredwhichindicatesan alarmfeed.YoushouldalsofindtheAlarmStarted ()actionintheCommunication log d)Acknowledge thealarmandopenthebarrierbyleft-clickinginputcontact2.Make surethatthisleadstotheopeningofoutput1andanAlarmAcked ()actionappearing inthelog. e)Quitthealarmbyleft-clickinginputcontact3.Thevideooutputs’colorshould changetogreenasthealarmhasfinished.Thebarrier(output1)shouldhaveclosed. --- Page 49 --- Switching Video Thoughmonitorgroupsdatebacktoanaloguevideorecording, theideabehindthemcomesin handywhencomplexsituations aretobepresented tooperators. InmodernCCTVsystems mostofthesourcesaredigitalonesandtheviewersrunassoftwareondedicated consoles. Nevertheless theconceptofmonitorgroupscanstillbereproduced withGeutebrück’s sys- tems.Thestandardviewer--GscView--canberemotecontrolled toshowpredefined scene setupsinawaysimilartomonitorgroups. InthischapteryouwilllearnhowtoswitchbetweentwouserdefinedGscViewscenesbytrig- geringaGeViSoftalarm.Youwillhaveanormal4-by-4scenedisplaying 16channelsoflive footagefromaGeViScope. OntriggeringanalarminGeViSoft, GscViewwillbeswitchedtoa 2-by-2scenedisplaying predetermined videochannels. Scenario Assumethefollowingsituation,whichiscloselyrelatedtoConfiguring anAlarminchapter Alarms: Configure analarmfortheparkinglotscenario.Assumethatthedetectionofavehicleisdone byasensorondigitalinput1(vehicleisdetectedonclose).Aftercheckingifthevehiclemay enter,theoperatormustopenthebarrier.Thishappensonacknowledging thealarmbypush- ingabuttonconnected todigitalinput2.Asthebarrieriscontrolled bydigitaloutput1,theOn acknowledge actionmustopenthiscontact.Afterthevehiclehaspassed,theoperatormust quitthealarmbypushingabuttonconnected todigitalinput3.Onquitthebarrierhavetobe closedbyclosingdigitaloutput1.Theparkinglotissurveilledbytwocamerasoninputs4and 7.Duringthealarm,thesemustberoutedtooutputs1and2ofa2-by-2sceneMyScenein GscView. Beforeandafterthealarm,all16GeViScope channelsshouldbedisplayedina4- by-4sceneMyStartScene inGscView. --- Page 50 --- Prerequisites 1.PleasesetuptheGeViScope SDKonyourdevelopment machineifyouhavenotdone ityet. 2.Configure GscViewasdescribed inthechapterRemotecontrolGscView byactionin theGeViScope SDKdocumentation. CheckthatfromGSCPLCSimulator youcan switchbetweenthescenes. 3.Configure aconnection toGeViScope asdescribed inConnection toGeViScope (optional). 4.YoushouldnowhaveaGscViewsetupwithtwoscenes:MyStartScene andMyScene thatcanberemotecontrolled. Configuring theAlarm 1.Configure thealarmasdescribed inConfiguring anAlarm. 2.Afterthat,themonitorgroupmustbemappedtoaGscViewScene.GeViSoftusesthe CrossSwitchWithAlarm actiontoroutethevideotothemonitorgroupinternally. There- foretheseactionsmustbemappedtoGSCViewer Controlactions(e.g.VCChange SceneByName).ThisisdoneinGeViSetbyaddinganewActionmapping: c)Thischangesthesceneintheviewer.Afterthat,channel4mustberoutedto viewer1101inthescene.Forthat,addanotheroutputactiontothesetbypressing the+button: d)AddtheViewerconnectliveactionwiththeGeviScope alias=GEVISCOPE ,the viewer=1101,thechannel=4,andCaption=ViewerConnectLive (1101,4) --- Page 51 --- a)AsInputactionselectCrossSwitchWithAlarm withVideoInput =4,VideoOutput = 1,andCaption=CrossSwitchWithAlarm (4,1) b)Tochangethesceneintheviewertherearedifferentpossibilities. Youcaneither callVCChangeSceneByName ordirectlyconnectalivestreamtoaviewernumber. ThisisdonebysendingaViewerConnectLive action.Here,channel4mustbe routedtoviewer1101inthescene.Forthat,addanoutputactiontothesetbypress- ingthe+button: c)AddtheViewerconnectliveactionwiththeGeviScope alias=GEVISCOPE ,the viewer=1101,thechannel=4,andCaption=ViewerConnectLive (1101,4) d)TheActionmappingsettingswindowshouldlooklikethis: --- Page 52 --- Switching Video1 e)NowrepeattheprocessfortheCrossSwitchWithAlarm actionforvideoinput7 andviewer1102. --- Page 53 --- f)Ifexecuted, themappings abovewillswitchthescenetoMySceneinGscView androutethevideochannelstotherespective viewer.Execution oftheCross- SwitchWithAlarm actionstakesplaceatthemomentoftriggeringthealarminGeV- iSoft. 3.Afterquittingthealarmthe4-by-4sceneMyStartScene mustbereloadedinGscView, according tothescenario.ThiscanbedoneasanOnquitactionoftheGeViSetalarm: a)IntheGeViSet AlarmsettingsoftheParkingLot alarm,addaVCchangesceneby nameactiontotheOnquitlist. --- Page 54 --- b)ChosetheactionfromGSC:VieweractionandsetGeviScope aliastoGEV- ISCOPE,viewerto1000,scenetoMyStartScene ,andCaptiontoVCChan - geSceneByName (1000,MyStartScene ). c)Sendthesetuptotheserver. 4.OpenGeViAPITestClientandGscViewtotestyournewconfiguration. Onstarting thealarmbyleftclickinginput1inGeViSet,thesceneshouldswitchtoMyScenein GscViewwithchannel4beingdisplayedinviewer1101andchannel7inviewer1102. Onquittingthealarmbyleftclickinginput3inGeViAPITestClient,thesceneshould switchbacktoMyStartScene . --- Page 55 --- SDKUsage Introduction Itisrecommended tobefamiliarwiththeGeViSoftsystem,thepossibilities ofmodernvideo surveillance systemsandvideomanagement systemsingeneral.Beforestartingpro- gramming yourcustomGeViSoftapplication, youshouldunderstand thebasicsofaction, alarm,andeventhandlinginGeViSoft, aswellastheprinciplesofclient-servernetworkcom- munication. Thefollowingsectionssupportyouwithsomesuggestions andhintsaboutusingtheSDK interfaces. General Hints YoucanalwaysmonitortheactionssentbytheGeViServer oryourapplication insidethe GeViAPITestClient.Furthermore, thisapplication allowsyoutosendactionsanddatabase queries.Itislocatedinthe%GEVISOFTSDKPATH% .  NOTICE Onadevelopment system itisrecommended tostartGeViServer withthestartserver.bat script orfromacommand prompt inconsole mode(geviserver.exe console ).Thisallowsyouto monitor theserver’s outputduringyourdevelopment.  WARNING Makesuretodeleteallobjects thatarecreated insideofDLLs.TheSDKoffersaDeleteObject () method fortheseobjects.  NOTICE --- Page 56 --- Callback functions whicharecalledoutoftheSDKDLLsarecalledfromthreads. Thesewere created insidetheDLLs.Variables andpointers thatarepassed asarguments ofthecallback maynotbeusedoutside thecallback context. Theyareonlyvalidfortheduration ofthecallback call.  NOTICE Structures thatareusedasarguments forSDKfunctions shouldalwaysbeinitialized byuseof thefunction memset ().Ifthestructure contains asizeorstructsize element, thenithastobe initialized withthesizeof()function. --- Page 57 --- Overview oftheSDK’sInterfaces forC++andDelphiusers  NOTICE Thefollowing paragraphs describe theSDKusagefromC++andDelphi. Foradescription ofthe .NetInterfaces seechapter C#and.Netspecifics GeViProcAPI TheSDKisbasedontwoDLLsandthecorresponding headers.TheGeViProcAPI.dll incon- nectionwiththeGSCActions.dll implements alltheSDK’sfunctionality. GSCActions.dll is usedtoallowtheinteroperability betweenGeViSoftandGeViScope. ItmakestheGeV- iScopeactionsavailabletoyourGeViSoftapplication. Thecorresponding headersandPas- calfilesallowyoutoaccessthefunctionsprovidedbytheseDLLsdirectly. GeViSoftisaclient/server architecture andbasedonacentraldatabasemanagedbythe GeViServer. ThisisreflectedinthefunctioncallsprovidedbytheSDK.Therearefourmajor functiontypesdeclaredinGeViProcAPI. Theycanbedistinguished bytheirprefixes: GeViAPI_ Database_ ThesedatabasefunctionsallowyoutointeractwithGeViSoftserverdirectly.Theyare theonesyounormallyusefordeveloping yourapplication. Example:GeViAPI_Database_ Connect()isusedtoconnectyourapplication tothe server. GeViAPI_ DeviceClient_ TheDeviceClient functionsareusedbytheGeViIOclientinternally. Theyareusuallynot ofinterestforSDKdevelopers. GeViAPI_ SetupClient_ --- Page 58 --- TheSetupClient functionsareusedbyGeViSettochangetheserversetup.Theyare usuallynotofinterestforSDKdevelopers. GeViAPI_ Thesearegeneralhelperfunctionsneededforcarryingoutstandardtasksinyourappli- cation. Example:GeViAPI_FreePointer ()to releasememoryallocatedbyyourobjectsinside theDLLthreads. GeViProcAPI providesflatfunctioncallsforcommunicating withaGeViServer. Togiveyoua moreconvenient andobjectorientedoptiontodevelopyourapplication, anotherabstraction layerhasbeenaddedtotheSDK.ThislayerhidestheflatfunctioncallstotheGeViProcAPI fromyou.Itsfunctionality canbefoundintheGeViAPIClient headersandC++files. Foracomprehensive description ofthesefunctions, pleaseconsulttheGeViSoftAPIDoc- umentation whichisdeliveredwiththeGeViSoftAPISDK. GeViAPIClient GeViAPIClient asanabstraction layerusestheflatfunctionsprovidedbyGeViProcAPI and encapsulates themintoaCGeViAPIClient class.Youcaninstantiate anobjectofthisclass anduseitsprovidedmethodstohandlethecommunication withtheGeViServer. Foracomprehensive description ofthesefunctions, pleaseconsulttheGeViSoftAPIDoc- umentation whichisdeliveredwiththeGeViSoftAPISDK. --- Page 59 --- Configuring yourIDEforGeViSoft Projects VisualStudio2008,C++ 1.)AddGeViSoft’s headerandcppfilestoyourproject. (YoucandothisbydragginganddroppingtheGeViScopeSDK\Include folderandtheGeV- iSoftSDK\Include folderfrom%GEVISOFTSDKPATH%\Examples\VS2008CPP toyour project.) 2.)AddtheSDK’sincludefilestoyourprojectbyadding $(GEVISOFTSDKPATH) \Examples\VS2008CPP\GeViScopeSDK\Include and $(GEVISOFTSDKPATH) \Examples\VS2008CPP\GeViSoftSDK\Include toyourConfiguration Properties ->C/C++->General–>Additional IncludeDirectories 3.)IntheConfiguration Properties ->C/C++->Preprocessor tabaddthePreprocessor Def- initionGEVI_GSC_INCLUDE 4.)Intheproject’sproperties TABConfiguration Properties ->Linker->Generaladd $(GEVISOFTSDKPATH) \Examples\VS2008CPP\GeViScopeSDK\lib and $(GEVISOFTSDKPATH) \Examples\VS2008CPP\GeViSoftSDK\lib totheAdditional LibraryDirectories ofyourproject 5.)Intheproject’sproperties TABConfiguration Properties ->Linker->Input->Additional Dependencies addGeViProcAPI.lib andGscActions.lib 6.)MakesurethatyouroutputfilecanfindthepathtoGeViProcAPI andGscActions DLLs. Itisrecommended tosetConfiguration Properties ->Linker->General->OutputFileto $(GEVISOFTSDKPATH) \$(ProjectName).exe orcopytheDLLsintotheapplication’s folder. 7.)SettheConfiguration Properties ->Debugging ->Command toyourexecutables name: --- Page 60 --- $(GEVISOFTSDKPATH) \$(TargetName) $(TargetExt)  NOTICE Pleasemakesurethatyouselectthecorrect configuration whensettingproperties. Bestprac- ticeistoadopttheGeViSoft settings toAllConfigurations  NOTICE PleasenoticethatVisualStudioreferstoenvironment variables intheform$(VAR) whereas Win- dowsusesthe%VAR% notation. Takethisintoaccount ifyouusetheGEVISOFTSDKPATH var- iable. VisualStudio2010,C++ Thefollowing guideissuitable forconsole projects orMFCprojects. Ifyouwish tobuildWindows Forms orC++/CLI applications moreconfigurations mightbe necessary. 1.)AddGeViSoft’s headerandcppfilestoyourproject. (YoucandothisbydragginganddroppingtheGeViScopeSDK\Include folderandtheGeV- iSoftSDK\Include folderfrom%GEVISOFTSDKPATH%\Examples\VS2010CPP toyour project. 2.)AddtheSDK’sincludefilestoyourprojectbyadding $(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViScopeSDK\Include and $(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViSoftSDK\Include toyourConfiguration Properties ->VC++Directories ->IncludeDirectories 3.)AddtheSDK’slibraryfilestoyourprojectbyadding $(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViScopeSDK\lib and --- Page 61 --- $(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViSoftSDK\lib toyourConfiguration Properties ->VC++Directories ->LibraryDirectories 4.)Intheproject’sproperties TABConfiguration Properties ->Linker->Input->Additional Dependencies addGeViProcAPI.lib andGscActions.lib 5.)MakesurethatyouroutputfilecanfindthepathtoGeViProcAPI andGscActions DLLs. Itisrecommended tosetConfiguration Properties ->Linker->General->OutputFileto $(GEVISOFTSDKPATH) \$(ProjectName).exe orcopytheDLLsintotheapplication’s folder. 6.)SettheConfiguration Properties ->Debugging ->Command toyourexecutables name: $(GEVISOFTSDKPATH) \$(TargetName) $(TargetExt) --- Page 62 --- Common Tasks Thischapterdescribes severalcommontasksyoumightneedtocarryoutduringyourdevel- opment. Thesearedescribed inpseudocodeandC++.Foradescription ofthe.NetAPIseechapter C#and.Netspecifics. Connecting toaGeViServer ThefirstexampleshowsyouhowtoconnecttoaGeViServer byusingtheflatAPIcallsfrom GeViProcAPI. Thesecondandrecommended methodshowsyouhowtoestablishthecon- nectionwiththehelpofaGeViAPIClient object. Connecting usingGeViProcAPI calls Pseudo code 1.Declareadatabasehandle 2.Encryptthepassword string 3.CreatearemotedatabaseobjectinsidetheDLL 4.ConnecttothedatabaseobjectcreatedinsidetheDLL C++, direct GeViProcAPI calls: //declare astringtoholdthepassword hash //(32byte+'\0') charencodedPassword [33]; --- Page 63 --- //declare adatabase handle GeViAPI_ Namespace::HGeViDatabase database; //encodethepassword GeViAPI_ EncodeString (encodedPassword, "masterkey", sizeof(encodedPassword)); //createaremotedatabase objectinsidethe DLL //toaccessaGeViSoft database GeViAPI_ Database_ Create(database, "localhost" , "127.0.0.1" ,"sysadmin" , encodedPassword, "",""); if(database) //database successfully created { //Connect functions result TConnectResult result; //Connect tothedatabase object. GeViAPI_ Database_ Connect(database, result, NULL/*yourcallback here!*/, NULL/*yourinstance here!*/); if(result ==connectOk) std::cout <<"Connection established!"; } Connecting usingGeViAPIClient Objects (recommended) Pseudo code 1.DeclareaGeViAPIClient wrapperobject 2.Declareanddefineaconnection callbackfunctiontomonitortheconnection progress(this functionwillbecalledfrominsidetheDLLandreturnaprogressstateinitsarguments) --- Page 64 --- 3.Encryptthecleartextpassword 4.CreateaninstanceoftheGeViAPIClient wrapperobject 5.Callthewrapper’s connectmethod 6.CheckIftheconnectmethodreturnedasuccess C++, GeViAPIClient calls: 1.Connection handling //wrapper aroundaGeViAPIclientobject GeViAPIClient* m_APIClient; //declare astringtoholdthepassword hash charencodedPassword [33]; GeViAPIClient::EncodePassword (encodedPassword, "mypassword" , sizeof(encodedPassword) ); //createannewinstance ofthewrapper m_APIClient =newGeViAPIClient ("MyGeViServer" , "127.0.0.1" ,"sysadmin" , encodedPassword, NULL,NULL); if(m_APIClient) { //connect totheserver–ConnectProgressCB isyourcallback TConnectResult ConnectResult = m_APIClient- >Connect (ConnectProgressCB, this); if(ConnectResult ==connectOk) { //Connection successfully established //Doyourworkhere. } --- Page 65 --- } 2.Callbacks //Callback function forconnect progress display bool__stdcall ConnectProgressCB (void*Instance, intPercentage, intPercent100) { if(Instance ==NULL) { return(true); } //Callthecallback methodofyourclass //object's instance CYourClass* yourClass =(CYourClass*) Instance; return( yourClass- >ConnectProgress ( Percentage, Percent100) ); } //Yourclass’s callback boolCYourClass::ConnectProgress (intpercentageLower, intpercentageUpper) { //Dos.th.,e.g.showaProgress Ctrl. return(true); } Connection Monitoring GeViSoftoffersmethodstomonitorifyourconnection isstillestablished. Itisadvisableto monitortheconnection fromyourapplication andtryareconnect ifitbreaksdown. YoucanusethesendPing()methodforconnection monitoring whichreturnstrueifthecon- nectionisstillestablished andfalseifnot. --- Page 66 --- BestpracticeistocyclicallycallsendPing()fromaseparatethreadandhandletherecon- nectionfrominsidethisthreadifnecessary. Monitoring connections isimplemented intheSDK’sexample CPP_Mon- itoredConnectionClient. Monitoring aConnection Pseudo code 1.Createaseparatethreadinsideyourapplication ifaconnection shouldbeestablished 2.Insidethisthead,DO: a.Sendapingtotheserver b.IFtheresultofthepingisNOTtrue:tryareconnect c.Sleepforagiventime(e.g.10s) 3.UNTILtheconnection shouldbeterminated C++Example //Prerequisite: //GeViAPIClient* m_APIClient //mustalready becreated andconnected. // //Runthismethodinsideaseparate Thread! intMonitorConnection () { constintreconnectionPeriod_ in_ms=10000; boolresult; while(true){ --- Page 67 --- result=m_APIClient- >SendPing (); if(result ==false) { //TODO:notifyyouruserhere. //Tryareconnect: m_APIClient- >Connect (YourConnectCallbackCB, this); } Sleep(reconnectionPeriod_ in_ms); } return0; } --- Page 68 --- Message Handling Afteryouhaveestablished yourconnection youarereadytoexchange messages withthe server. Message Representation Therearetwopossiblerepresentations ofmessages inGeViSoft. Theyareeitherstoredina binaryformorasanASCIIstring.TheAPIoffersmethodstoconvertbetweenthesetworep- resentations. ThesemethodsaredefinedintheMessageBase header,C++,andPascalfiles. Tableofconversion methodsbetweenmessagerepresentations. CGeV- iMessage::ReadASCIIMessageConverts anASCIIstringintoaCGeViMessage CGeV- iMessage::WriteASCIIMessageConverts aCGeViMessage intoanASCIIstring CGeViMessage::ReadBinMessage Converts abinaryrepresentation ofamessage intoaCGeV- iMessage CGeV- iMessage::WriteBinMessageConverts aCGeViMessage intoitsbinaryrepresentation --- Page 69 --- ActionMessages Creating ActionMessages Youcancreateanactionmessageintwoways.Oneisbycallingitspredefined actioncon- structordirectly.Theotherisbyconverting anASCIIorbinaryrepresentation intoanew actionobject.Thepredefined constructors arelocatedintheActionsheader,C++,andPas- calfiles. Actionscanbeconsidered aseitherbeingdirectcommands fromtheclienttotheGeViServer tocontrolitsperipheryorasnotifications whicharesentfromtheservertotheclienttoindi- catestatechangesoflogicalorphysicalcomponents. Incontrasttoactions,therearestate queriesanddatabasequeries.Thesearetreatedseparately inthechapters StateQueriesand Database Queries. 1.Example foradirectly created CustomAction message (con- structor fromActions.h/cpp) CGeViMessage* gevimessage =new CActCustomAction (123,"HelloGeViSoft!" ); 2.Example foraCustomAction message created fromastring intbytesRead; std::string buffer("CustomAction (123,\"Hello GeViSoft!\") "); CGeViMessage* gevimessage = CGeViMessage::ReadASCIIMessage (buffer.c_ str(), buffer.size (), bytesRead ); 3.Example fortheASCIIoutput ofabinary action message: //gevimessage isthebinarymessage --- Page 70 --- char*buffer; constintbufferlength =GEVI_MAXACTIONLENGTH; intnumBytesReceived; buffer=newchar[bufferlength]; gevimessage- >WriteASCIIMessage (buffer, bufferlength, numBytesReceived); std::cout <SendMessage (gevimessage); //Don’tforgettodeleteobjects youcreateinsidetheDLL gevimessage- >DeleteObject (); } Receiving ActionMessages ThisexampleshowsyouhowtoreceiveamessagefromGeViSoft. Asaprerequisite, aGeVi- APIClient objectmustalreadybecreatedandconnected totheserver.Furthermore, adata- basenotification callbackfunctionmustbedefined.Thiscallbackfunctionwillbecalledfrom insidetheGeViProcAPI DLLwhenever anotification fromtheserverisreceived. Pseudo code 1.Definethecallback 2.Definethecallback’s handlermethod 3.RegisteryourcallbackwiththeGeViAPIClient connection’s object. 4.Handlethereceivednotifications inyouhandlermethod. C++Example: 1.Define thecallback --- Page 72 --- void__stdcall GeViDatabaseNotificationCB (void*Instance, TServerNotification Notification, void*Params) { if(Instance ==NULL) return; //calling thecallback methodofyourClass object's instance. //Asanexample, CYourClass mightbeCMainWin foranMFCApplication CYourClass* yourClass =(CYourClass*) Instance; yourClass- >DatabaseNotification (Notification, Params); } 2.Define thecallback’s method voidDatabaseNotification (TServerNotification Notification, void*Params) { //Checkifwereceived amessage. Itmightalsobeanother //notification likeachangeofsetuporshutdown oftheserver if(Notification ==NFServer_ NewMessage) { //createthemessage ifpossible //(themessage isfreedagaininthemainthreadcontext) CGeViMessage* gevimessage; TMessageEntry* messageEntry = reinterpret_ cast (Params); intnoOfBytesRead =0; gevimessage =CGeViMessage::ReadBinMessage ( messageEntry- >Buffer, messageEntry- >Length, noOfBytesRead); if(gevimessage) { //Youreceived amessage! Nowyouneedtohandleit. //Thiscanbedonehere. } else --- Page 73 --- { //Message couldnotbecreated. Handletheerrorhere. } } else { //Ifwearehere,wereceived another typeofnotification } } 3.Register yourcallback withtheconnection object. m_APIClient =newGeViAPIClient ( ...); if(m_APIClient) { //connect totheserver TConnectResult ConnectResult = m_APIClient- >Connect (ConnectProgressCB, this); if(ConnectResult ==connectOk) { //Connection established! Nowregister yourcallback! m_APIClient- >SetCBNotification ( GeViDatabaseNotificationCB, this); } } Disconnecting fromaGeViServer Whendisconnecting fromtheserver,youshouldunregister yournotification callbackand deletetheGeViAPIClient object. C++Example: voidDisconnectFromServer () { --- Page 74 --- if(m_APIClient !=NULL) { //Unregister thenotification callback m_APIClient- >SetCBNotification (NULL,NULL); m_APIClient- >Disconnect (); deletem_APIClient; m_APIClient =NULL; } } --- Page 75 --- StateQueries StateQueriesaremessages sentfromtheclienttotheservertogetinformation aboutthe stateoflogicalandphysicalcomponents oftheGeViSoftsystemwellasvirtualressources. Anexampleofsuchinformation wouldbeanenumeration ofallthevideoinputsavailableata GeViServer. Creating StateQueries Youcancreateastatequerybycallingitspredefined constructor. Allthestatequeries’con- structorsarelocatedintheStateQueries header,C++,andPascalfiles. StatequeriescanthenbesentwiththeSendStateQuery ()methodoftheGeViAPIClient class.ThismethodreturnsaCStateAnswer objectwiththeGeViServer’s response. CStateAnswer* StateAnswer =m_APIClient- >SendStateQuery ( GetFirstVideoInputQuery, INFINITE); Thesecondparameter ofthemethodisthetimeoutforaserveranswerinmilliseconds. By sendingINFINITE,youcanpreventthecallfromtimingout. Creating, sending, andreceiving statequeries isimplemented intheSDK’sexam- pleDelphi/CPP_ SimpleClient. Enumeration ofallvideoinputs Pseudo code 1.Createastatequerytogetthefirstvideoinput(classCSQGetFirstVideoInput) 2.Sendthequerytotheserver --- Page 76 --- 3.If theanswerisavalidinputchannelthen 4.REPEAT a)Gettheactualchannel’s  information fromtheanswerandprocessitasneeded(e.g. printitout,storeittoalist) b)CreateastatequerytogetthenextvideoInput(classCSQGetNextVideoInput) c)Sendthequery 5.UNTILthereisnomorevideoinputleft C++Example: voidCMainWin::FillVideoInputsList () { if(m_APIClient ==NULL) return; //Enumerate allavailable videoinputswiththehelpofstatequeries. //Createanewstatequerythatwillreturnthefirstvideoinputchan- nel: CStateQuery* getFirstVideoInputQuery =newCSQGetFirstVideoInput ( true,//showonlyactivechannels true);//showonlyenabled channels if(getFirstVideoInputQuery) { //Sendthequerytotheserver CStateAnswer* stateAnswer =m_APIClient- >SendStateQuery ( getFirstVideoInputQuery, INFINITE); //Timeout //Don'tforgettofreethememoryinsidetheDLL... getFirstVideoInputQuery- >DeleteObject (); if(stateAnswer) { //Iterate through allavailable videoinputchannels --- Page 77 --- while(stateAnswer- >m_AnswerKind !=sak_Nothing) { //Getthechannels info CSAVideoInputInfo* videoInputInfo = reinterpret_ cast (stateAnswer); //createavideoinputdescriptor TVideoInputDescriptor* newVideoInput =new TVideoInputDescriptor (videoInputInfo- >m_GlobalID, videoInputInfo- >m_Name, videoInputInfo- >m_Description, videoInputInfo- >m_HasPTZHead, videoInputInfo- >m_HasVideoSensor, videoInputInfo- >m_HasContrastDetection, videoInputInfo- >m_HasSyncDetection); //Dosomething withthechannel information. Here: //Addthechannel information toa //CListBox lbVideoInputs intnewIndex =lbVideoInputs.AddString ( newVideoInput- >m_Name.c_str()); lbVideoInputs.SetItemDataPtr (newIndex, newVideoInput); //Createaquerytogetthenextinputchannel CStateQuery* getNextVideoInputQuery =new CSQGetNextVideoInput (true,true, videoInputInfo- >m_GlobalID); stateAnswer- >DeleteObject (); stateAnswer =NULL; if(getNextVideoInputQuery) { stateAnswer = m_APIClient- >SendStateQuery ( getNextVideoInputQuery, INFINITE); getNextVideoInputQuery- >DeleteObject (); if(!stateAnswer) break; } else//Nomorevideoinputchannel detected! break; } if(stateAnswer) --- Page 78 --- { stateAnswer- >DeleteObject (); stateAnswer =NULL; } } } } --- Page 79 --- Database Queries (optional) Database queriesallowyoutofetchdatasetsfromtheactionoralarmtableoftheGeViSoft activitydatabase. Alltheactionsthathavebeenreceivedandallthealarmeventsthat occurredarestoredinsidethedatabase. Tospecifyandnarrowdownyourqueryresults,sev- eralfilteroperations areavailableaswell. Togetfamiliar withthepossibilities ofGeViSoft’s database queries, andespe- ciallyitsfiltering options, please havealookattheGeViAPI TestClient’s “Data- baseViewer” and“Database Filter” tabs. Creating Database Queries Youcancreateadatabasequerybycallingitspredefined constructor. Allthedatabaseque- ries’constructors arelocatedintheDatabaseQueries header,C++,andPascalfiles. Database queriescanthenbesentwiththeSendDatabaseQuery ()methodoftheGeVi- APIClient class.ThismethodreturnsaCDataBaseAnswer objectwiththeGeViServer’s response. CDataBaseQuery* geviquery =newCDBQCreateActionQuery (0); CDataBaseAnswer* dbAnswer =m_APIClient- >SendDatabaseQuery (geviquery, INFI- NITE); Thesecondparameter ofthemethodisthetimeoutforaserveranswerinmilliseconds. By sendingINFINITE,youcanpreventthecallfromtimingout. Database QuerySession Handling Actionsendingandstatequeryingdidnotneedanyformofsessionhandling.Thisisdifferent fordatabasequerying.Usuallyyouwanttocollectseveralrecordsthatareconnected in --- Page 80 --- someform,e.g.applyingthesamefiltersettosubsequent queries. Tosignalthedatabase enginethatyourqueriesareassociated, youpassauniquequeryhandlewiththem.The queryhandleistheresultyoureceivefromaCDBQCreateActionQuery orCDBQCrea - teAlarmQuery .Thereforethesequeriesarethefirstyousendwheninteracting withthedata- base. C++Example forgetting aquery handle: //CreateanewActionQuery CDataBaseQuery* geviquery =newCDBQCreateActionQuery (0); //SendtheActionQuerytotheserver CDataBaseAnswer* dbanswer =m_APIClient- >SendDatabaseQuery (geviquery, INFI- NITE); geviquery- >DeleteObject (); if(dbanswer- >m_AnswerCode ==dbac_QueryHandle) { //Extract thequeryhandlefromtheanswer CDBAQueryHandle* handle=reinterpret_ cast (dbanswer); } --- Page 81 --- Iterating overDatabase Records Youcansendagroupofassociated databasequeriesafterhavingobtainedthequeryhandle. PleasenotethattheGeViSoftarchitecture alwaysreturnsonesingleanswerforeveryquery. Asaconsequence, youmightneedtoissueseveraldatabasequeriesconsecutively toget yourdesiredpiecesofinformation. Thiscanbeillustrated byanexampledatabasequery.Imagineyouwanttoretrievethetwo latestactionsinsidethedatabase: Example:  Retrieving ofthetwolatest actions inside thedata- base Pseudo code 1.CreateanewCDBQCreateActionQuery 2.SendthequerytoGeViServer andretrievethehandlefromtheanswer 3.CreateanewCDBQGetLast querywiththehandleastheargument 4.Sendthequeryandfetchthelatestactionasananswer 5.Extractthelatestaction’sprimarykeyfromtheanswer 6.CreateanewCDBQGetPrev querywiththehandleandthelatestaction’sprimarykeyas anargument 7.Sendthequeryandfetchthesecondlatestactionasananswer C++: --- Page 82 --- //Declare aqueryhandle CDBAQueryHandle* handle; __int64primaryKey; //CreateanewActionQuery CDataBaseQuery* geviquery =newCDBQCreateActionQuery (0); //SendtheActionQuerytotheserver CDataBaseAnswer* dbanswer =m_APIClient- >SendDatabaseQuery (geviquery, INFI- NITE); geviquery- >DeleteObject (); if(dbanswer- >m_AnswerCode ==dbac_QueryHandle) { //Extract thequeryhandefromtheanswer handle=reinterpret_ cast (dbanswer); } //Createadatabase queryforthelatestactionentry CDataBaseQuery* getEntry =newCDBQGetLast (handle- >m_Handle); //SendthequerytotheGeViServer dbanswer =m_APIClient- >SendDatabaseQuery (getEntry, INFINITE); getEntry- >DeleteObject (); //Checkifanactionentryisinthedatabase if(dbanswer- >m_AnswerCode ==dbac_ActionEntry) {  //Dos.th.withtheanswerhere... //Gettheprimary keywhichisusedto //address therecords internally primaryKey =reinterpret_ cast (dbanswer) ->m_PK; }//TODO: Adderrorhandling ifnoactionisinthedatabase //Create adatabase querytogetthesecondlatestactionentry getEntry =newCDBQGetPrev (handle- >m_Handle, primaryKey); //SendthequerytotheGeViServer dbanswer =m_APIClient- >SendDatabaseQuery (getEntry, INFINITE); getEntry- >DeleteObject (); --- Page 83 --- //Checkifanactionentryisinthedatabase if(dbanswer- >m_AnswerCode ==dbac_ActionEntry) {  //Dos.th.withtheanswerhere... }//TODO: Adderrorhandling ifnoactionisinthedatabase dbanswer- >DeleteObject (); --- Page 84 --- Filtering Database Queries GeViSoftsupportsvariousfiltersallowingyoutospecifyyourqueriesinamorepreciseway. Forexample,youcannarrowdownyoursearchtocertainactiontypesorsenders.Allthe availablefiltersaredeclaredintheDatabaseQueries headerfile. TosetthefilteringontheGeViServer, youhavetosendadatabasequeryforeveryfilterele- mentafteryouhaveobtainedthequeryhandle.Youcanmonitortheprocessing ofthequeries insidetheGeViAPITestClient. Hereisascreenshot ofadatabasequerysequence whichsetsafilterfortheactiontype nameCrossSwitch .Themessagesettingthefilterishighlighted. Thefilterhasbeendefined intheDatabase FiltertaboftheGeViAPITestClient.Afterwards, thefetchoperationwas startedfromtheDatabase Viewertab. Composing Filtered Queries Inthisparagraph youwilllearnhowtocomposesimplefiltersfirstandfinallyextenttheexam- plefromabove(IteratingoverDatabase Records)withafilterthatwillonlyreturn --- Page 85 --- CustomAction messages withcertainprimarykeys. Prerequisite foratestonyoursystemisthatthereareCrossSwitch ,CustomAction ,andsev- eralotheractiontypeentriesstoredinsideyourdatabase. Topopulateyourdatabasewith these,youcansendthemwiththeGeViAPITestClient.DoingafetchintheDatabase Vie- wer’staballowsyoutoverifythattheyarestoredcorrectlyafterwards. Example Filters ExampleforafilterthatwillonlyreturnCustomActions : CDataBaseFilter* myActionNameFilter = newCDBFTypeName (handle- >m_Handle, "CustomAction", dbc_LIKE); Aftercreatingyourfilters,youcansendthemwithGeViAPIClients SendDatabaseQuery method. CDataBaseAnswer* dbanswer = m_APIClient- >SendDatabaseQuery (myActionNameFilter, INFINITE); Makesuretoverifythattheanswercodeisdbac_DBOkandtocalltheDeleteObject method foryourfilteraftersendingit. Composing complex filters: Youcancomposeacomplexfilterbysendingasequence ofmultiplesinglefilterstothedata- base.Thesefilterswillthenbetreatedasaconjunction (logicalAND)byGeViServer. Hereisanexampleforacomplexfilterthatonlyreturnsactionswithprimarykeysbetween 500and600.Thisfilterhastobecomposed bysendingtwosimplefilterssequentially: CDataBaseFilter* myMinFilter = newCDBFPK_GrtEqu(handle- >m_Handle, 500); --- Page 86 --- CDataBaseFilter* myMaxFilter = newCDBFPK_LowEqu(handle- >m_Handle, 600); Complete Example ofaFiltered Database Query TheexampleIteratingoverDatabase RecordswillbeextendedtofilterforCustomActions with aprimarykeybetween500and600inthisparagraph. Toachievethis,thefiltermessages havetobesentdirectlyafterretrievingthedatabasehandle.Thefiltersarecreatedina methodcalledsetActionFilter .Thismessageisthencalledafterobtainingthedatabase handle. Examplefilteringmethod: voidsetActionFilter (CDBAQueryHandle* handle) { //Createavectorwithyourfiltermessages std::vector filterList; filterList.push_ back( newCDBFPK_GrtEqu(handle- >m_Handle, 500)); filterList.push_ back( newCDBFPK_LowEqu(handle- >m_Handle, 600)); filterList.push_ back( newCDBFTypeName (handle- >m_Handle, "CustomAction", dbc_LIKE)); //Sendthefilters for(vector::iterator it= filterList.begin ();it!=filterList.end (); it++) { CDataBaseAnswer* dbanswer =m_APIClient- >SendDatabaseQuery (*it,INFI- NITE); if(dbanswer- >m_AnswerCode !=dbac_DBOk) { //Doerrorhandling here! (*it)->DeleteObject (); return; } --- Page 87 --- (*it)->DeleteObject (); } } Nowyoucancallthatmethodinyourexamplefromabove: /* ... */ CDataBaseAnswer* dbanswer =m_APIClient- >SendDatabaseQuery ( geviquery, INFINITE); geviquery- >DeleteObject (); if(dbanswer- >m_AnswerCode ==dbac_QueryHandle) { //Extract thequeryhandefromtheanswer handle=reinterpret_ cast (dbanswer); //SendFilterhere setActionFilter (handle); } /* ... */ Asaresult,youshouldseethetwolatestCustomAction recordswithaprimarykeybetween 500and600.Ifyoudonotgetanyresults,youneedtoadoptthefilteringcriteriatomatchrec- ordsinyourdatabase. Database queries andfiltering isimplemented intheSDK’sexample Delphi/CPP_ SimpleDatabaseClient. --- Page 88 --- C#and.Netspecifics ThischapterdealswiththeGeViSoftSDKs.Netcapabilities andspecifics. Itdescribes the architecture ofthewrappersandthespecificsoftheusage. Architecture TheGeViSoftSDKisdeliveredwitha.Net-Wrapper,allowingyoutodesignapplications in C#orother.Netlanguages. TheGeutebrueck.GeViSoftSDKNET.Wrapper.dll encapsulates allthenativeGeViProcAPI.dll calls.Additionally, theGscActionsNet.dll fromtheGeV- iScopeSDK isneededtoallowforGeViScope interoperability. Thiswrapperencapsulates the GscActions.dll whichitselfusestheGscDBI.dll. --- Page 89 --- Diagram oftheGeViSoft .Netwrappers Configuring yourIDEforGeViSoft .NetProjects VisualStudio2008,C# 1.)Addthe.Netwrapperstoyourproject’sreferences. (Youcandothisbyright-clickingonReferences inyourSolution Explorer.Afterpressing Add Reference browsetoyour%GEVISOFTSDKPATH% andaddGeViProcAPINET_ 2_0.dll.Ifyou plantouseGeViScope ActionsalsoaddGscActionsNET_ 2_0.dll. --- Page 90 --- 2.)ChangetheplatformsettingstogenerateX86codeifitisnotalreadyset. IntheConfiguration ManagerselectPlatform ->New->X86andusethisplatformforthe DebugandReleaseconfigurations. --- Page 91 --- 3.)ChangetheOutputpathofyourproject. Theapplication needsthefollowingfilesinitspath:GeviProcAPI.dll ,GscDBI.dll ,GscAc- tions.dll ,GeViProcAPINET_ X_Y.dll,andGscActionsNET_ X_Y.dll.Allthesefilesarein your%GEVISOFTSDKPATH% ,sotheoutputpathtoc:\gevisoft\ . TochangetheOutputpath,eitherright-clickonyourprojectinSolution Explorerandpress Properties orchooseProject->ProjectName Properties fromthemenu.ThenselecttheBuild tabandsetyourOutputpath. --- Page 92 --- --- Page 93 --- 4.)Addtherequiredusingdirectives toyourproject’ssourcefiles. ForaprojectthatonlyusesGeViSoftactions,youneedatleast. GEUTEBRUECK.GeViSoftSDKNET.ActionsWrapper aswellas GEUTEBRUECK.GeViSoftSDKNET.ActionsWrapper.ActionDispatcher and,additionally foractionsfromeveryactionclassyouuse, GEUTEBRUECK.GeViSoftSDKNET.ActionsWrapper.YourActionClass IfyoualsowanttouseGeViScope actions,makesuretoinclude GEUTEBRUECK.GeViScope.Wrapper.Actions.ActionDispatcher and GEUTEBRUECK.GeViScope.Wrapper.Actions.YourActionClass Youcanfinddescriptions oftheactionsandtheirrespective actionclassesintheAPIdoc- umentation orbyinspecting theassemblies withtheObjectBrowser. VisualStudio2010,C# Configure yourprojectasdescribed inparagraph VisualStudio2008,C# Common TaskswithC# Thischapterdescribes severalcommontasksyoumightneedtocarryoutduringyourdevel- opment.Thetasksaredescribed inpseudocodeandC#. --- Page 94 --- Connecting toaGeViServer Thisparagraph showsyouwhattasksareneededforconnecting toaGeViServer. Connecting PseudoCode 1.Implement theconnectcallbackmethod 2.Createaninstanceofadatabaseconnection object 3.Callthecreate()methodofyourdatabaseconnection object 4.Addyourcallbackdelegatemethodtotheinvocation list 5.Registeryourcallbackmethod 6.Calltheconnectmethodofyourdatabaseconnection object C# //Thisistheconnect progress callback method. //ItiscalledfromwithinGeViSoft duringtheconnection progress voidmyConnectProgress (objectsender, GeViSoftConnectProgressEventArgs e) { Console.WriteLine ("Connecting... {0}of{1}",e.Progress, e.Effort); } //myDBisthedatabase objectthatencapsulates //allGeViSoft interaction. GeViDatabase myDB=newGeViDatabase (); //Settheservername,usernameandpassword ofyour //GeViSoft connection myDb.Create ("localhost", "sysadmin", "masterkey" ); --- Page 95 --- //Addyourcallback delegate totheinvocation list myDb.ConnectProgress +=newGeViSoftConnectProgressEventHandler ( myConnectProgress); //Register thecallback insideGeViSoft myDb.RegisterCallback (); //Nowyoucanconnect totheGeViSoft Server... myDB.Connect (); Astraightforward implementation forestablishing aconnection canbefoundinexampleCS_ ConsoleClient . Message Handling Afterhavingestablished theconnection, youarereadytoexchange messages andactions withtheserver. Creating andSending ofGeViSoft Messages Therearetwoapproaches thatcanbetakentocreateandsendGeViSoftmessages. Youcan eithercreateamessageinstancebycallingitsconstructor andthensendthisinstance,or youcandirectlysendastringrepresentation ofamessagewithoutinstantiating itfirst. Example 1–Creating aninstance ofamessage andsending itafter- wards //CreateaCrossSwitch Actionandswitch //input7tooutput1 GeViAct_ CrossSwitch myAction =newGeViAct_ CrossSwitch ( 7,1,GeViTSwitchMode.sm_ Normal); //Sendtheaction --- Page 96 --- myDB.SendMessage (myAction);  NOTICE Makesureyouhaveincludedyouraction’scorresponding actionclassnamespace inyour usingdirectives. SeeConfiguring yourIDEforGeViSoft.Net Projects->VS2008,C# Example 2–Directly sending amessage fromastring myDB.SendMessage ("CrossSwitch (7,1,0)"); Receiving ofGeViSoft Actions GeViSoftactiondispatching iseventbased.Internally, foreveryactionthatisreceived,an eventisfired.IfyouwanttoprocesscertainGeViSoftactionmessages insideyourappli- cation,youcanregisteraneventhandlerforthisparticularaction.Theeventhandleriscalled whenever anewactionofthattypeisreceived. IfyouwanttoprocessCrossSwitch actionsinyourapplication, youcanproceedasshownin thisexample. Pseudocode: 1.Implement amethodthatiscalledwhenever theeventisfired(actionreceived) 2.Registeryourmethodasaneventhandlerfortheparticularaction 3.RegisteryoureventhandlerinsidetheGeViSoftconnection object. C#: //Methodtobecalledonreceiving aCrossSwitch Action voidmyDB_ReceivedCrossSwitch (objectsender, GeViAct_ CrossSwitchEventArgs e) { --- Page 97 --- StringreceivedMessage ="CrossSwitch ("+ e.aVideoInput +","+ e.aVideoOutput +","+ e.aSwitchMode +")"; } //Eventhandler forCrossSwitch Actions myDB.ReceivedCrossSwitch +=new GeViAct_ CrossSwitchEventHandler (myDB_ReceivedCrossSwitch); //Don’tforgettoregister thehandler insidetheGeViSoft connection object myDB.RegisterCallback (); Receiving ofGeViSoft Notifications Besidesactions,GeViSoftalsosendsmessages regardingtheserverstatus,thedatabase notifications. Youcanreceivethesenotifications byregistering aGeV- iSoftDatabaseNotificationEventHandler. Theprocedure issimilartotheactionsubscription asdescribed above. Hereisanexample: voidmyDB_DatabaseNotification (objectsender, GeViSoftDatabaseNotificationEventArgs e) { switch(e.ServerNotificationType) { caseGeViServerNotification .NFServer_ Disconnected: //("Disconnected fromServer"); break; caseGeViServerNotification .NFServer_ GoingShutdown: //("Server isshutting down"); break; --- Page 98 --- caseGeViServerNotification .NFServer_ SetupModified: //("Server setuphasbeenmodified"); break; caseGeViServerNotification .NFServer_ NewMessage: //An“ordinary” actionhasbeenreceived. //Handlethisactioninaseparate Event- Handler //(likemyDB_ReceivedCrossSwitchAction) break; } } //Youregister thehandler asdescribed before myDB.DatabaseNotification +=new GeViSoftDatabaseNotificationEventHandler (myDB_DatabaseNotification); myDB.RegisterCallback ();  NOTICE Pleasenotethatthee.ServerNotificationType equalsGeViServerNotification .NFServer_ New- Message witheveryGeViSoft actionthatisreceived, regardless ifyoualready subscribed forit withanother eventhandler. Handling ofGeViScope Actions YoucanalsosendGeViScope actionsfromyourGeViSoftapplication. SendingGeViScope actionsisverysimilartosendingGeViSoftactions.Theonlydifference isthatyouneedto addtheGeViScope serveraliastotheSendMessage ()method’sparameters. Sending GeViScope Actions Example–sendingaGeViScope message: --- Page 99 --- Prerequisite: 1.Connection toGeViScope hasbeenconfigured withGeViSet 2.Theappropriate namespaces areincluded //Example forGeViScope namespace neededtohandle //aGeViScope CustomAction usingGEUTEBRUECK.GeViScope.Wrapper.Actions; usingGEUTEBRUECK.GeViScope.Wrapper.Actions.SystemActions; //CreatetheGeViScope action GscAct_CustomAction myGscAction =new GscAct_CustomAction (23,"HelloGeViScope!" ); //SendtheActiontothe“GeViScope_ Alias”server myDB.SendMessage ("GEVISCOPE_ ALIAS",myGscAction); Receiving GeViScope Actions Receiving GeViScope actionsisalittledifferentfromhandlingGeViSoftactions.Duetoarchi- tecturalconstraints, whenever aGeViSoftActionarrives,itisencapsulated intoaspecial GeViSoftaction.ThisactioniscalledGscAction. TheGscAction itselfisretrievedlikeanyotherGeViSoftactionbyimplementing amethod thatprocesses theGscAction andthatisaddedasaneventhandlerforreceivingtheGscAc- tion. ThismethodreceivestheoriginalGeViScope Actionembedded intoitsEventArgs whenever itiscalled. NormallyyouthenwouldhavetoidentifyandparsetheGeViScope actionandhandleitas neededbyhand.Foryourconvenience, theGeutebrueck SDKsprovideyouwithadispatcher thatcansimplifythattask: ThereisaDispatcher methodforGeViScope actionsthatworksverysimilartothedis- patchingmechanism usedbyGeViSoft. YoucansimplyaddeventhandlersfortheGeV- iScopeactionsyouareinterested inandprocesstheminthere. --- Page 100 --- Example–Receiving andDispatching GeViScope ActionsinsideGeViSoft: PseudoCode: 1.CreateaninstanceoftheGscActionDispatcher classthatwilldispatchtheGeV- iScopeactionstoyourhandlers 2.CreateaneventhandlerthatreceivestheGeViSoftGscAction. Insidethisevent handler,callthedispatchmethodofyourGscActionDispatcher instanceforevery receivedGscAction. 3.RegistertheGeViSoftGscAction eventhandlerwithyourGeViSoftdatabasecon- nectionobject. 4.CreateaneventhandlermethodforanyGeViScope actionyouwanttoprocess 5.RegisteryourGeViScope actionseventhandleratthedispatcher. C#: //Createaninstance oftheGscActionDispatcher class GscActionDispatcher myGscDispatcher =newGscActionDispatcher (); //GscAction eventhandler thatdispatches theGscAction voidmyDB_ReceivedGscAction (objectsender, GeViAct_ GscActionEventArgs e) { myGscDispatcher.Dispatch (e.m_GscAction); } //Addthehandler forGscAction (thisiscalledforanynewlyreceived GeV- iScopeaction) myDB.ReceivedGscAction +=new GeViAct_ GscActionEventHandler (myDB_ReceivedGscAction); //Don'tforgettoregister thecallbacks! myDB.RegisterCallback (); //Eventhandler methodfortheGeViScope Action --- Page 101 --- voidmyGscDispatcher_ OnCustomAction (objectsender, GscAct_Cus- tomActionEventArgs e) { Console.WriteLine "Received GEVISCOPE CustomAction ("+e.aInt+"," +e.aString +")"); } //Register theGeViScope CustomAction eventhandler withthedispatcher myGscDispatcher.OnCustomAction +=new GscAct_CustomActionEventHandler (myGscDispatcher_ OnCustomAction);  NOTICE Youcanfindacomplete example application thatsendsandreceives GeViScope actions inCS_ SimpleGscActionClient. StateQueries inC# Thisparagraph describes howyoucansendandreceiveStateQueriesfromwithinC#.Foran introduction toStateQueriesingeneralseechapterSDK-Usage->StateQueries. Creating andSending StateQueries YoucancreateStateQuerieswiththeirrespective constructors andsendthemafterwards by callingtheSendQuery ()methodofyourdatabaseconnection instance.TheSendQuery () methodreturnstheGeViSoftStateAnswerviaanoutparameter. //myAnswer isfilledbytheSendQuery ()method //withtheStateAnswer. GeViMessage myAnswer; //Thisisyourquery GeViMessage myQuery =newGeViSQ_GetFirstVideoInput (true,true); --- Page 102 --- //Sendthequery myDB.SendQuery (myQuery, outmyAnswer); if(myAnswer isGeViSA_VideoInputInfo ) { //Dosomething withmyanswerhere... } SettingtheStateQueryTimeout ThemethodSendQuery ()blocksuntilthedatabaseanswerisretrievedfromtheGeViServer. Iftheserverdoesnotanswer,thisleadstoadeadlock. Amaximum timeouttimerforthe SendQuery existstopreventwaitingendlesslyforadatabaseanswer.Bydefault,thetimeout issetto3000ms.YoucanchangethistimeoutgloballybycallingtheSetQueryTimeoutInMs ()methodofyourdatabaseconnection instance. Example–SettingtheSendQuery timeouttoonesecond: myDB.SetQueryTimeoutInMs (1000); Enumeration ofallvideoinputs Pseudocode 1.Createastatequerytogetthefirstvideoinput(classGeViSQ_GetFirstVideoInput) 2.Sendthequerytotheserver 3.Iftheanswerisavalidinputchannelthen 4.REPEAT a)Gettheactualchannel’sinformation fromtheanswerandprocessitasneeded (e.g.printitout,storeittoalist) b)CreateastatequerytogetthenextvideoInput(classGeViSQ_ --- Page 103 --- GetNextVideoInput) c)Sendthequery 5.UNTILthereisnomorevideoinputleft C#Example: private ListgetVideoInputsList () { ListmyVideoInputs = newList(0); if(myDB!=null) { GeViMessage myAnswer; myDB.SendQuery (newGeViSQ_GetFirstVideoInput (true,true), outmyAnswer); while(myAnswer isGeViSA_VideoInputInfo ) { inttempID=(myAnswer asGeViSA_VideoInputInfo ).sG- lobalID; myVideoInputs.Add (myAnswer asGeViSA_VideoInputInfo ); myDB.SendQuery ( newGeViSQ_GetNextVideoInput (true,true,tem- pID), outmyAnswer); } } returnmyVideoInputs; }  NOTICE Youcanfindacomplete example application thatsendsStateQueries andreceives StateActions inCS_SimpleClient. Thisexample showsyouhowtoenumerate videoin-andoutputs aswellas digitalIO. --- Page 104 --- Supported Development Platforms TheSDKisdesignedforandtestedtoworkwiththefollowingdevelopment environments: lMicrosoftVisualStudio2008,C++ lMicrosoftVisualStudio2010,C++ lMicrosoftVisualStudio2008,C# lMicrosoftVisualStudio2010,C# lEmbarcadero RADStudioXE,Delphi --- Page 105 --- Examples TheSDKisshippedwithvariousexamples showingyouhowtoimplement commontasks. Theexamples aregroupedbyfunctionality andplatform. ByFunctionality Connecting/disconnecting toGeViServer lCPP_SimpleActionClient (VS2008/VS2010, C++) lCPP_SimpleClient (VS2008/VS2010, C++) lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCPP_MonitoredConnectionClient (VS2008/VS2010, C++) lCPP_ConsoleClient (VS2008/VS2010, C++) lCS_SimpleActionClient (VS2008/VS2010, C#) lCS_SimpleClient (VS2008/VS2010, C#) lCS_SimpleDatabaseClient (VS2008/VS2010, C#) lCS_SimpleGscActionClient (VS2008/VS2010, C#) lDelphi_SimpleActionClient (RADStudioXE) lDelphi_SimpleClient (RADStudioXE) lDelphi_SimpleDatabaseClient (RADStudioXE) lDelphi_ConsoleClient (RADStudioXE) Monitoring aGeViSoft connection lCPP_MonitoredConnectionClient (VS2008/VS2010, C++) Automatically reconnecting aGeViSoft connection onloss lCPP_MonitoredConnectionClient (VS2008/VS2010, C++) Sending/receiving ofGeViSoft actions/messages lCPP_SimpleActionClient (VS2008/VS2010, C++) lCPP_MonitoredConnectionClient (VS2008/VS2010, C++) lCPP_SimpleClient (VS2008/VS2010, C++) --- Page 106 --- lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCPP_ConsoleClient (VS2008/VS2010, C++) lCS_SimpleActionClient (VS2008/VS2010, C#) lCS_SimpleClient (VS2008/VS2010, C#) lCS_SimpleDatabaseClient (VS2008/VS2010, C#) lCS_ConsoleClient (VS2008/VS2010, C#) lDelphi_SimpleActionClient (RADStudioXE) lDelphi_SimpleClient (RADStudioXE) lDelphi_SimpleDatabaseClient (RADStudioXE) lDelphi_ConsoleClient (RADStudioXE) Sending/receiving ofGeViScope actions/messages lCS_SimpleGscActionClient (VS2008/VS2010, C#) Receiving anddispatching ofservernotifications lCPP_SimpleActionClient (VS2008/VS2010, C++) lCPP_MonitoredConnectionClient (VS2008/VS2010, C++) lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCPP_ConsoleClient (VS2008/VS2010, C++) lCS_SimpleActionClient (VS2008/VS2010, C#) lCS_SimpleClient (VS2008/VS2010, C#) lCS_SimpleDatabaseClient (VS2008/VS2010, C#) lCS_SimpleGscActionClient (VS2008/VS2010, C#) lCS_ConsoleClient (VS2008/VS2010, C#) lDelphi_SimpleActionClient (RADStudioXE) lDelphi_SimpleClient (RADStudioXE) Converting between ASCIIandbinaryrepresentation ofmessages lCPP_SimpleActionClient (VS2008/VS2010, C++) lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCPP_ConsoleClient (VS2008/VS2010, C++) lDelphi_SimpleActionClient (RADStudioXE) lDelphi_SimpleDatabaseClient (RADStudioXE) lDelphi_ConsoleClient (RADStudioXE) --- Page 107 --- Sending/receiving statequeries andanswers lCPP_SimpleClient (VS2008/VS2010, C++) lCS_SimpleGscActionClient (VS2008/VS2010, C#) lDelphi_SimpleClient (RADStudioXE) Enumeration ofvideoinputandoutputchannels lCPP_SimpleClient (VS2008/VS2010, C++) lCS_SimpleClient (VS2008/VS2010, C#) lDelphi_SimpleClient (RADStudioXE) Enumeration ofdigitalIOcontacts lCPP_SimpleClient (VS2008/VS2010, C++) lCS_SimpleClient (VS2008/VS2010, C#) lDelphi_SimpleClient (RADStudioXE) Sending database actionqueries lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCS_SimpleDatabaseClient (VS2008/VS2010, C#) lDelphi_SimpleDatabaseClient (RADStudioXE) Sending database alarmqueries lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCS_SimpleDatabaseClient (VS2008/VS2010, C#) lDelphi_SimpleDatabaseClient (RADStudioXE) Navigating through database entries lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lCS_SimpleDatabaseClient (VS2008/VS2010, C#) lDelphi_SimpleDatabaseClient (RADStudioXE) Converting database answers frombinarytoASCIIrepresentation lCPP_SimpleDatabaseClient (VS2008/VS2010, C++) lDelphi_SimpleDatabaseClient (RADStudioXE) --- Page 108 --- Building GeViSoft messages fromuserinput lCPP_ConsoleClient (VS2008/VS2010, C++) lCS_ConsoleClient (VS2008/VS2010, C#) lDelphi_ConsoleClient (RADStudioXE) --- Page 109 --- ByPlatform Microsoft VisualStudio2008/2010, C++,MFC CPP_SimpleActionClient lConnecting/disconnecting toGeViServer lSending/receiving ofactions lReceiving anddispatching ofservernotifications lConverting betweenASCIIandbinaryrepresentation ofmessages. CPP_MonitoredConnectionClient lConnecting/disconnecting toGeViServer lSending/receiving ofactions lReceiving anddispatching ofservernotifications lConverting betweenASCIIandbinaryrepresentation ofmessages lMonitoring aGeViSoftconnection lAutomatically reconnecting aGeViSoftconnection onloss CPP_SimpleClient lConnecting/disconnecting toGeViServer lSending/receiving statequeriesandanswers lSending/receiving ofactions lEnumeration ofvideoinputandoutputchannels lEnumeration ofdigitalIOcontacts lReceiving anddispatching ofservernotifications CPP_SimpleDatabaseClient lConnecting/disconnecting toGeViServer lSendingdatabaseactionqueries lSendingdatabasealarmqueries lNavigating throughdatabaseentries lReceiving databaseentries lConverting databaseanswersfrombinarytoASCIIrepresentation --- Page 110 --- Microsoft VisualStudio2008/2010, C++,Console CPP_ConsoleClient lConnecting/disconnecting toGeViServer lBuildingGeViSoftmessages fromuserinput lReceiving anddisplaying messages lConverting betweenASCIIandbinaryrepresentation ofmessages Microsoft VisualStudio2008/2010, C#WinForms CS_SimpleActionClient lConnecting/disconnecting toGeViServer lSending/receiving ofactions lReceiving anddispatching ofservernotifications CS_SimpleClient lConnecting/disconnecting toGeViServer lSending/receiving statequeriesandanswers lSending/receiving ofactions lEnumeration ofvideoinputandoutputchannels lEnumeration ofdigitalIOcontacts lReceiving anddispatching ofservernotifications CS_SimpleDatabaseClient lConnecting/disconnecting toGeViServer lSendingdatabaseactionqueries lSendingdatabasealarmqueries lNavigating throughdatabaseentries lReceiving databaseentries CS_SimpleGscActionClient lConnecting/disconnecting toGeViServer lCreating/Dispatching GeViScope Actions --- Page 111 --- lCreatingGeViScope ActionEventHandlers lAdding/Removing EventHandlersonruntime Microsoft VisualStudio2008/2010, C#,Console CS_ConsoleClient lConnecting/disconnecting toGeViServer lBuildingGeViSoftmessages fromuserinput lReceiving anddisplaying messages lComposing GeViSoftactionsfromstrings Embarcadero RADStudioXE,Delphi,VCL Delphi_SimpleActionClient lConnecting/disconnecting toGeViServer lSending/receiving ofactions lReceiving anddispatching ofservernotifications lConverting betweenASCIIandbinaryrepresentation ofmessages. Delphi_SimpleClient lConnecting/disconnecting toGeViServer lSending/receiving statequeriesandanswers lSending/receiving ofactions lEnumeration ofvideoinputandoutputchannels lEnumeration ofdigitalIOcontacts lUsageofvideoinputandoutputdescriptors lUsageofdigitalcontactinputandoutputdescriptors lReceiving anddispatching ofservernotifications Delphi_SimpleDatabaseClient lConnecting/disconnecting toGeViServer lSendingdatabaseactionqueries lSendingdatabasealarmqueries --- Page 112 --- lNavigating throughdatabaseentries lReceiving databaseentries lConverting databaseanswersfrombinarytoASCIIrepresentation Embarcadero RADStudioXE,Delphi,Console Delphi_ConsoleClient lConnecting/disconnecting toGeViServer lBuildingGeViSoftmessages fromuserinput lReceiving anddisplaying messages lConverting betweenASCIIandbinaryrepresentation ofmessages --- Page 113 ---