geutebruck/GeViScope_SDK_Docs/GeViScope_SDK_Part01_Pages_1-20.txt

================================================================================
GeViScope SDK Documentation - Pages 1 to 20
================================================================================


============================================================
PAGE 1
============================================================

GeViScope SDK
D ok u m e n t at i on | D oc u m e n t at i on | D oc u m e n t at i on | D oc u m e n t a t i ón
Version 04.2013


============================================================
PAGE 2
============================================================

GeViScope Software Development Kit (SDK)
Introduction
The GeViScope SDK consists of a collection of free software interfaces for the
GEUTEBRÜCK DVRs GeViScope and RePorter. It can be used to integrate these devices
in custom applications and although for linking not yet supported peripherals.
The interfaces are based on native Win32 DLLs. So they can be used with various devel-
opment platforms of the Windows OS.
To support the .NET technology the SDK examples contain wrapper classes based on
C++/CLI. These wrapper examples can be freely used, modified and extended by the SDK
users. The C# examples included in the SDK demonstrate, how the wrappers can be used
by custom applications.
Contents
Files and directory structure of the SDK
Setting up a virtual test environment
Remote control GSCView
Overview of the interfaces in the SDK
Supported development platforms
Guidelines and hints
GSCView data filter plugins
Examples overview
Action documentation
Documentation-History Version 3.9 / PME
Files and directory structure of the SDK
During the installation of the SDK the environment variable %GSCSDKPATH% which
points to the root directory of the SDK is set. This reference path is used in all examples.
%GSCSDKPATH%\Bin
Contains all dynamic link libraries and is the target directory for the
compiled examples
%GSCSDKPATH%\include Contains all Delphi import units, C++ header and cppfiles
%GSCSDKPATH%\lib
Contains all lib files for Borland C++ Builder and Microsoft Visual C++
The matching interface units between C++ and Delphi have the same name but compiler
specific file extensions.


============================================================
PAGE 3
============================================================

Setting up a virtual test environment
Introduction
All required components for setting up a virtual GeViScope device are included in the SDK.
So an independent development of custom solutions can be achieved without any special
hardware required.
After starting up the GeViScopeserver (part of the virtual GeViScope device) GeViScope
software can be used with full function for two hours. After that time the functionality is lim-
ited. After stop and restart of the server full functionality is offered for two hours again.
Step by step
After the successful installation of the SDK all necessary files exist in the installation folder
(normally “%HOMEPATH%\My Documents\GeViScopeSDK”).
Ste p 1: As s i gn l oc al pol i c y “Loc k pa ge s i n m e m or y ”
To run GeViScopeserver on your local machine, a local policy needs to be assigned to the
user account under which GeViScope server should work.
Please open the “Local Security Policy” dialog in the control panel – Administrative Tools.
With “Security Settings / Local Policies / User Rights Assignment” the privilege “Lock
pages in memory” has to be assigned to the user account under which GeViScope server
should run.
The user has to be a member of the local Administrators group.
The user has to logout and login again to let the setting take effect.


============================================================
PAGE 4
============================================================

Ste p 2: unpac k the te s t f i l e s
Unpack the file “\BIN\GeViScope.Database.zip” to the root directory of your system drive
(normally “C:”). Afterwards the file “C:\GeViScope.Database” should exist. Please note that
the file is not seen in the windows explorer if hidden files and folders are masked out.
Unpack the file “\BIN\DatabaseBackup.zip” to the sub folder “\BIN” of the GeViScope SDK
base directory (normally “%HOMEPATH%\My Documents\GeViScopeSDK”). After that
the file “\BIN\DatabaseBackup.gpf“, which contains a test backup file in GBF format
(“GEUTEBRÜCK Backup File”) should exist.
Ste p 3: s tar t the Ge Vi Sc ope s e r v e r
Start the server by double clicking on file “\BIN\GSCServer.exe“. Now a console application
should start.
Ste p 4: i m por t the te s t s e tup
Start the GSCSetupsoftware (file “\BIN\GSCSetup.exe“ ) and establish a connection to the
local server. Use the following login information:
Username = sysadmin
Password = masterkey
Send the setup once to the server by using the menu entry “Send setup to server“.
The test setup “\BIN\GeViScopeSDKSetup.set“ can be imported into the server with the help
of the menu entry “Import setup from file“. Afterwards it should be send to the server once
again.
Ste p 5: v i e w l i v e v i de o and ba c k up v i de o i n GSCVi e w
Now the correct setup of the test environment should be tested. For that purpose the
GSCViewsoftware (file “\BIN\GSCView.exe”) can be started and again a connection to the
local server should be established. After a successful connection media channels are avail-
able and can be viewed. Simply drag the media channels on the viewers of GSCView.


