geutebruck/GeViScope_SDK_Docs/GeViScope_SDK_Part02_Pages_21-40.txt

================================================================================
GeViScope SDK Documentation - Pages 21 to 40
================================================================================


============================================================
PAGE 21
============================================================

Background information
In GeViScope systems actions are used to communicate between the GeViScope server
and any client application. All available actions can be divided into three groups:
Notification actions (for example “User Login”), command actions (for example “Viewer con-
nect live”) and logical actions (these actions are not directly created by the GeViScope
server and they don’t directly result in any reaction in the GeViScope server, for example
“Custom action”).
All actions are grouped in different categories. The category “Viewer actions” contains all
actions that are relevant for remote controlling GSCView.
To get notifications about GSCView activities, one of the options “Send notification actions”
in the profile manager of GSCView has to be set. All possible notification actions are col-
lected in the action category “Viewer notifications”.


============================================================
PAGE 22
============================================================

More detailed information about all available actions can be found in the topic “Action doc-
umentation” (especially Viewer actions and Viewer notifications).
Please be aware of the fact that GSCView is working in an asynchronous mode. If a custom
application sends an action, that depends on the result of the previous sent action there may
be the need for inserting a pause time before sending the second action (e.g. send action
“Viewer connect live”, wait one second, send action “Viewer print picture”). GSCView does
not have an input queue for remote control actions.
Supported development platforms
The SDK is designed and tested to be used with the following development environments:
l CodeGear C++ Builder 6 ©
l CodeGear C++ Builder 2009 ©
l CodeGear Delphi 7 ©
l CodeGear Delphi 2005 ©
l CodeGear Delphi 2009 ©
l Microsoft Visual Studio 2005, C++, MFC ©
l Microsoft Visual Studio 2008, C++, MFC ©
l Microsoft Visual Studio 2005, C++/CLI ©
l Microsoft .NET © (wrapper classes are contained in the “Examples” folder)


============================================================
PAGE 23
============================================================

Guidelines and hints
Introduction
It is recommended to be familiar with the GeViScope system and the possibilities of modern
video surveillance systems and video management systems. Before starting programming
your custom GeViScope client you should know basics of video formats, video com-
pression, GeViScope events, GeViScope actions and the principles of a client - server net-
work communication.
The following sections support you with some suggestions and hints about using the SDK
interfaces.
General hints
If your application needs to listen to events and actions please use the application PLCSim-
ulator.exe that you can find on Your GeViScope device. This software allows you to start
actions and events which might be used by your program.
You should work and do some tests with a real GeViScope device or with the virtual test
environment belonging to the SDK. Create some events and actions, start them with
PLCSimulator.exe.
Starting the setup software GSCSetup.exe with the command line parameter /utilities will
offer you the possibility to open DBITest to discover the database structure and to evaluate
and test select statements against the database. Additionally this tool offers you the pos-
sibility to start the registry editor to evaluate the internal structure of the GeViScope setup.
Make sure to delete all objects that are created inside of DLLs. The objects
themselves should always offer a Destroy() or Free() method for that.
Callback functions, which are called out of the SDK DLLs, are called from threads, which
were created inside the DLLs. Variables and pointers that are passed as arguments of the
callback may not be used outside the callback context. They are only valid for the duration
of the callback call.
Structures that are used as arguments for SDK functions should always be initialized by the
function memset(). After setting all the structure elements to zero, the size or structsize ele-
ment has to be initialized with the sizeof() function.
MPEG-2 files that were created by SDK functions can possibly not be played with the win-
dows media player. The reason is a missing MPEG-2 decoder. We recommend using DVD
player software like PowerDVD or the VCL Media Player software.
Working with handles and instances
Integral part of the SDK are units that give the user a comfortable access to the plain func-
tions of the DLL, e.g. GSCDBI.h/.cpp/.pas. In these units classes encapsulate access to
instances of objects which are created inside the DLL. To have access from outside the
DLL (custom application) to the inside residing instances, handles are used. The units have
to be added to the project respectively to the solution to avoid linker errors.


============================================================
PAGE 24
============================================================

