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 compression, GeViScope events, GeViScope actions and the principles of a client - server network 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 PLCSimulator.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 possibility 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 element has to be initialized with the sizeof() function.

MPEG-2 files that were created by SDK functions can possibly not be played with the windows 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 functions 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.

After work with instances is finished, the instances have to be deleted by calling their destroy() 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):

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):

The following example (in pseudo code) shows how to create a viewer and use it afterwards:

 // 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 offscreen viewer object class. If you want to decompress media, which should not be 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 DecompBuffer 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 function GMPCreateDecompBuffer(). The instance can be used for as many decompressions as needed. The method GetBufPointer() gives access to the raw picture data inside the buffer.

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(NewOffscreenImageCallback);

 // 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

 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 representing the list of resources. There are different Get…() methods, e. g. GetMediaChannels() or GetEvents().
4. Use the GUID array to receive the resources data by calling Get…Settings() methods, 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 = "/";

 // 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 function GMPQueryMediaChannelList() of the MediaPlayer interface as well.

PLC, actions and events

The PLC (Prcess Logic Control) object supports you with functionality for handling notifications, 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):

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 dispatched 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):

 // 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 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 created 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 “ServerType” 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.