============================================================
PAGE 5
============================================================

The menu entry “Open backup file…” allows opening the test backup file “\BIN\Data-
baseBackup.gpf“, which also contains media channels that can be displayed. Please check
the correct function of the backup by play back the video material.
Ste p 6: U s e of tool “\BI N \ GSCPLCSi m ul a tor . e x e ”
The software “\BIN\ GSCPLCSimulator.exe” serves as a monitoring tool for all messages
(actions) and events that are transported inside the complete system. Furthermore actions
can be triggered and events can be started and stopped.
After building up a connection to the local server all action traffic is displayed in a list.
This tool is extremely helpful for testing of custom applications based on the SDK and for
analyzing message flow in the complete system.
Background information
To provide a test environment with full functionality the GeViScope media plugin“MCS”
(Media Channel Simulator) is used. It simulates real video media channels by channeling
test pictures into the GeViScopeserver. 16 media channels can be used as live channels or
can be recorded into the test database. Furthermore the channels create messages
(actions) that allow using them as base for developing video analysis software.
The media plugin“MCS” is part of the SDK including source code (development platform Bor-
land C++ Builder 6) and documentation (please see topic “Examples overview” for more
information).
Overview of the interfaces in the SDK
Introduction
This document gives a short overview of the different interfaces that belong to the SDK.
Please note, that all interfaces include class declarations to access the exported functions
of the dynamic link libraries. To use them in C++, the matching cpp files and the lib files cor-
responding to the DLLs have to be added to the custom project.


============================================================
PAGE 6
============================================================

Building blocks of functionality
DBI
l Low level server and database interface
l Connection handling, GBF access, raw database access (no video display!), media
export functionality, backup functions, access to raw live media (no video display!),
setup data access
l Supports basic functionality for building blocks “PLC” and “MediaPlayer”
l Main binary file: GSCDBI.DLL
l Main include files (C++): GSCDBI.h, GSCDBI.cpp
l Main include files (Pascal): GSCDBI.pas
PLC
l Complex notification, action and event processing
l Listen to, dispatch, create and send actions
l Listen to events and system notifications
l Allows controlling and monitoring the system
l Main binary file: GSCActions.DLL
l Main include files (C++): GSCActions.h
l Main include files (Pascal): GSCActions.pas
TACI
l Telnet Action Command Interface
l Simple ASCII-Format communication based on Telnet
l Allows controlling and monitoring the system
l Received actions need to be parsed


============================================================
PAGE 7
============================================================

l To use that interface, the media plugin “GSCTelnetActionCommand” needs to be
installed
Me di aPl ay e r
l High level server and database interface including media presentation
l Display video, play audio (live and backup)
l Integrated export functionality (GBF, MPEG, Video-DVD, Single picture)
l Search media data by time or corresponding to event data
l Main binary file: GSCMediaPlayer.DLL
l Main include files (C++): GSCMediaPlayer.h, GSCMediaPlayer.cpp
l Main include files (Pascal): GSCMediaPlayer.pas
Of f s c r e e nVi e w e r
l Part of building block “MediaPlayer”
l Same functionality as MediaPlayer, but: no rendering, only decompressing
l Class TGSCOffscreenViewer can be used analogous to TGSCViewer
Me di a pl ugi n (Ge Vi Sc ope s e r v e r pl ugi ns )
l GeViScope server plugins allow integrating custom peripherals in GeViScope sys-
tems
l Channeling of video and/or audio media into the server
l Including full access to PLC
l Plugins run as In-Process-DLLs in GeViScope server software
GSCVi e w data f i l te r pl ugi n
l GSCView plugins allow integrating custom data filter frontends in GSCView soft-
ware
l Plugins run as In-Process-DLLs in GSCView software
GSCVi e w data pr e s e ntati on pl ugi n
l GSCView plugins allow customized presentation of event data in GSCView soft-
ware, especially of event data presented in viewed pictures
l Plugins run as In-Process-DLLs in GSCView software
Remote control GSCView by actions
Introduction
The simplest approach to view and browse live and recorded video of one or more GeViS-
copes is to remote control GSCView out of custom solutions.
GSCView can be used in a special mode so that it can be controlled by actions that are sent
from a GeViScope server. The actions can be channeled into the system using the SDK
(GSCDBI.DLL and GSCActions.DLL) in custom applications. As an alternative the actions
can be sent to the TACI interface of the GeViScope server. The TACI interface is a media
plugin of the GeViScope server, which can receive actions as ASCII text commands similar
to a TELNET communication. The TACI plugin has to be licensed.


============================================================
PAGE 8
============================================================