After work with instances is finished, the instances have to be deleted by calling their des-
troy() or free() method. Otherwise there will be memory leaks left.
Using the plain exported functions of the DLL is not recommended. To get access to full
functionality you should use the units instead (pas files or h/cpp files).
The following example (in pseudo code) should illustrate the above facts:
 // define a handle to a server object
 HGscServer MyServer;
// create a server object instance inside the DLL and
 // get a handle to it
 MyServer = DBICreateRemoteserver();
 ...
// work with the object instance with the help of the handle
 MyServer->Connect();
 ...
 // define a handle to a PLC object
 HGscPLC PLC;
  // create a PLC object instance inside the DLL and
 // get a handle to it
 PLC = MyServer.CreatePLC();
 ...
// work with the object instance with the help of the handle
 PLC->OpenPushCallback(...);
 ...
// destroy PLC object
 PLC->Destroy();
 ...
 // destroy server object
 MyServer->Destroy();
Interaction between DBI and MediaPlayer
The DBI interface gives access to GeViScope server functionality. After creating an
instance with the function DBICreateRemoteserver() a connection to the server can be
established by calling the method Connect() of the server object instance.
The following methods of a server object instance can be called to get access to different
kinds of functions (not a complete list):


============================================================
PAGE 25
============================================================

Method
Function
CreateDataSet(),
CreateDataPacket()
Fetch data from server database
CreateLiveStream()
Fetch live data from server
CreateRegistry()
Fetch setup data from server (media channel information, event
information, …)
CreatePLC()
Listen to, create and send actions
The example (in pseudo code) of the previous chapter should illustrate the above facts.
The MediaPlayer interface offers simple to use objects to display live and recorded video in
windows controls. A viewer object instance needs to be created by calling
GMPCreateViewer(). The viewer needs a handle to a windows control and a handle to a
server object instance. It handles fetching data, decompressing data and displaying video in
the linked windows control by itself.
The following methods of a viewer object instance can be called to get access to different
kinds of functions (not a complete list):
Method
Function
ConnectDB()
Fetch video data from the database and display it in any play mode required.
Filter and search criteria can optionally be defined.
SetPlayMode
(pmPlayNextEvent)
Display the next available event pictures
The following example (in pseudo code) shows how to create a viewer and use it after-
wards:
// define a handle to a viewer object
 HGscViewer MyViewer;
// create a viewer object instance inside the DLL and
// get a handle to it
 MyViewer = GMPCreateViewer(WindowHandle, ...);
// define a structure with data needed to link
// the viewer to a media channel in the server
 TMPConnectData MyViewerConnectData;
  // handle to the server object instance
 MyViewerConnectData.Connection = MyServer;
 MyViewerConnectData.ServerType = ctGSCServer;
 MyViewerConnectData.MediaType = mtServer;
 // ID of the media channel that should be displayed
 MyViewerConnectData.MediaChID = ...
// link the viewer to a media channel and display live data
 MyViewer->ConnectDB(MyViewerConnectData, pmPlayStream, ...);
 // destroy viewer object
  MyViewer->Destroy();
Beside the viewer object class there is another class in the MediaPlayer interface: The off-
screen viewer object class. If you want to decompress media, which should not be


============================================================
PAGE 26
============================================================

displayed with the help of the viewer object, you can use the offscreen viewer object. An
instance can be created with the function GMPCreateOffscreenViewer(). The offscreen
viewer object instance provides nearly the same functionality as the viewer object class
does. The video footage is not rendered in a window, it is decompressed in a special Decom-
pBuffer object instance. After the decompression is done inside the offscreen viewer, the
hosting application can be notified with the help of a callback function. Inside the callback
the decompressed image can be accessed.
The DecompBuffer class encapsulates special functions for effective decompressing. So it
is recommend to use it. Creating an instance of the buffer can be reached by calling the func-
tion GMPCreateDecompBuffer(). The instance can be used for as many decompressions
as needed. The method GetBufPointer() gives access to the raw picture data inside the buf-
fer.
Here is a short example (in pseudo code) how to work with an offscreen viewer object:
 // define a handle to a DecompBuffer object
 HGscDecompBuffer MyDecompBuffer;
 // create a DecompBuffer object instance inside the DLL and
 // get a handle to it
 MyDecompBuffer = GMPCreateDecompBuffer();
 // define a handle to a offscreen viewer object
 HGscViewer MyOffscreenViewer;
 // create an offscreen viewer object instance inside the DLL and
 // get a handle to it
 MyOffscreenViewer = GMPCreateOffscreenViewer(MyDecompBuffer);
 // set callback of the offscreen viewer object
 MyOffscreenViewer.SetNewOffscreenImageCallBack(NewOff-
screenImageCallback);
 // define a structure with data needed to link
 // the offscreen viewer to a media channel in the server
 TMPConnectData MyOffscreenViewerConnectData;
