================================================================================
GeViScope_SDK.pdf - Pages 21 to 30
================================================================================


────────────────────────────────────────────────────────────────────────────────
Page 21
────────────────────────────────────────────────────────────────────────────────

Backgroundinformation
InGeViScopesystemsactionsareusedtocommunicatebetweentheGeViScopeserver
andanyclientapplication.Allavailableactionscanbedividedintothreegroups:
Notificationactions(forexample“UserLogin”),commandactions(forexample“Viewercon-
nectlive”)andlogicalactions(theseactionsarenotdirectlycreatedbytheGeViScope
serverandtheydon’tdirectlyresultinanyreactionintheGeViScopeserver,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.Eventsdon’thaveglobal
numbers.Heretheeventnameshouldbeusedinstead.
Handlingconnectioncollapses
ThecallbackOpenPushCallback()ofthePLCobjectenablestolistentodifferentkindsof
notificationsfromthePLCobject.Oneisthe“plcnPushCallbackLost”notification.Itisfired
ifaconnectionisinternallydetectedascollapsed.Asareactiononthiseventyoushould
destroyorfreeallobjectsthatwerecreatedinsidetheDLLsandstartaphaseofreconnect
tries.Thereconnecttriesshouldstartevery30secondsforexample.Additionallyyour
applicationcanlistentoUDPbroadcaststhataresentbytheGeViScopeserver.Afteryour
applicationreceivedthisbroadcastitcandirectlytrytoreconnecttotheserver.Pleasebe
awareofthefact,thatbroadcastsonlyworkinLAN–routersnormallyblockbroadcasts.
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.