Step by step
The following step by step instructions show how to configure a simple system to demon-
strate remote controlling GSCView. The virtual test environment included in the SDK should
be successfully installed and set up before following these instructions (see topic Setting up
a virtual test environment).
Ste p 1: s tar t the Ge Vi Sc ope s e r v e r
Start the server by double clicking on file “\BIN\GSCServer.exe“. Now a console application
should start.


============================================================
PAGE 9
============================================================

Ste p 2: s tar t GSCVi e w
Start the GSCView software (file “\BIN\GSCView.exe”).
Ste p 3: s tar t the pr of i l e m anage r
The menu entry “Options – Profile manager…” starts the internal profile manager of
GSCView. The profil manager allows configuring all GSCView settings.


============================================================
PAGE 10
============================================================

Ste p 4: de c l ar e l oc al c onne c ti on as “c onne c t autom a ti c a l l y ”
By selecting “Connections” in the section “Resources” the local connection can be declared
as a connection that is automatically built up after starting GSCView. Additional the option
“Reconnect automatically” should be activated.


============================================================
PAGE 11
============================================================

If the connection is open in GSCView or GSCSetup, the settings of the connection cannot
be changed. Close all local connections at first to be able to change the connection settings.
Ste p 5: c onf i gur e GSCVi e w to be abl e to r e m ote c ontr ol i t by
a c ti ons
The entry “Options profile” in the section “Profiles” shows a tab control with a lot of different
GSCView settings. To be able to remote control GSCView the option “Remote control” on
the “Actions” tab has to be set.


============================================================
PAGE 12
============================================================

The “Viewer client number” should be set to a arbitrary global number that is unique in the
whole system. This global “Viewer client number” identifies this special instance of
GSCView in the whole network. The number is used in different actions to remote control
GSCView.
By contrast the “global number” of a viewer in a custom scene identifies a special viewer in
a user defined scene. Details about user defined scenes will be topic of the next step.
Ste p 6: us e r de f i ne d s c e ne s
To define user defined scenes in GSCView the entry “Scenes” in section “Resources”
should be selected. By right clicking on one of the predefined scenes new user defined
scenes can be created. For this step by step example two new scenes with the names
“MyStartScene” and “MyScene” have to be added. With the button “Edit scene” the global
numbers of the viewers of the scene and the video channels that should be displayed can be
set.
The “MyStartScene” should be based on the “Matrix 4x4”. The viewers should have the
global numbers 1001 to 1016. Each viewer should display live pictures of a video channel of
the local connection. The video channels can be set via drag & drop while editing the scene.


============================================================
PAGE 13
============================================================

The “MyScene” should be based on the “Matrix 2x2” and the viewers should have the global
numbers 1101 to 1104. The viewers should not automatically display any video channel.
They will be used by special actions to display video channels.


============================================================
PAGE 14
============================================================

Ste p 7: m odi f y the appe ar anc e of GSCVi e w
The appearance of GSCView can be controlled by different settings in the entry “Options pro-
file” of the section “Profiles”. For this test scenario, GSCView should appear as a stupid
video wall without any user controls directly visible in the GSCView application window. To
achieve this, the following options on the “Application” tab have to be set:


============================================================
PAGE 15
============================================================

Please keep in mind, that if the option “Sensitive area enabled” is not set and if all “Hide…”
options are set, the main menu of GSCView only can be accessed by pressing F10!
Ste p 8: s av e al l s e tti ngs
All settings should be saved by selecting the menu entry “File – Save”.
Ste p 9: te s t the s y s te m w i th GSCPLCSi m ul a tor
After restarting GSCView it should appear in full mode with 16 viewers displaying live pic-
tures of the video channels of the local connection.


============================================================
PAGE 16
============================================================

Now start the software “\BIN\ GSCPLCSimulator.exe” to test the system. The
GSCPLCSimulator serves as a monitoring tool for all messages (actions) and events that
are transported inside the complete system. Furthermore actions can be triggered and
events can be started and stopped.
After its start the connection to the local server should be build up automatically and all
action traffic is displayed in a list.


============================================================
PAGE 17
============================================================

With the button “Dialog” an action can be selected and with the button “Send” this action can
be send to the GeViScope server. For testing the system first select the action “VC change
scene by name” in the category “Viewer actions” to display “MyScene” on the GSCView
with the global “Viewer client number” 1000.


============================================================
PAGE 18
============================================================

After sending the action, GSCView should display an “empty” “MyScene”.


============================================================
PAGE 19
============================================================

To display video channels in the viewers of “MyScene” the action “Viewer connect live” can
be used. The parameter “viewer” now means the global number of a viewer of “MyScene”,
e.g. 1102. The parameter “channel” should be set to the global number of the video channel
that should be displayed, e.g. 2.


============================================================
PAGE 20
============================================================

After sending the action, GSCView displays live video of the video channel 2 on the upper
left viewer in GSCView.