// handle to the server object instance
 MyOffscreenViewerConnectData.Connection = MyServer;
 MyOffscreenViewerConnectData.ServerType = ctGSCServer;
 MyOffscreenViewerConnectData.MediaType = mtServer;
 // ID of the media channel that should be decompressed
 MyOffscreenViewerConnectData.MediaChID = ...
// link the offscreen viewer to a media channel and decompress live data
 MyOffscreenViewer->ConnectDB(MyOffscreenViewerConnectData, pmPlayStream,
...);
 ...
 // destroy offscreen viewer object
 MyOffscreenViewer->Destroy();
 // destroy DecompBuffer object


============================================================
PAGE 27
============================================================

 MyDecompBuffer->Destroy();
 ...
 // callback function, that is called after images have been decompressed
 ...
 // get a raw pointer to the picture in the DecompBuffer
 // object
 MyDecompBuffer->GetBufPointer(BufferPointer, ...);
 // copy the picture into a windows bitmap resource
 // for example
 SetDIBits(..., BitmapHandle, ..., BufferPointer, ..., DIB_RGB_COLORS);
 ...
Enumeration of setup data
GeViScope Server resources can be enumerated by custom applications. The setup object,
which can be instantiated by calling the server method CreateRegistry(), offers functionality
for this.
Enumeration of resources normally is done in four steps:
1. Define an array of type GSCSetupReadRequest with the only element “/”. This
causes the method ReadNodes() to transfer the whole setup from the server to the
custom application.
2. Call the method ReadNodes() of the setup object to get the whole setup from the
server.
3. Call one of the Get…() methods of the setup object to get an array of GUIDs rep-
resenting the list of resources. There are different Get…() methods, e. g. GetMe-
diaChannels() or GetEvents().
4. Use the GUID array to receive the resources data by calling Get…Settings() meth-
ods, e. g. GetMediaChannelSettings() or GetEventSettings().
Here is an example (in pseudo code), that shows how to enumerate the media channels:
 ...
// connect to the server
 MyServer->Connect();
 ...
// define a handle to a setup object
 HGscRegistry MySetup;
 // create a setup object instance inside the DLL and
 // get a handle to it
 MySetup = MyServer->CreateRegistry();
// define a array for the setup read request
 GscSetupReadRequest SetupReadRequest[1];
 SetupReadRequest[0].NodeName = "/";


============================================================
PAGE 28
============================================================

// read the setup data from the server
 MySetup->ReadNodes(&SetupReadRequest, ...);
 // define a GUID array for the GUIDs of the
 // existing media channels
 GuidDynArray MediaChannels;
// get the GUID array out of the setup data
 MySetup->GetMediaChannels(MediaChannels);
// get the data of each single media channel
for each MediaChannelGUID in MediaChannels
 MySetup->GetMediaChannelSettings(MediaChannelGUID,
 MediaChannelID,
  GlobalNumber,
 ...);
 ...
// destroy setup object
 MySetup->Destroy();
// destroy server object
 MyServer->Destroy();
  ...
Please note that especially the media channels can be enumerated by using the global func-
tion GMPQueryMediaChannelList() of the MediaPlayer interface as well.
PLC, actions and events
The PLC (Prcess Logic Control) object supports you with functionality for handling noti-
fications, actions and events. The method CreatePLC() of the server object class creates a
handle to a PLC object inside the DBI DLL.
The following methods of a PLC object instance can be called to get access to different
kinds of functions (not a complete list):
Method
Function
SendAction()
Send an action to the connected server
StartEvent()
Start an event of the connected server
SubscribeActions()
Subscribe a list of actions that should be notified by a registered callback
function
OpenPushCallback
()
Register a callback function, that is called if an notification arrives or a
event starts/stops or if one of the subscribed actions arrives
To receive Notifications and actions a callback function can be registered with the method
OpenPushCallback(). After receiving an action, the action should be decoded and dis-
patched by the an instance of the class GSCActionDispatcher. The action dispatcher gives
you a simple way to react on specific actions. Here is a short example (in pseudo code):


============================================================
PAGE 29
============================================================

 // initialization code:
 ...
 // connect to the server
 MyServer->Connect();
 ...
// define a handle to a PLC object
 HGSCPLC PLC;
 // create a PLC object instance inside the DLL and
 // get a handle to it
 PLC = MyServer.CreatePLC();
  ...
 // link your callback function for a custom action
 // to the action dispatcher, so that the callback function
 // is called automatically if a cutsom action arrives
 ActionDispatcher->OnCustomAction = this->MyCustomActionHandler;
 // register a callback function for notifications,
 // events and actions (this callback function dispatches
 // all received actions with the help of the
 // GSCActionDispatcher)
 PLC->OpenPushCallback(...);
 ...
// destroy PLC object
 PLC->Destroy();
 ...
// destroy server object
 MyServer->Destroy();
 // callback function for all notifications, events and
 // subscribed actions:
 ...
 // dispatch the received action to the linked
 // callback functions
 ActionDispatcher->Dispatch(ActionHandle);
 ...
Media channel IDs
The existing media channels can be displayed by the viewer objects of the MediaPlayer
interface. Normally this is done with the method ConnectDB(). This method needs the


============================================================
PAGE 30
============================================================

media channel ID to identify the media channel (camera) that should be displayed.
The media channel IDs are generated automatically by the GeViScope server. Every cre-
ated media channel gets an ID that is always unique. So if you remove media channels from
the setup and add them again, they will sure receive some new IDs.
For that reason media channels should not be accessed by constant IDs. It is recommend
using global numbers instead, because they can be changed in the setup. To find the fitting
media channel ID for a given global number, the media channels should be enumerated from
the server setup. Please refer to chapter “Enumeration of setup data” in this document to
see how this is done.
There is a similar difficulty with events, digital inputs and outputs. Events don’t have global
numbers. Here the event name should be used instead.
Handling connection collapses
The callback OpenPushCallback() of the PLC object enables to listen to different kinds of
notifications from the PLC object. One is the “plcnPushCallbackLost” notification. It is fired
if a connection is internally detected as collapsed. As a reaction on this event you should
destroy or free all objects that were created inside the DLLs and start a phase of reconnect
tries. The reconnect tries should start every 30 seconds for example. Additionally your
application can listen to UDP broadcasts that are sent by the GeViScope server. After your
application received this broadcast it can directly try to reconnect to the server. Please be
aware of the fact, that broadcasts only work in LAN – routers normally block broadcasts.
Using MediaPlayer with GeViScope and MULTISCOPE III
servers
Generally the MediaPlayer interface can be used with GeViScope as well as MULTISCOPE
III servers. To link the server connection to the viewer object, the connection data structure
has to be defined. The type of the structure is “TMPConnectData”. The element “Server-
Type” identifies the kind of server whose media should be displayed in the viewer.
Please have a look on the example (in pseudo code) in the chapter “Interaction between DBI
and MediaPlayer” in this document.
For creating different kind of connections, different DLLs have to be used. For GeViScope
the DLL “GSCDBI.DLL” and for MULTISCOPE III the DLL “MscDBI.DLL” has to be
included in the project or solution of the custom application. They can coexist.
Handling a connection to a MULTISCOPE III server is similar to GeViScope. Details can be
found in the MULTISCOPE III SDK documentation.
Using the SDK with .NET
To make the usage of the native Win32 DLLs easier in .NET languages like C# or VB.NET,
the SDK contains some wrapper assemblies around the plain SDK DLLs.


============================================================
PAGE 31
============================================================

These wrapper assemblies are developed in C++/CLI and published with the SDK. The
assemblies can be found in the GeViScope SDK binary folder “GeViScopeSDK\BIN”.
The SDK provides wrapper assemblies for the .NET-Frameworks versions 2.0 and 4.0
which are named as follows:
.NET-Framework 2.0
• GscExceptionsNET_2_0.dll
• GscActionsNET_2_0.dll
• GscMediaPlayerNET_2_0.dll
• GscDBINET_2_0.dll
.NET-Framework 4.0
• GscExceptionsNET_4_0.dll
• GscActionsNET_4_0.dll
• GscMediaPlayerNET_4_0.dll
• GscDBINET_4_0.dll
These wrapper assemblies can be used together with our native SDK DLLs (GscAc-
tions.DLL, GscDBI.DLL, GscHelper.DLL, GscMediaPlayer.DLL, MscDBI.DLL) to create
custom applications under any .NET language on a windows platform. The assemblies
need to be referenced by the .NET project and all the files (assemblies and native DLLs)
have to reside in the application folder.


============================================================
PAGE 32
============================================================

Deploying a custom solution based on the .NET wrapper
To successfully deploy a custom application that uses the .NET wrapper contained in the
SDK, the following prerequisites have to be fulfilled:
a ) Mi c r os of t Vi s ual C+ + Re di s tr i buta bl e Pa c k age ha s to be
i ns tal l e d
The wrapper assemblies are developed in C++/CLI. So for executing them on a none devel-
opment machine, the Microsoft Visual C++ Redistributable Package is needed. This pack-
age exists in a debug or in a release version. On productive machines the release version
needs to be installed.
For applications using the .NET-Framework 2.0 the Visual C++ 2008 Redistributable Pack-
age is needed. In case that the application is developed using the .NET-Framework 4.0 you
need to install the Visual C++ 2010 Redistributable Package.
b) . N ET F r am e w or k Ve r s i on 2. 0 SP 1 or ne w e r ha s to be
i ns tal l e d
If updating the .NET Framework on a GEUTEBRÜCK device (GeViScope or re_porter)
fails, a special Microsoft tool Windows Installer CleanUp Utility (MSICUU2.exe) can
improve the situation. After executing this tool, updating the Framework should be possible.
c ) Wr appe r as s e m bl i e s AN D na ti v e SDK DLLs ar e ne e de d
Beside the custom application also the wrapper assemblies and the native SDK DLLs (lis-
ted above) are needed in the same folder as in which the custom application resides.
If the application uses the .NET-Framework 4.0 you need to reference the GeViScope wrap-
per DLLs with the extension _4_0 otherwise please use the wrapper assemblies with the
extension _2_0 (see above).
GeViScope REGISTRY
Using the GscRegistry with .NET
Introduction
By using the GeViScope registry (GSCREGISTRY) it is possible to modify GeViScope/Re_
porter settings programmatically. The GscRegistry is a proprietary registry format
developed by GEUTEBRÜCK. This registry format is similar to the Microsoft Windows
registry.


============================================================
PAGE 33
============================================================

All needed GeViScope server settings are stored in the GscRegistry database. The creation
of own registry databases based on files is also possible.
The GEUTEBRÜCK GEVISCOPE SDK provides several classes and methods to allow a
comfortable access to the GscRegistry.
Requirements
The following requirements are needed to create a .NET application that uses the GscRe-
gistry functionality:
• .NET-Framework 2.0 SP1 or newer
- .NET-Framework 2.0 SP1 Wrapper-Assemblies:
GscExceptionsNET_2_0.dll
GscDBINET_2_0.dll
- .NET-Framework 4.0 Wrapper-Assemblies:
GscExceptionsNET_4_0.dll
GscDBINET_4_0.dll
• Native Win32-DLLs, used by the .NET-Wrapper:
- GscActions.dll
- GscDBI.dll
- GscMediaPlayer.dll
- GscHelper.dll
- MscDBI.dll
• Microsoft Visual C++ Redistributable Package
Using the registry
In the following, the usage of the GscRegistry with .NET is explained in detail. It discusses
the following steps:
l Open the registry
l Read values out of nodes
l Create a node
l Add values to a node
l Save the registry
All necessary classes and methods for using the GscRegistry are available in the GscDBI
namespace. To include this namespace the following using-statement is needed:
using GEUTEBRUECK.GeViScope.Wrapper.DBI;
Ope n the r e gi s tr y
To read or modify GeViScope/Re_porter settings it is necessary to establish a connection
to the preferred GeViScope/Re_porter server before. After this is done you need to create a
new object of the class GscRegistry and initialize it by using the CreateRegistry() method
which is contained in the GscServer object.
C#-Code: Open the registry
if (_GscServer != null)
{
// create an object instance of the server registry
GscRegistry GscRegistry = _GscServer.CreateRegistry();
if (GscRegistry != null)
{
// define an array for the setup read request (registry node paths
to read)


============================================================
PAGE 34
============================================================

GscRegistryReadRequest[] ReadRequests = new GscRegistryReadRequest
[1];
ReadRequests[0] = new GscRegistryReadRequest("/", 0);
// read the nodes (setup data) out of the server registry
GscRegistry.ReadNodes(ReadRequests);
}
}
The method ReadNodes() of the GscRegistry object expects an array of the type GscRe-
gistryReadRequest which contains all node paths to be read out of the registry. In the
source code snippet above, the array simply contains one element which represents the
root node (“/”). By reading the root node the entire registry will be read out.
Re a d v al ue s of node s
The following source code snippet shows how to read values out of nodes:
C#-Code: Read values out of nodes
if (GscRegistry != null)
{
GscRegNode RegNode = GscRegistry.FindNode("/System/MediaChannels/");
for (int i = 0; i < RegNode.SubNodeCount; ++i)
{
// find the GeViScope registry node of the parent node by means of
the index
GscRegNode SubRegNode = RegNode.SubNodeByIndex(i);
GscRegVariant RegVariant = new GscRegVariant();
// Get the value "Name" out of the sub registry type and store the
value and
// value type in the GscRegVariant class
SubRegNode.GetValueInfoByName("Name", ref RegVariant);
if (RegVariant != null && RegVariant.ValueType ==
GscNodeType.ntWideString)
Console.WriteLine(RegVariant.Value.WideStringValue);
}
}
To read a specific node out of the registry the GscRegistry class provides the method
FindNode().
For that the path to the preferred node has to be committed to the method and it you will get
back an object of the type of GscRegNode. This object contains all sub nodes and values of
the found node.
To access a sub node of the parent node the method SubNodeByIndex() provided by the
class GscRegNode can be used or use the SubNodeByName() method if the name of the
sub node is already known.
The method GetValueInfoByName() can be used to access a specific value of a node. This
method expects the name of the specific value as well as a reference to an object of type of
GscRegVariant. The GscRegVariant object will be filled with the type of the value
(ValueType) as well as the value itself (Value).
Cr e ate a node


============================================================
PAGE 35
============================================================

To create a new node in a parent node the method CreateSubNode() which is provided by
the class GscRegNode needs to be called. The method expects the name of the new node.
C#-Code: Create a node
if (_GscRegistry != null)
{
GscRegNode RegNode = _GscRegistry.FindNode("/System/MediaChannels/0000");
// create a new sub node in NodePath
if (RegNode != null)
RegNode.CreateSubNode("NewNode");
}
Add v al ue s to a node
There are several methods in the class GscRegNode to add values to a node. Depending on
the type of the value it is needed to call the right method for writing this type into the registry.
For example if you would like to write an Int32 value into the registry you need to use the
method WriteInt32().
C#-Code: Add values to node
public void AddValue(string NodePath, string ValueName, GscNodeType ValueType,
object Value)
{
GscRegNode RegNode = _GscRegistry.FindNode(NodePath);
if (RegNode != null)
{
switch (ValueType)
{
case GscNodeType.ntWideString:
{
RegNode.WriteWideString(ValueName, Value.ToString());
break;
}
case GscNodeType.ntInt32:
{
RegNode.WriteInt32(ValueName, Convert.ToInt32(Value));
break;
}
}
}
}
Sa v e the r e gi s tr y
After the GscRegistry object was modified (e.g. new nodes/new values), the server also
needs to know about the changes made. For this the GscRegistry class provides the
method WriteNodes().
C#-Code: Add values to node
// define an array for the setup write request


============================================================
PAGE 36
============================================================

GscRegistryWriteRequest[] WriteRequests = new GscRegistryWriteRequest[1];
WriteRequests[0] = new GscRegistryWriteRequest("/", 0);
GscRegistry.WriteNodes(WriteRequests, true);
The WriteNodes() method expects an array containing objects of the type of GscRe-
gistryWriteRequest. Each GscRegistryWriteRequest contains a path to a node that has to
be saved.
 NOTICE
It is recommended to only add one element to this array which contains the root path (“/”).
This results in saving the entire registry structure.
Structure of GSCRegistry
The GEVISCOPE SDK offers two possibilities to browse the structure of the GscRegistry.
By means of the application GscRegEdit that is delivered with the SDK, it is possible to
browse or modify the registry similar to Microsoft’s Windows registry.
In addition to GscRegEdit you can also use the registry editor which is integrated in
GSCSetup. To activate this feature the key combination STRG+ALT+U needs to be actu-
ated. The entry Registry editor in the section Utilities in the navigation bar on the left will
now be shown.
Examples
To get a better idea of how to use the GscRegistry, the GEVISCOPE SDK provides further
.NET example applications.
The examples can be found in the folder „Examples“ folder in the GeViScopeSDK main
folder:
l C:\Program Files (x86)\GeViScopeSDK\Examples\VS2008NET\VS2008NET_
GscRegEdit
Simple registry editor, GUI application (Visual Studio 2008)
l C:\Program Files (x86)\GeViScopeSDK\Examples\VS2008NET\VS2010NET_
GscRegEdit
Simple registry editor, GUI application (Visual Studio 2010)
l C:\Program Files (x86)\GeViScopeSDK\Examples\VS2008NET\VS2008NET_
GscRegistryBasics
Console application (Visual Studio 2008)
l C:\Program Files (x86)\GeViScopeSDK\Examples\VS2010NET\VS2010NET_
GscRegistryBasics
Console application (Visual Studio 2010)
GSCView data filter plugins
Introduction
GSCView offers the possibility to integrate customized data filter dialogs. Data filter dialogs
are used to search and filter video footage by additional event data. They can be customized
to the different business environments in which GeViScope is used.


============================================================
PAGE 37
============================================================

The following sections support you with some suggestions and hints about creating cus-
tomized data filter plugins.
General hints
Custom data filters are hosted in flat windows 32Bit dynamic link libraries. Differing from nor-
mal DLLs the data filter DLLs have the extension “.GPI”. All data filter DLLs existing in the
same folder as GSCView are integrated in GSCView automatically.
The customized data filter DLL interface
Each DLL has to export the function GSCPluginRegisterSearchFilter() that is called by
GSCView to use the customized dialogs. The exact definition of this function and some
additional type definitions can be found in the unit “GSCGPIFilter.pas/.h”.
Inside the function GSCPluginRegisterSearchFilter() one or even more data filter dialogs
have to be registered by calling the function Callbacks.RegisterFilter().
The following example (in pseudo code) shows how this is done:
if(Callbacks.RegisterFilter == NULL)


============================================================
PAGE 38
============================================================

return FALSE;
TPluginFilterDefinition def;
def = SimpleFilter.GetFilterDefinition();
Callbacks.RegisterFilter(Callbacks.HostHandle, def);
The structure TPluginFilterDefinition defines some informational data and all the callback
functions needed for a single dialog. GSCView uses the definition to call the different call-
back functions during its execution.
Name of callback
function
Function
InitFilter()
Can be used to initialize the data filter dialog. To integrate the dialog in
GSCView, the function has to return true.
ShowFilter()
Inside this function the dialog should be displayed as a stand-alone
(modal) dialog. GSCView calls the function after the user activates the
 button.
DeinitFilter()
Can be used to deinitialize the data filter dialog. The function has to return
true, even if it is not used.
GetFilterGuid()
The function should provide a global unique identifier (GUID) that is used
inside GSCView to identify the dialog. The GUID can be defined as a static
constant value.
As an alternative to the modal display of the data filter dialog, the dialog can be displayed
nested in the GSCView main window or GSCView event list. But at the moment this feature
is only supported by custom filter dialogs created with Borland Delphi ©.
To achieve the nested display, the additional callback functions of the structure TPlu-
ginFilterDefinition have to be implemented. The Borland Delphi © example
“GSCViewDataFilter” demonstrates the details.
Creating the filter criteria
If the custom data filter is applied, GSCView does a query against the tables “events” and
“eventdata” of the internal GeViScope database. For this query a filter criteria is needed. The


============================================================
PAGE 39
============================================================

custom data filter delivers the criteria and gives it back to GSCView in the ShowFilter() call-
back function.
To build up meaningful filter criteria some background knowledge of the GeViScope data-
base is needed.
The table “events” contains all the events recorded in the database (only event information,
not the samples; the samples are linked to the events).
The table “eventdata” contains additional data belonging to the events. Inside the table the
different parameters of actions are saved. If for example an event is started by the Cus-
tomAction(4711, “Hello world”), the value 4711 is saved in the row “Int64_A” and the value
“Hello world” is saved in the row “String_A”. Because the event is started by a Cus-
tomAction, the value 8 is saved in the row “EventDataKind”. Each action has an individual
mapping of action parameters to rows in the table “eventdata”.
For different business environments special actions can be created by GEUTEBRÜCK.
There already exist some special actions like:
Action name
Business environment
ATMTransaction()
Automated teller machines
ACSAccessGranted()
Access control systems
SafebagOpen()
Cash management systems
POSData()
Point of sale systems
The action internally defines the mapping of action parameters to rows in the table “event-
data”. The code of an action (for a CustomAction the code is 8) is stored in the row
“EventDataKind”. The codes of actions are listed in the action reference documentation
“GSCActionsReference_EN.pdf”.
To evaluate the mapping of action parameters to database rows, GSCSetup can be used.
By pressing STRG+ALT+U in GSCSetup the special utility “DBI test” gets available.
With “DBI test” the structure and content of the GeViScope database can be analyzed. The
following SQL queries can be helpful:
SQL query
Function
select * from events
Fetches records from the table “events”
select * from eventdata
Fetches records from the table “eventdata”
select * from samples
Fetches records from the table “samples”
The following table should demonstrate how to build up filter criteria depending on para-
meters given in the custom data filter dialog (here the CustomAction() is used to start the
events):


============================================================
PAGE 40
============================================================

Action
para-
meter
INT
Action
para-
meter
STRING
Fil-
terCriteria.SQLstatement
SQL query
Nothing
Nothing
EventData.EventDataKind = 8 select * from EventData left join Events on
EventData.EventID = Events.EventID with
EventData.EventDataKind = 8
Nothing
Hello
world
EventData.EventString_A =
"Hello world" and
EventData.EventDataKind = 8
select * from EventData left join Events on
EventData.EventID = Events.EventID with
EventData.EventString_A = "Hello world"
and EventData.EventDataKind = 8
4711
Nothing
EventData.EventInt64_A =
4711 and
EventData.EventDataKind = 8
select * from EventData left join Events on
EventData.EventID = Events.EventID with
EventData.EventInt64_A = 4711 and
EventData.EventDataKind = 8
4711
Hello
world
EventData.EventInt64_A =
4711 and
EventData.EventString_A =
"Hello world" and
EventData.EventDataKind = 8
select * from EventData left join Events on
EventData.EventID = Events.EventID with
EventData.EventInt64_A = 4711 and
EventData.EventString_A = "Hello world"
and EventData.EventDataKind = 8
Nothing
Hello*
EventData.EventString_A =
"Hello*" and
EventData.EventDataKind = 8
select * from EventData left join Events on
EventData.EventID = Events.EventID with
EventData.EventDataKind = 8 where
EventData.EventString_A LIKE "Hello*"
During testing the custom data filter dialog in the GSCView event list a double click on the
status bar of the event list delivers the SQL query that is executed in the GeViScope server.
Examples overview
The examples overview is organized in two different views on all examples including the
GeViScopeSDK:
Examples grouped by programming tasks
Examples grouped by development platforms