geutebruck/SOURCES/CODEX/GeViSoft/GeViSoft_SDK_Documentation.md

GeViSoft_SDK_Documentation

Converted from GeViSoft/GeViSoft_SDK_Documentation.pdf using pdftotext -layout.

GeViSoft SDK Doku men tati on | Doc u men tati on | Doc u men tati on | Doc u men tati ón

Version 2012_1.7 | Date 19.07.2012 GeViSoft SDK Introduction The GeViSoft SDK allows integrating your custom solutions and products with Geutebrück’s GeViSoft suite. It includes an application programming interface (API) with all necessary DLLs, headers, example projects, and documentation to help you getting started with your integration easily.

The SDK supports C++ and Delphi. Furthermore a .Net wrapper is included which allows you to use the SDK from C#. It provides various example projects and solutions in these lan- guages. GeViSoft GeViSoft is Geutebrück’s central management system for video control. Its main function is the switching of video signals between different cameras, monitors and DVRs by controlling a video matrix system. Alarm handling as well as the remote control of pan/tilt and dome cam- eras is a further functionality of GeViSoft.

GeViSoft can also be used to handle general purpose digital inputs and outputs and thus allows integrating custom sensor technology and actuating elements to the Geutebrück sys- tem.

Furthermore, different peripherals common to video control systems, like video motion anal- ysis or operator consoles, can be managed.

GeViSoft Architecture The architecture of GeViSoft follows the client-server paradigm. The server software (GeV- iServer) usual runs on a dedicated PC. This hardware platform is called GeViStation. The combined system of software and hardware is called GeViControl.

At least one IO client must handle connections to the peripherals. This client is com- municating with the GeViSoft server and runs on the same machine. It is called GeViIO.

The GeViIO client provides the interfaces for the communication to the attached peripherals like a VX3 matrix or a PTZ. These peripherals can also be virtualized.

GeViServer and GeViIO can be configured from the GeViSet application. The configuration is described in detail in chapter Configuration of GeViSoft.

The following figure shows a setup of GeViSoft with an attached VX3, digital IO and two PTZ devices. Figure 1 - GeViSoft Example Configuration

Historically, there has been a demand to control a large number of video feeds with a limited number of monitors in surveillance systems. This has lead to the invention of video matrixes like the VX3, which allowed different camera signals to be dynamically routed to the attached monitors. The routing could be user initiated or triggered by external events like alarms or dig- ital inputs.

Besides the video routing it was necessary to allow the operator to remote control PTZ and dome cameras from a central console to react on alarms or other events.

A configuration like the one described above is reflected in the setup according to figure 1.

Nowadays analogue video cameras and monitors are getting replaced by IP cameras and PCs running software viewers like GSCView. GeViSoft allows the handling of these modern setups as well so that they can be integrated seamlessly into existing installations.

Figure 2 gives an example for a complex setup integrating analogue as well as digital com- ponents. Figure 2 - Complex GeViSoft Setup Additional to controlling the cross switching inside the matrix, GeViSoft can be used to com- municate with GeViScopes. It is possible to configure GeViSoft in such a way that a GeV- iScope and the connected GscViews can be controlled just like an analogue video matrix, e.g. a VX3.

The next chapter gives an overview of the different components that add up to GeViSoft.

GeViServer GeViServer is the backend server in a GeViSoft system. It also manages the internal data- base. GeViServer usually runs as a Windows service on production machines, but can also be started as a console application for testing purposes or debugging. If installed by the SDK setup, the GeViServer must be started from the console.

It is possible to run GeViServer in a cluster to increase reliability.

GeViAdmin The application GeViAdmin is used to set up the GeViServer database. It can also be used to configure redundancy settings by clustering several GeViServers. Furthermore, GeViScope can be used for diagnostics and load analysis. GeViAdmin is part of the shipping product, but not of the SDK. The SDK installer automatically sets up a GeViSoft database during the installation process.

GeViIO The GeViIO client is responsible for the communication with the external interfaces and peripherals. It runs on the same machine as the GeViServer. Other instances of GeViIO might run on separate machines. GeViSet GeViSet is the configuration tool for GeViServer. It can be used to configure GeViIO clients, users, events, alarms and all other functionalities of GeViServer, as well as connections to GeViScope servers. Some configuration steps and options inside GeViSet are shown in the following chapters.

GeViAPI Test Client The GeViAPI Test Client allows testing and debugging GeViSoft applications. With this tool you can send and receive actions and alarms, query the database, and retrieve system infor- mation. SDK Introduction The GeViSoft SDK provides you with an open application programming interface to the GeV- iSoft suite and allows you to integrate your custom products with Geutebrück’s.

The SDK includes the DLLs and corresponding header files required by your C++ or Delphi projects. Furthermore .Net wrapper Dlls are included which allow you to use the SDK from your C# application.

Several example applications help you getting started with the GeViSoft SDK development and may act as a foundation for your own solutions.

Files and Directory Structure During installation, the environment variable %GEVISOFTSDKPATH% is set. It points to the root directory of the SDK installation. The variable’s value is determined by the path chosen as the install directory during setup. Usually, this is “C:\GEVISOFT”. All SDK directories are located inside this root directory.

This is a (partial) tree view of the standard installation: Please note that the directory C:/GEVISOFT/DATABASE will be created without regarding the chosen install path. This directory hosts the GeViSoft database GeViDB.mdb which is hidden by default.

Inside the %GEVISOFTSDKPATH% directory, a structure like this is created: l A Documentation folder containing all GeViSoft related documentation and manuals. l An Examples folder including subfolders that are named according to the cor-

    responding IDE and programming language.
    - Inside each of these, there is a GeViScopeSDK and GeViSoftSDK folder with the
    respective Include and Lib folders for the programming language as well as the folders
    with the different examples.
    - The C++ headers are located inside the Include folder and the libraries inside the Lib
    folder.
    - For Delphi, the .pas and the .inc files can all be found inside the Include folder.

The %GEVISOFTSDKPATH% directory itself hosts all the executables, dynamic link libraries, and runtime files that are needed by GeViSoft. By default, all the example projects will output their generated binaries into this folder as well. This guarantees that all runtime dependencies are met and your compiled executables find the needed DLLs. Additionally, the .Net wrapper assemblies Geutebrueck.GeViSoftSDKNetWrapper.dll and GscActionsNET.dll reside in this folder. SDK Setup Setup of Test/Build Environment This chapter describes how to setup and configure the GeViSoft test environment.

NOT ICE

Please note that you need administrative privileges on the development machine.

Installation of GeViSoft The SDK is shipped as an executable installer. You just need to run it on your development machine in order to install the SDK.

NOT ICE

It is highly recommended to install GeViSoft to the default path C:/Gevisoft.

W ARNING

Please make sure that you do not install the SDK on a production GeViSoft machine as the setup will overwrite the installed GeViSoft files without notice.

Starting GeViServer You can start GeViServer from the command prompt by issuing the command %GEVISOFTSDKPATH%/geviserver.exe console or by executing the startserver.bat script in your GeViSoft installation’s root folder. The console argument forces the software to run as a console application and allows you to easily monitor the server’s output. On a production machine, GeViServer usually runs as a windows service.

NOT ICE

Please note that without a license dongle, the server will terminate after two hours. You can
directly restart it without any further restrictions.

Configuration of GeViSoft In this chapter you will learn how to establish a connection to the GeViServer with the setup client GeViSet (Setting up the server connection).

After that there is a description for setting up a GeViIO client that provides a virtual video matrix and digital IO (Configuration of the GeViIO Client). You do not need to carry out the steps described in that paragraph. They are for reference only because this configuration is already done for you in the database that is delivered with the SDK.

Setting up the server connection

1 Start GeViServer by executing startserver.bat if not already done so 2 Start GeViSet.exe 3 Setup the server connection a Open File -> GeViSoft server connections b If a connection localhost exists, press Connect and move to step 4 c If no connection exists choose Connections -> New Connection d Enter localhost as the name of the new connection and press the Forward button e In the Create New Server Connection window set the computer name to localhost, the user name to sysadmin. Check Save password and set the password to mas- terkey. Select Local connection as connection type. Press the Forward button. Choose the localhost connection and press Connect Configuration of the GeViIO Client (reference)

The GeViIO client’s configuration is already done for you inside the database that is shipped with the SDK. The steps described here are only a reference for you if you need to adapt set- tings for your test environment.

1. In the Clients field push the Add button and add a new GeViIO client with the name GeViIO_01.
2. Select the new GeViIO client and press Configure.
3. Mark the client as Active and Virtual.
4. Add a new VX3 matrix by pressing Add in the Interfaces field and selecting the appro- priate type (VX3/CX3). Name the interface Virtual VX3.
5. Select the newly created VX3 interface and press Edit.
6. Add 16 new video inputs to the VX3 interface by pressing the Add button in the Video inputs tab. In the New video Input window set Count to 16 and press ok. The new video input channels should show up in the Video input tab.
7. Add 4 new video outputs in the same manner as the inputs.
8. Add 8 new input contacts and 8 new output contacts in the same way you did for the video input.
9. Send your newly created setup to the server by choosing File -> Setup to server or by clicking .

Now your client window should look like this: Connection to GeViScope (optional) If you have a GeViScope server up and running, you can connect GeViSoft to it via a TCP/IP connection. If connected, actions can be exchanged between the two systems. As an example this can be used to remote control GSCView.

Please note that you can install the GeViScope Server as a part of Geutebrück’s GeViScope SDK if you have not done it yet. You can download this SDK on www.geutebrueck.com or request it from the SDK division.

Installing the GeViScope SDK is a prerequisite for the scenario and example in the chapter Switching Video.

You can configure the connection to GeViScope inside GeViSet. Choose the menu Server -> GeViScope Connections and press Add in the pop-up menu. You can then configure the con- nection parameters inside the GeViScope connection window.

NOT ICE Please note that the Alias is used to address different GeViScope servers from inside the SDK with GSCActions. See Action messages –> creating action messages > 4. Example of cre- ating a GeViScope Action Message First Steps with GeViSoft This chapter will lead you throughout your first steps with GeViSoft. You will learn how to con- nect to a GeViServer, send some basic actions, and customize message logging and display to your needs. If you are already familiar with GeViSoft, you can skip this chapter or skim through it.

GeViAPI Test Client The easiest way to test your GeViSoft setup is by using the GeViAPI Test Client. You can start it from your %GEVISOFTSDKPATH% directory.

Please make sure that your GeViServer is already started. If not start it by executing the “startserver.bat” inside the GeViSoft root directory.

After startup connect to the GeViServer by adding your credentials and pressing the “Conn” button. If everything works out, the “Connected” indicator will be illuminated in green and sev- eral messages will pop up in the “Communication log”. At this point your communication is set up correctly.

If you have followed the configuration steps in chapter Setting up GeViIO you will already be able to use GeViSoft for switching your virtual video I/O.

Cross Switching Video Select the tab Video/DigIO. You can switch your video signal in the following way:

1. Select an active input and an active output. The signal will be switched between these
two. You can see the active I/O on the windows right hand side beneath the text Video.

     a) To select an active output, left-click on one of your configured video outputs in the
     upper window area. You should see Act Out changing with regard to your selection.

 b) Now move the mouse over the desired input (e.g. 7) and right-click on the input. The number of your selected input should now appear in the black square above your selected output.

2. Clear a video output. Move the mouse over the output to clear and right-click on it. The number in the black square above the output should vanish. NOT ICE

When switching the output, a CrossSwitch action with the chosen channels is displayed in the Communication Log shown in the lower part of the GeViAPI Test Client’s window.

If a real VX3 would be connected to your GeViSoft and the inputs were connected to video sig- nals, you would switch the real signal to the according output (normally a monitor). You will learn how to use these switch actions to remote control a GscView in the same way you would use an analogue matrix in the chapter Switching Video.

Manipulating Digital I/O Similar to the video signals you can switch digital outputs and generate digital input signals in your virtual test client.

Generate a simulated digital input:
To generate an input move your mouse pointer over the desired input channel. A left click
will simulate a closing of the contact, a right click an opening. The contacts’ states are
color coded according to this table:
          Color         State
          White         Unknown
          Red           Closed
          Green         Open
          Gray          Unavailable


Generate a simulated digital output:
To generate an output move the pointer over the desired output signal. Left-clicking will
set the output’s state to open, right-clicking to close. The outputs’ states are color coded
according to this table:
         Color         State
         White         Unknown
         Red           Closed

 Green Open Yellow Alternating (Can be set via Alternate Contact action) Gray Unavailable

I nformati on If th e GeVi IO c l i en t w as c on n ec ted to r eal DIO h ar d w ar e, you c ou l d s ee th e i n p u t s i g n al s c h an g i n g i n r eal ti me. Setti n g of th e ou tp u ts w ou l d r es u l t i n s w i tc h i n g r eal l oad s . Actions So far you only used GeViAPI Test Client’s built-in functionality to interact with GeViServer. In this chapter you will learn to use GeViSoft actions to control the system.

GeViSoft actions can be sent by typing them into the text box in the lower middle of the GeVi- API Test Client’s window. You can find a complete list of the possible actions in the doc- umentation.

Hin t Y ou c an i n ter ac ti vel y g en er ate ac ti on s an d l ear n ab ou t th ei r p ar ameter s b y c om- p os i n g th em i n GeVi Set. T h er ef or e, op en GeVi Set, an d c on n ec t to th e s er ver . T h en n avi g ate to Ser ver - > Named ac ti on s an d p r es s Ad d i n th e w i n d ow th at p op s u p . In th e w i n d ow Named ac ti on s etti n g s you may p r es s th e b u tton w i th th e th r ee d ots ( “ … ” ) to take you to th e Ac ti on s etti n g s men u .

T h er e you c an c h oos e an y of th e i mp l emen ted ac ti on s an d vi ew th ei r p ar ameter s an d s etti n g s . T o f i l ter th e ac ti on s b y c ateg or y c h oos e on e of th e c ateg or i es f r om th e u p p er l ef t l i s t b ox. Hoover th e mou s e over an y of th e p ar ameter s to g et a d etai l ed d es c r i p ti on of i t.

As an examp l e s el ec t Cr os s b ar c on tr ol as a c ateg or y an d move to Cr os s Sw i tc h to s ee th e mes s ag e’ s p ar ameter s on th e r i g h t s i d e.

T h e c omp l ete mes s ag e i s : CrossSwitch(ID VideoInput, ID VideoOutput, Switchmode) .

Cross Switching Video 1. Route video from an input to an output -- To send the video from input 7 to output 3, do the following:  a) Type this action into the text box in the lower middle of the GeViAPI Test Client window and send it: CrossSwitch(7, 3, 0)

b) Make sure that the signal is routed accordingly by checking the output in the tab
Video/DigIO

c) Route video input 3 to output channel 2. (CrossSwitch(3,2,0))

2. Clear video output 2: ClearVideoOutput(2) Cross switching video 1 Manipulating Digital I/O

3. Open contact 1 and close contact 2 -- The actions OpenContact(ContactNumber) and CloseContact(ContactNumber) can be used to set the digital outputs from GeViSoft.

   a) To open contact 1 send the action: OpenContact(1)

   b) In the Tab Video/DigIO of GeViAPI Test Client make sure that the indication of output one has turned to green

   c) To close contact 2 send the action: CloseContact(2)

   d) Make sure that the output turned red.

4. Simulate a closing of the input contact 3 and an opening of the input contact 5

   a) InputContact(3, true)

   b) Make sure that input 3 is signaling closed (red indication)

   c) InputContact(5, false)

   d) Make sure that input 5 is signaling open (green indication)

5. Alternating a contact -- Simulate a flash light on output 8

   a) To alternate a contact, you can use the action AlternateContact(ContactID, BlinkPeriod_in_ms, BlinkOnTime_in_ms)

   b) Send the command to flash the light with a frequency of 1 Hz and a duty cycle of 500ms: AlternateContact(8, 1000,500) c) Check that the contact is alternating – after pressing the Refresh button, the out- put 8 state should be alternating (yellow). Manipulating digital IO GETAS In this chapter you will learn about GETAS, the Geutebrück Telnet Action Server. The GETAS component allows you to send and receive GeViSoft actions via telnet. Multiple clients can connect to one GeViServer at a time.

The telnet interface allows you to easily integrate simple applications into your GeViSoft infra- structure. Furthermore it offers an option to connect non-Windows platforms.

CAU T ION

By default, GETAS is not active. To activate GETAS, open GeViSet and navigate to Server -> GETAS. In the GETAS settings window, you can then activate the component by checking Enable TCP port. By default GETAS will listen to port 7707. Leave the other settings unmodified and press OK. Send the altered setup to the server afterwards (File -> Setup to server).

CAU T ION

To connect to GETAS, you need a telnet client. You can either use the Windows telnet client or a third party application like putty.

ADVICE

If you are using Windows 7, the telnet client is not activated by default. To activate it go to Start -> Control Panel -> Programs and Features and select the Telnet Client from the list box.

Now you can connect to GeViServer and send some actions.

Basic GETAS Usage 1. Connect to GeViServer via GETAS – Open a command window (cmd.exe) and start telnet. In a command window type: telnet localhost 7707  2. Make sure that your input is echoed locally by entering set localecho

3. You may want to press enter once to clear your screen if necessary.

4. Make sure that you started your GeViAPI Test Client and connected it to the GeV- iServer

5. Send an action to the server:

   a) CustomAction(42, "Hello GETAS")

   b) If you receive an echo of your action preceded by a 4; from the GeViSoft server, your configuration is working

   c) Verify that you can also see the action in the GeViAPI Test Client’s com- munication log. If you cannot see the message, make sure you are connected and your filter settings in the tab Filter GeViSoft are set correctly. To be sure, set the filter to accept all messages.

6. Monitor actions sent by other clients in your telnet session:

   a) Send an action from GeViAPI Test Client: CustomAction(23, "Hello GETAS client")

   b) Verify that you received the action in your telnet window.

Video and IO Control with GETAS

1. Now control your virtual VX3 by using GETAS – Make sure that GeViAPI Test Client is running while you issue commands via telnet and you can see the Video/DigIO tab. Your GeViIO_01 configuration should be the same as in chapter Setting up GeViIO.  2. Route video input 7 to video output 2:

   a) Connect to the GeViServer via telnet in a command window if not done it yet.
   
   b) Send: CrossSwitch(7,2,0)
   
   c) Make sure that the video signal is routed correctly in the Video/DigIO tab of GeVi-
   API Test Client
   

3. Copy the video signal from output 2 to have it also on output 4:

     a) Send: CopyCameraOnMonitor(2,4)

     b) Make sure, that input 7 is routed to output 2 and 4 in the GeViAPI Test Client

4. Clear the video output on channel 2:

     a) Send: ClearVideoOutput(2)

     b) Make sure the command worked (GeViAPI Test Client)

5. Close digital output contact 5:

     a) Send: CloseContact(5)

     b) Verify the result of the command in GeViAPI Test Client

GETAS Limitations GETAS can be used for simple applications or integration of non-Windows clients. Nev- ertheless there is one limitation. The telnet connection is only established to one server at a time. If GeViServer is running in a redundancy setup, the actions are not forwarded between the different servers.

W ARNING

If you plan to integrate your GETAS solution into a complex setup with mirroring, you have to take care of the communication with the different servers on your own.

This has not to be considered if you are using the SDK functionality as described in chapter SDK Usage. The SDK functions will take care of communicating with the various systems. Action Mapping Action mapping comes in handy if you need to trigger one action by another. Assume you want to switch on a beacon if a door is opened. The beacon is connected to a digital output 2 and the door to a digital input 3 (which opens together with the door). These actions can be mapped in the following way.

1. In GeViSet select Server –> Action mapping

2. Press Add in the Action mapping window. The Action mapping settings window will
open.

3. Press the … button to add a new input action and choose the Digital contactscategory
in the Action settings window

4. Select the InputContact action and set the parameters GlobalContactID to 3 and
ChangedTo to false. Set Caption to door contact has opened and press OK.

5. Press the + button to set the output action in the Action mapping settings window

6. To flash a beacon, the output signal must alternate between on and off. This can be
achieved with the AlternateContact action.

7. Set the AlternateContact action’s parameters to GlobalContactID = 2, BlinkPeriod =
1000ms, and BlinkOnTime = 500ms. Enter blink the beacon as Caption.

8. Send the setup to the GeViServer

9. Test the mapping by sending the action InputContact(3,false) either by GETAS or
inside GeViAPI Test Client. You should see the mapped action AlternateContact(2,
1000, 500) delivered by the GeViServer directly afterwards. You can also check the out-
put’s status in GeViAPI Test Client’s Video/DigIO tab after hitting the refresh button.

 10. To switch off the beacon after the door has closed, you need to map another action pair in GeViSet. For that, map InputContact(3, true) to CloseContact(2) and send the setup to the GeViServer.

11. Check if the beacon is switched off immediately after sending the action Input-
Contact(3, true)

Please note that you can map multiple actions to one input. This allows you to realize more complex setups. Timer (optional) GeViSoft allows you to configure timers which can schedule actions, giving you a versatile tool for custom applications. You can configure different types of timers in GeViSet. Timers internally count in “ticks”. Each tick equals one millisecond.

Types of Timers l Once timer (single shot) – this timer counts down for the number of main ticks after being started and at the end fires the configured action

l   Periodical timer – this timer allows triggering actions periodically every time it
    reaches the number of main ticks. After firing the action, the timer restarts counting
    ticks from zero.

l   Periodical timer with embedded tick – this timer acts similar to the simple peri-
    odical timer. In addition, it can fire a second action on reaching the “embedded tick”
    count. As an example, you could realize switching on and off of a beacon light with a
    timer like this. Simply close the output at the embedded tick and open it at the main
    tick.

Timer 1 Configuring a Timer

1. To realize the beacon’s timer select „Server -> „Timer in GeViSet.

2. Add a new timer. Make sure, the Active checkbox is ticked. Name the timer Bea- conTimer and describe it as Timer to toggle a beacon on digital output 2

3. Set the Timer type to Periodical with embedded tick, the main tick to occur every 1000ms, and the embedded tick to occur every 500ms. This will generate a timer with two ticks per second and a spacing of 500 ms in between.

4. Press the Edit button On embedded tick to set the action that shall occur with every embedded tick. Chose OpenContact for the GlobalContactID 2 and give the action a cap- tion like turn of beacon.

5. For the main tick, set the action to CloseContact for the same output and the caption to turn on beacon.

6. Send the new setup to the server and switch to GeViAPI Test Client

7. You can start the timer by sending the StartTimer action. This action takes two param- eters, the TimerID and the TimerName. If you want to address a timer by its ID, just send an empty TimerName. Send StartTimer(1,"BeaconTimer")

8. In the Video/DigIO tab, you should see that output 2 toggles with a frequency of 1 Hz.

9. To stop the timer, send a StopTimer(1,"BeaconTimer") action.

NOT ICE

Hint for using StartTimer and StopTimer actions: GeViSoft first tries to evaluate the timer by TimerName and only if no name is given by ID. If you use a non existing name, the timer will not be started, even if you state the right ID. If you want to start a timer by ID, send an empty string as name (e.g. StartTimer(1,"")). Events (optional) Events can be used to control complex behavior caused by a start condition as a trigger. The GeViSoft event handling implementation allows a very flexible setup of event triggers and resulting actions. You can add events in GeViSet (Server -> Events -> Add).

Options for Events Option Description Active Events can only be triggered if marked Active Trigger Enabled If trigger is enabled, the event is restarted if the Start by condition occurs again. Repeat Actions If the Start by condition occurs, the On start action is invoked Adjust auto stop If the Start by condition occurs, the elapsed Auto stop time is reset to zero time Adjust start time If checked, the start time is adjusted on retriggering Stop before Auto stop Enabled If enabled, the event stops after the time frame set in Stop after Stop after Period of time after which the event automatically stops Auto Stop on leave of Events can be activated for certain time ranges only. If this option is valid time ranges checked, the event automatically stops if the valid time ranges are left Time range field List of all the time ranges where the event is activated. Note that if no time range is given, the event cannot be triggered! Start by List of actions that trigger the event. If multiple actions are configured, any of the actions will trigger the event on its own (logical OR operation) Stop by List of actions that terminate the event. If multiple actions are configured, any of the actions will stop the event on its own (logical OR operation) On start List of actions that are all executed on event start (logical AND) On Stop List of actions that are all executed on event termination (logical AND)

Configuring an Event 1. Here is an example how to configure an event that routes video signals based on dig- ital input -- closing of contact 3 triggers the routing of video input 3 to video output 2. After 5 seconds, the event stops and video output 2 is cleared. The event will be configured for automatic retriggering. Here are the settings: Example of an Event

2. The actions for Start by, On start, and On stop are:

    a) Start by: Contact 3 closed -> InputContact(3, true)

 b) On start: Route video In 3 to Video out 2 -> CrossSwitch(3,2,0)

c) On stop: Clear video output 2 -> ClearVideoOutput(2)

3. After the setup has been sent to the GeViServer, the event can be tested with the GeViAPI Test Client

4. If you left click input contact 3 the event is started. You will see that video input stream 3 is routed to video output 2. After 5 seconds the output is cleared again. You can also see the event being started in the communication log.

5. The event can be retriggered. If you left click input 3 again while the event is running, the 5 second auto stop time starts over again.

6. You can also start the event by sending a StartEvent message (StartEvent(ID, "MessageName")). Alarms (optional) Due to the large amount of video cameras connected to modern video surveillance systems, operators cannot observe all the streams at the same time. Moreover, only certain incidents are of interest or need action. Therefore, it is helpful that a preselection of the video material shown to the user is carried out by the system. Often special actions have to be taken if a par- ticular situation is happening. As an example assume that a parking lot with a barrier at the entrance is being monitored. The operator is supposed to open the barrier after making sure that a waiting vehicle is allowed to enter. Normally, the operator would have to watch the stream of the camera permanently and act on it. In cases like this Geutebrück systems can assist by providing alarms. Alarms are very similar to events, but offer more versatile options for customizing and defining required user interaction.

Alarm Options GeViSet offers several options for alarms.

Option Description Name Alarm name – can be used in actions Description Field for the description of an alarm Alarm ID Alarm identifier -- can be used in actions Active Alarms can only be triggered if marked Active Priority Alarms can have a priority from 1 (high) to 10(low). A higher priority alarm will displace a lower priority one if configured to be shown on the same monitor group Monitor Group Several monitors that are addressed as a group for easier admin- istration Cameras List of cameras that are relevant for the alarm. Their pictures are shown on the monitor group in case an alarm occurs Retriggerable If checked, the alarm can be retriggered by its initial activator. Popup (Retrigger) Option Description Undo acknowledge If set, the alarm has already been acknowledged and the alarm is (Retrigger) retriggered, the state will be reset to not acknowledged. User specific (Retrigger) If checked, a custom list of actions can be added which will be executed on a retrigger event of the alarm Start by Action List of actions. Any of the actions will start the alarm (logical OR) On start Action List of actions. All of the actions will be sent on start (logical AND) Acknowledge by Action List of actions. Any of the actions will acknowledge the alarm (logical OR) On acknowledge Action List of actions. All of the actions will be sent on acknowledge (logical AND) Quit by Action List of actions. Any of the actions will quit the alarm (logical OR) On quit Action List of actions. All of the actions will be sent on quit (logical AND)

Configuring an Alarm Configure an alarm for the parking lot scenario as described above. Assume that the detec- tion of a vehicle is done by a sensor on digital input 1 (vehicle is detected on close). After checking if the vehicle may enter the operator must open the barrier. To do so he acknowl- edges the alarm by pushing a button connected to digital input 2. As the barrier is controlled by digital output 1 the On acknowledge action must open this contact. After the vehicle has passed, the operator must quit the alarm by pushing a button connected to digital input 3. On quit the barrier must be closed by closing digital output 1. The parking lot is surveilled by two cameras on inputs 4 and 7. During the alarm, these must be routed to outputs 1 and 2.

1. Alarms are displayed in Monitor Groups. First define one In GeViSet.

     a) Server -> Monitor groups -> Add

     b) Set the group’s Name and Description to MonitorGroup1

     c) Add video outputs 1 and 2 to the group

 d) Leave the rest of the settings as they are

2. Add a new alarm in GeViSet: Server -> Alarms -> Add

   a) In the General tab, set Name and Description to ParkingLot

   b) Press the Monitor group button and add MonitorGroup1

   c) Add Video input 4 and Video input 7 to Cameras Alarm Settings 1 d) In the Actions tab, set the Start by action to InputContact, the GlobalContactID to 1 and ChangedTo to true. Add the Caption vehicle detected

e) Set the Acknowledge by action to InputContact, the GlobalContactID to 2 and ChangedTo to true. Add the Caption button acknowledged pressed

f) Set the On acknowledge action to OpenContact, and the GlobalContactID to 1. Add the Caption opening barrier

g) Set the Quit by action to InputContact, the GlobalContactID to 3 and ChangedTo to true. Add the Caption button quit pressed

h) Set the On quit action to CloseContact, and the GlobalContactID to 1. Add the Caption closing barrier Alarm Settings 2 3. Send the setup to the server

4. Test the new alarm in GeViAPI Test Client

   a) Clear video outputs 1 and 2 by right-clicking on them.

   b) Simulate the arrival of the vehicle by left-clicking input 1.

   c) Check if the alarm is triggered by verifying that streams 4 and 7 are displayed on monitors 1 and 2. Note that the outputs’ color changed to red which indicates an alarm feed. You should also find the AlarmStarted() action in the Communication log

   d) Acknowledge the alarm and open the barrier by left-clicking input contact 2. Make sure that this leads to the opening of output 1 and an AlarmAcked() action appearing in the log.

   e) Quit the alarm by left-clicking input contact 3. The video outputs’ color should change to green as the alarm has finished. The barrier (output 1) should have closed. Switching Video Though monitor groups date back to analogue video recording, the idea behind them comes in handy when complex situations are to be presented to operators. In modern CCTV systems most of the sources are digital ones and the viewers run as software on dedicated consoles. Nevertheless the concept of monitor groups can still be reproduced with Geutebrück’s sys- tems. The standard viewer -- GscView -- can be remote controlled to show predefined scene setups in a way similar to monitor groups.

In this chapter you will learn how to switch between two user defined GscView scenes by trig- gering a GeViSoft alarm. You will have a normal 4-by-4 scene displaying 16 channels of live footage from a GeViScope. On triggering an alarm in GeViSoft, GscView will be switched to a 2-by-2 scene displaying predetermined video channels.

Scenario Assume the following situation, which is closely related to Configuring an Alarm in chapter Alarms:

Configure an alarm for the parking lot scenario. Assume that the detection of a vehicle is done by a sensor on digital input 1 (vehicle is detected on close). After checking if the vehicle may enter, the operator must open the barrier. This happens on acknowledging the alarm by push- ing a button connected to digital input 2. As the barrier is controlled by digital output 1, the On acknowledge action must open this contact. After the vehicle has passed, the operator must quit the alarm by pushing a button connected to digital input 3. On quit the barrier have to be closed by closing digital output 1. The parking lot is surveilled by two cameras on inputs 4 and 7. During the alarm, these must be routed to outputs 1 and 2 of a 2-by-2 scene MyScene in GscView. Before and after the alarm, all 16 GeViScope channels should be displayed in a 4- by-4 scene MyStartScene in GscView. Prerequisites

1. Please setup the GeViScope SDK on your development machine if you have not done it yet.

2. Configure GscView as described in the chapter Remote control GscView by action in the GeViScope SDK documentation. Check that from GSCPLCSimulator you can switch between the scenes.

3. Configure a connection to GeViScope as described in Connection to GeViScope (optional).

4. You should now have a GscView setup with two scenes: MyStartScene and MyScene that can be remote controlled.

Configuring the Alarm

1. Configure the alarm as described in Configuring an Alarm.

2. After that, the monitor group must be mapped to a GscView Scene. GeViSoft uses the CrossSwitchWithAlarm action to route the video to the monitor group internally. There- fore these actions must be mapped to GSCViewer Control actions (e.g. VC Change Scene By Name). This is done in GeViSet by adding a new Action mapping:

   c) This changes the scene in the viewer. After that, channel 4 must be routed to viewer 1101 in the scene. For that, add another output action to the set by pressing the + button:

   d) Add the Viewer connect live action with the GeviScope alias = GEVISCOPE, the viewer = 1101, the channel = 4, and Caption = ViewerConnectLive (1101,4) a) As Input action select CrossSwitchWithAlarm with VideoInput = 4, VideoOutput = 1, and Caption = CrossSwitchWithAlarm(4,1)

b) To change the scene in the viewer there are different possibilities. You can either call VCChangeSceneByName or directly connect a live stream to a viewer number. This is done by sending a ViewerConnectLive action. Here, channel 4 must be routed to viewer 1101 in the scene. For that, add an output action to the set by press- ing the + button:

c) Add the Viewer connect live action with the GeviScope alias = GEVISCOPE, the viewer = 1101, the channel = 4, and Caption = ViewerConnectLive (1101,4)

d) The Action mapping settings window should look like this: Switching Video 1

    e) Now repeat the process for the CrossSwitchWithAlarm action for video input 7
    and viewer 1102.

 f) If executed, the mappings above will switch the scene to MyScene in GscView and route the video channels to the respective viewer. Execution of the Cross- SwitchWithAlarm actions takes place at the moment of triggering the alarm in GeV- iSoft.

3. After quitting the alarm the 4-by-4 scene MyStartScene must be reloaded in GscView, according to the scenario. This can be done as an On quit action of the GeViSet alarm:

   a) In the GeViSet Alarm settings of the ParkingLot alarm, add a VC change scene by name action to the On quit list.  b) Chose the action from GSC: Viewer action and set GeviScope alias to GEV- ISCOPE, viewer to 1000, scene to MyStartScene, and Caption to VCChan- geSceneByName(1000, MyStartScene ).

   c) Send the setup to the server.

4. Open GeViAPI Test Client and GscView to test your new configuration. On starting the alarm by left clicking input 1 in GeViSet, the scene should switch to MyScene in GscView with channel 4 being displayed in viewer 1101 and channel 7 in viewer 1102. On quitting the alarm by left clicking input 3 in GeViAPI Test Client, the scene should switch back to MyStartScene. SDK Usage Introduction It is recommended to be familiar with the GeViSoft system, the possibilities of modern video surveillance systems and video management systems in general. Before starting pro- gramming your custom GeViSoft application, you should understand the basics of action, alarm, and event handling in GeViSoft, as well as the principles of client-server network com- munication.

The following sections support you with some suggestions and hints about using the SDK interfaces.

General Hints You can always monitor the actions sent by the GeViServer or your application inside the GeViAPI Test Client. Furthermore, this application allows you to send actions and database queries. It is located in the %GEVISOFTSDKPATH%.

NOT ICE

On a development system it is recommended to start GeViServer with the startserver.bat script or from a command prompt in console mode (geviserver.exe console). This allows you to monitor the server’s output during your development.

W ARNING

Make sure to delete all objects that are created inside of DLLs. The SDK offers a DeleteObject() method for these objects.

NOT ICE Callback functions which are called out of the SDK DLLs are called from threads. These 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.

NOT ICE

Structures that are used as arguments for SDK functions should always be initialized by use of the function memset(). If the structure contains a size or structsize element, then it has to be initialized with the sizeof() function. Overview of the SDK’s Interfaces for C++ and Delphi users NOT ICE

The following paragraphs describe the SDK usage from C++ and Delphi. For a description of the .Net Interfaces see chapter C# and .Net specifics

GeViProcAPI The SDK is based on two DLLs and the corresponding headers. The GeViProcAPI.dll in con- nection with the GSCActions.dll implements all the SDK’s functionality. GSCActions.dll is used to allow the interoperability between GeViSoft and GeViScope. It makes the GeV- iScope actions available to your GeViSoft application. The corresponding headers and Pas- cal files allow you to access the functions provided by these DLLs directly.

GeViSoft is a client/server architecture and based on a central database managed by the GeViServer. This is reflected in the function calls provided by the SDK. There are four major function types declared in GeViProcAPI. They can be distinguished by their prefixes:

GeViAPI_Database_ These database functions allow you to interact with GeViSoft server directly. They are the ones you normally use for developing your application.

Example: GeViAPI_Database_Connect() is used to connect your application to the
server.

GeViAPI_DeviceClient_ The DeviceClient functions are used by the GeViIO client internally. They are usually not of interest for SDK developers.

GeViAPI_SetupClient_  The SetupClient functions are used by GeViSet to change the server setup. They are usually not of interest for SDK developers.

GeViAPI_ These are general helper functions needed for carrying out standard tasks in your appli- cation.

Example: GeViAPI_FreePointer() to release memory allocated by your objects inside
the DLL threads.

GeViProcAPI provides flat function calls for communicating with a GeViServer. To give you a more convenient and object oriented option to develop your application, another abstraction layer has been added to the SDK. This layer hides the flat function calls to the GeViProcAPI from you. Its functionality can be found in the GeViAPIClient headers and C++ files.

For a comprehensive description of these functions, please consult the GeViSoft API Doc- umentation which is delivered with the GeViSoft API SDK.

GeViAPIClient GeViAPIClient as an abstraction layer uses the flat functions provided by GeViProcAPI and encapsulates them into a CGeViAPIClient class. You can instantiate an object of this class and use its provided methods to handle the communication with the GeViServer.

For a comprehensive description of these functions, please consult the GeViSoft API Doc- umentation which is delivered with the GeViSoft API SDK. Configuring your IDE for GeViSoft Projects Visual Studio 2008, C++ 1.) Add GeViSoft’s header and cpp files to your project. (You can do this by dragging and dropping the GeViScopeSDK\Include folder and the GeV- iSoftSDK\Include folder from %GEVISOFTSDKPATH%\Examples\VS2008CPP to your project.)

2.) Add the SDK’s include files to your project by adding $(GEVISOFTSDKPATH)\Examples\VS2008CPP\GeViScopeSDK\Include and $(GEVISOFTSDKPATH)\Examples\VS2008CPP\GeViSoftSDK\Include to your Configuration Properties -> C/C++ -> General –> Additional Include Directories

3.) In the Configuration Properties -> C/C++ -> Preprocessor tab add the Preprocessor Def- inition GEVI_GSC_INCLUDE

4.) In the project’s properties TAB Configuration Properties -> Linker -> General add $(GEVISOFTSDKPATH)\Examples\VS2008CPP\GeViScopeSDK\lib and $(GEVISOFTSDKPATH)\Examples\VS2008CPP\GeViSoftSDK\lib to the Additional Library Directories of your project

5.) In the project’s properties TAB Configuration Properties -> Linker -> Input -> Additional Dependencies add GeViProcAPI.lib and GscActions.lib

6.) Make sure that your output file can find the path to GeViProcAPI and GscActions DLLs. It is recommended to set Configuration Properties -> Linker -> General -> Output File to $(GEVISOFTSDKPATH)$(ProjectName).exe or copy the DLLs into the application’s folder.

7.) Set the Configuration Properties -> Debugging -> Command to your executables name: $(GEVISOFTSDKPATH)$(TargetName)$(TargetExt)

NOT ICE

Please make sure that you select the correct configuration when setting properties. Best prac- tice is to adopt the GeViSoft settings to All Configurations

NOT ICE

Please notice that Visual Studio refers to environment variables in the form $(VAR) whereas Win- dows uses the %VAR% notation. Take this into account if you use the GEVISOFTSDKPATH var- iable.

Visual Studio 2010, C++

T h e f ol l ow i n g g u i d e i s s u i tab l e f or c on s ol e p r oj ec ts or MFC p r oj ec ts . If you w i s h to b u i l d W i n d ow s For ms or C+ + / CL I ap p l i c ati on s mor e c on f i g u r ati on s mi g h t b e n ec es s ar y.

1.) Add GeViSoft’s header and cpp files to your project. (You can do this by dragging and dropping the GeViScopeSDK\Include folder and the GeV- iSoftSDK\Include folder from %GEVISOFTSDKPATH%\Examples\VS2010CPP to your project.

2.) Add the SDK’s include files to your project by adding $(GEVISOFTSDKPATH)\Examples\VS2010CPP\GeViScopeSDK\Include and $(GEVISOFTSDKPATH)\Examples\VS2010CPP\GeViSoftSDK\Include to your Configuration Properties -> VC++ Directories -> Include Directories

3.) Add the SDK’s library files to your project by adding $(GEVISOFTSDKPATH)\Examples\VS2010CPP\GeViScopeSDK\lib and  $(GEVISOFTSDKPATH)\Examples\VS2010CPP\GeViSoftSDK\lib to your Configuration Properties -> VC++ Directories -> Library Directories

4.) In the project’s properties TAB Configuration Properties -> Linker -> Input -> Additional Dependencies add GeViProcAPI.lib and GscActions.lib

5.) Make sure that your output file can find the path to GeViProcAPI and GscActions DLLs. It is recommended to set Configuration Properties -> Linker -> General -> Output File to $(GEVISOFTSDKPATH)$(ProjectName).exe or copy the DLLs into the application’s folder.

6.) Set the Configuration Properties -> Debugging -> Command to your executables name: $(GEVISOFTSDKPATH)$(TargetName)$(TargetExt) Common Tasks This chapter describes several common tasks you might need to carry out during your devel- opment.

These are described in pseudo code and C++. For a description of the .Net API see chapter C# and .Net specifics.

Connecting to a GeViServer The first example shows you how to connect to a GeViServer by using the flat API calls from GeViProcAPI. The second and recommended method shows you how to establish the con- nection with the help of a GeViAPIClient object.

Connecting using GeViProcAPI calls

Ps e udo c ode

1. Declare a database handle

2. Encrypt the password string

3. Create a remote database object inside the DLL

4. Connect to the database object created inside the DLL

C++, di r ect GeVi Pr ocAPI cal l s:

// declare a string to hold the password hash //(32 byte + '\0') char encodedPassword[33]; // declare a database handle GeViAPI_Namespace::HGeViDatabase database;

// encode the password GeViAPI_EncodeString(encodedPassword, "masterkey", sizeof(encodedPassword));

// create a remote database object inside the DLL // to access a GeViSoft database GeViAPI_Database_Create(database, "localhost", "127.0.0.1", "sysadmin", encodedPassword, "", "");

if (database) // database successfully created
{
    // Connect functions result
    TConnectResult result;

    // Connect to the database object.
    GeViAPI_Database_Connect(database, result,
        NULL /* your callback here! */,
        NULL /* your instance here! */);
    if(result == connectOk)
        std::cout << "Connection established!";
}

Connecting using GeViAPIClient Objects (recommended)

Ps e udo c ode

1. Declare a GeViAPIClient wrapper object

2. Declare and define a connection callback function to monitor the connection progress (this function will be called from inside the DLL and return a progress state in its arguments) 3. Encrypt the clear text password

3. Create an instance of the GeViAPIClient wrapper object

4. Call the wrapper’s connect method

5. Check If the connect method returned a success

C+ + , Ge Vi API Cl i e nt c al l s :

1. Conne c ti on ha ndl i ng

// wrapper around a GeVi API client object GeViAPIClient* m_APIClient;

// declare a string to hold the password hash char encodedPassword[33]; GeViAPIClient::EncodePassword(encodedPassword, "my password", sizeof(encodedPassword) );

// create an new instance of the wrapper m_APIClient = new GeViAPIClient("My GeViServer", "127.0.0.1", "sysadmin", encodedPassword, NULL, NULL);

if(m_APIClient) { // connect to the server – ConnectProgressCB is your callback TConnectResult ConnectResult = m_APIClient->Connect(ConnectProgressCB, this); if(ConnectResult == connectOk) { // Connection successfully established // Do your work here. } }

2. Ca l l ba c k s

// Callback function for connect progress display bool __stdcall ConnectProgressCB(void* Instance, int Percentage, int Percent100) { if(Instance == NULL) { return (true) ; } // Call the callback method of your class // object's instance CYourClass* yourClass = (CYourClass*)Instance; return ( yourClass->ConnectProgress( Percentage, Percent100) ) ; }

// Your class’s callback bool CYourClass::ConnectProgress(int percentageLower, int percentageUpper) { // Do s.th., e.g. show a Progress Ctrl. return (true) ; }

Connection Monitoring GeViSoft offers methods to monitor if your connection is still established. It is advisable to monitor the connection from your application and try a reconnect if it breaks down.

You can use the sendPing()method for connection monitoring which returns true if the con- nection is still established and false if not. Best practice is to cyclically call sendPing() from a separate thread and handle the recon- nection from inside this thread if necessary.

Mon i tor i n g c on n ec ti on s i s i mp l emen ted i n th e SDK’ s examp l e CPP_ Mon -
i tor ed Con n ec ti on Cl i en t.

Monitoring a Connection Pseudo code

1. Create a separate thread inside your application if a connection should be established

2. Inside this thead, DO: a. Send a ping to the server b. IF the result of the ping is NOT true: try a reconnect c. Sleep for a given time (e.g. 10s)

3. UNTIL the connection should be terminated

C++ Exampl e

// Prerequisite: // GeViAPIClient* m_APIClient // must already be created and connected. // // Run this method inside a separate Thread! int MonitorConnection() { const int reconnectionPeriod_in_ms = 10000; bool result; while(true){  result = m_APIClient->SendPing(); if (result == false) { // TODO: notify your user here. // Try a reconnect: m_APIClient->Connect(YourConnectCallbackCB, this); } Sleep(reconnectionPeriod_in_ms); } return 0; } Message Handling After you have established your connection you are ready to exchange messages with the server.

Message Representation

There are two possible representations of messages in GeViSoft. They are either stored in a binary form or as an ASCII string. The API offers methods to convert between these two rep- resentations. These methods are defined in the MessageBase header, C++, and Pascal files.

Table of conversion methods between message representations.

CGeV- Converts an ASCII string into a CGeViMessage iMessage::ReadASCIIMessage CGeV- Converts a CGeViMessage into an ASCII string iMessage::WriteASCIIMessage CGeViMessage::ReadBinMessage Converts a binary representation of a message into a CGeV- iMessage CGeV- Converts a CGeViMessage into its binary representation iMessage::WriteBinMessage Action Messages

Creating Action Messages

You can create an action message in two ways. One is by calling its predefined action con- structor directly. The other is by converting an ASCII or binary representation into a new action object. The predefined constructors are located in the Actions header, C++, and Pas- cal files.

Actions can be considered as either being direct commands from the client to the GeViServer to control its periphery or as notifications which are sent from the server to the client to indi- cate state changes of logical or physical components. In contrast to actions, there are state queries and database queries. These are treated separately in the chapters State Queries and Database Queries.

1. Ex a m pl e f or a di r e c tl y c r e a te d Cus tom Ac ti on m e s s a ge (c on- s tr uc tor f r om Ac ti ons . h/c pp)

CGeViMessage* gevimessage = new CActCustomAction(123, "Hello GeViSoft!");

2. Ex a m pl e f or a Cus tom Ac ti on m e s s a ge c r e a te d f r om a s tr i ng

int bytesRead; std::string buffer("CustomAction(123, "Hello GeViSoft!")"); CGeViMessage* gevimessage = CGeViMessage::ReadASCIIMessage(buffer.c_str(), buffer.size(), bytesRead );

3. Exampl e for the ASCI I output of a bi nary acti on message:

// gevimessage is the binary message char* buffer; const int bufferlength = GEVI_MAXACTIONLENGTH; int numBytesReceived; buffer = new char[bufferlength]; gevimessage->WriteASCIIMessage(buffer, bufferlength, numBytesReceived); std::cout << buffer << std::endl;

4. Exampl e of creati ng a GeVi Scope Acti on Message

GeViScope messages can also be created inside GeViSoft directly. This is needed to allow the interoperability of GeViSoft and GeViScope.

The GeViScope message constructors can be found in the GscActions header. They are implemented inside the GscActions DLL. GscActions can be created by calling the CActG- scAction constructor:

CGeViMessage* gevimessage = new CActGscAction( "YourGscServerName", GscAct_CreateCustomAction(1, L"Hello GeViScope!") );

NOT ICE

Please note that “GscServerNameAlias” is the alias name you configured for the connection in GeViSet.

Sending Action Messages

The next example shows you how to send a message to the GeViSoft server. As a pre- requisite, a GeViAPIClient object must already be created and connected to the server.

C+ + Ex ampl e :

GeViAPIClient* m_APIClient //must already be created and connected /* … / CGeViMessage gevimessage = new CActCustomAction( 123, "Hello GeViSoft!"); if(gevimessage) { m_APIClient->SendMessage(gevimessage); // Don’t forget to delete objects you create inside the DLL gevimessage->DeleteObject(); }

Receiving Action Messages

This example shows you how to receive a message from GeViSoft. As a prerequisite, a GeVi- APIClient object must already be created and connected to the server. Furthermore, a data- base notification callback function must be defined. This callback function will be called from inside the GeViProcAPI DLL whenever a notification from the server is received.

Ps e udo c ode

1. Define the callback

2. Define the callback’s handler method

3. Register your callback with the GeViAPIClient connection’s object.

4.Handle the received notifications in you handler method.

C+ + Ex ampl e :

1. De f i ne the c a l l ba c k void __stdcall GeViDatabaseNotificationCB(void* Instance, TServerNotification Notification, void* Params) { if(Instance == NULL) return; // calling the callback method of yourClass object's instance. // As an example, CYourClass might be CMainWin for an MFC Application CYourClass* yourClass = (CYourClass*)Instance; yourClass->DatabaseNotification(Notification, Params); }

2. De f i ne the c a l l ba c k ’ s m e thod

void DatabaseNotification(TServerNotification Notification, void* Params) { // Check if we received a message. It might also be another // notification like a change of setup or shutdown of the server if(Notification == NFServer_NewMessage) { // create the message if possible // (the message is freed again in the main thread context) CGeViMessage* gevimessage; TMessageEntry* messageEntry = reinterpret_cast<TMessageEntry*>(Params); int noOfBytesRead = 0; gevimessage = CGeViMessage::ReadBinMessage( messageEntry->Buffer, messageEntry->Length, noOfBytesRead); if(gevimessage) { // You received a message! Now you need to handle it. // This can be done here. } else  { // Message could not be created. Handle the error here. } } else { // If we are here, we received another type of notification } }

3. Re gi s te r y our c a l l ba c k w i th the c onne c ti on obj e c t.

m_APIClient = new GeViAPIClient( ... ); if(m_APIClient) { // connect to the server TConnectResult ConnectResult = m_APIClient->Connect(ConnectProgressCB, this); if(ConnectResult == connectOk) { // Connection established! Now register your callback! m_APIClient->SetCBNotification( GeViDatabaseNotificationCB, this); } }

Disconnecting from a GeViServer When disconnecting from the server, you should unregister your notification callback and delete the GeViAPIClient object.

C+ + Ex ampl e :

void DisconnectFromServer() {  if(m_APIClient != NULL) { // Unregister the notification callback m_APIClient->SetCBNotification(NULL, NULL); m_APIClient->Disconnect(); delete m_APIClient; m_APIClient = NULL; } } State Queries State Queries are messages sent from the client to the server to get information about the state of logical and physical components of the GeViSoft system well as virtual ressources. An example of such information would be an enumeration of all the video inputs available at a GeViServer.

Creating State Queries You can create a state query by calling its predefined constructor. All the state queries’ con- structors are located in the StateQueries header, C++, and Pascal files.

State queries can then be sent with the SendStateQuery() method of the GeViAPIClient class. This method returns a CStateAnswer object with the GeViServer’s response.

CStateAnswer* StateAnswer = m_APIClient->SendStateQuery( GetFirstVideoInputQuery, INFINITE);

The second parameter of the method is the timeout for a server answer in milliseconds. By sending INFINITE, you can prevent the call from timing out.

Cr eati n g , s en d i n g , an d r ec ei vi n g s tate q u er i es i s i mp l emen ted i n th e SDK’ s exam- p l e Del p h i / CPP_ Si mp l eCl i en t.

Enumeration of all video inputs Ps e udo c ode

1. Create a state query to get the first video input (class CSQGetFirstVideoInput)

2. Send the query to the server 3. If the answer is a valid input channel then

3. REPEAT a) Get the actual channel’s information from the answer and process it as needed (e.g. print it out, store it to a list) b) Create a state query to get the next video Input (class CSQGetNextVideoInput) c) Send the query

4. UNTIL there is no more video input left

C+ + Ex ampl e :

void CMainWin::FillVideoInputsList() { if(m_APIClient == NULL) return;

// Enumerate all available video inputs with the help of state queries.
// Create a new state query that will return the first video input chan-
nel:
CStateQuery* getFirstVideoInputQuery = new CSQGetFirstVideoInput(
                   true, // show only active channels
                   true); // show only enabled channels
if(getFirstVideoInputQuery)
{
    // Send the query to the server
    CStateAnswer* stateAnswer = m_APIClient->SendStateQuery(
    getFirstVideoInputQuery,
    INFINITE); //Timeout
    // Don't forget to free the memory inside the DLL...
    getFirstVideoInputQuery->DeleteObject();
    if(stateAnswer)
    {
        // Iterate through all available video input channels

while(stateAnswer->m_AnswerKind != sak_Nothing) { // Get the channels info CSAVideoInputInfo* videoInputInfo = reinterpret_cast<CSAVideoInputInfo*>(stateAnswer); // create a video input descriptor 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); // Do something with the channel information. Here: // Add the channel information to a // CListBox lbVideoInputs int newIndex = lbVideoInputs.AddString( newVideoInput->m_Name.c_str()); lbVideoInputs.SetItemDataPtr(newIndex, newVideoInput); // Create a query to get the next input channel 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 //No more video input channel detected! break; } if(stateAnswer)  { stateAnswer->DeleteObject(); stateAnswer = NULL; } } } } Database Queries (optional) Database queries allow you to fetch datasets from the action or alarm table of the GeViSoft activity database. All the actions that have been received and all the alarm events that occurred are stored inside the database. To specify and narrow down your query results, sev- eral filter operations are available as well.

T o g et f ami l i ar w i th th e p os s i b i l i ti es of GeVi Sof t’ s d atab as e q u er i es , an d es p e- c i al l y i ts f i l ter i n g op ti on s , p l eas e h ave a l ook at th e GeVi API T es t Cl i en t’ s “ Data- b as e Vi ew er ” an d “ Datab as e Fi l ter ” tab s .

Creating Database Queries You can create a database query by calling its predefined constructor. All the database que- ries’ constructors are located in the DatabaseQueries header, C++, and Pascal files.

Database queries can then be sent with the SendDatabaseQuery() method of the GeVi- APIClient class. This method returns a CDataBaseAnswer object with the GeViServer’s response.

CDataBaseQuery* geviquery = new CDBQCreateActionQuery(0);

CDataBaseAnswer* dbAnswer = m_APIClient->SendDatabaseQuery(geviquery, INFI- NITE);

The second parameter of the method is the timeout for a server answer in milliseconds. By sending INFINITE, you can prevent the call from timing out.

Database Query Session Handling Action sending and state querying did not need any form of session handling. This is different for database querying. Usually you want to collect several records that are connected in some form, e.g. applying the same filter set to subsequent queries. To signal the database engine that your queries are associated, you pass a unique query handle with them. The query handle is the result you receive from a CDBQCreateActionQuery or CDBQCrea- teAlarmQuery. Therefore these queries are the first you send when interacting with the data- base.

C+ + Ex ampl e f or ge tti ng a que r y handl e :

// Create a new Action Query CDataBaseQuery* geviquery = new CDBQCreateActionQuery(0);

// Send the Action Query to the server CDataBaseAnswer* dbanswer = m_APIClient->SendDatabaseQuery(geviquery, INFI- NITE); geviquery->DeleteObject();

if (dbanswer->m_AnswerCode == dbac_QueryHandle) { // Extract the query handle from the answer CDBAQueryHandle* handle = reinterpret_cast<CDBAQueryHandle*>(dbanswer); } Iterating over Database Records You can send a group of associated database queries after having obtained the query handle. Please note that the GeViSoft architecture always returns one single answer for every query. As a consequence, you might need to issue several database queries consecutively to get your desired pieces of information.

This can be illustrated by an example database query. Imagine you want to retrieve the two latest actions inside the database:

Ex ampl e : Re tr i e v i ng of the tw o l ate s t ac ti ons i ns i de the data- base

Ps e udo c ode

1. Create a new CDBQCreateActionQuery

2. Send the query to GeViServer and retrieve the handle from the answer

3. Create a new CDBQGetLast query with the handle as the argument

4. Send the query and fetch the latest action as an answer

5. Extract the latest action’s primary key from the answer

6. Create a new CDBQGetPrev query with the handle and the latest action’s primary key as an argument

7. Send the query and fetch the second latest action as an answer

C++: // Declare a query handle CDBAQueryHandle* handle; __int64 primaryKey;

// Create a new Action Query CDataBaseQuery* geviquery = new CDBQCreateActionQuery(0);

// Send the Action Query to the server CDataBaseAnswer* dbanswer = m_APIClient->SendDatabaseQuery(geviquery, INFI- NITE); geviquery->DeleteObject();

if (dbanswer->m_AnswerCode == dbac_QueryHandle) { // Extract the query hande from the answer handle = reinterpret_cast<CDBAQueryHandle*>(dbanswer); }

// Create a database query for the latest action entry CDataBaseQuery* getEntry = new CDBQGetLast(handle->m_Handle);

// Send the query to the GeViServer dbanswer = m_APIClient->SendDatabaseQuery(getEntry, INFINITE); getEntry->DeleteObject();

// Check if an action entry is in the database if (dbanswer->m_AnswerCode == dbac_ActionEntry) { // Do s.th. with the answer here... // Get the primary key which is used to // address the records internally primaryKey = reinterpret_cast<CDBAActionEntry*>(dbanswer)->m_PK; } //TODO: Add error handling if no action is in the database

//Create a database query to get the second latest action entry getEntry = new CDBQGetPrev(handle->m_Handle, primaryKey); // Send the query to the GeViServer dbanswer = m_APIClient->SendDatabaseQuery(getEntry, INFINITE); getEntry->DeleteObject(); // Check if an action entry is in the database if (dbanswer->m_AnswerCode == dbac_ActionEntry) { // Do s.th. with the answer here... } //TODO: Add error handling if no action is in the database dbanswer->DeleteObject(); Filtering Database Queries GeViSoft supports various filters allowing you to specify your queries in a more precise way. For example, you can narrow down your search to certain action types or senders. All the available filters are declared in the DatabaseQueries header file.

To set the filtering on the GeViServer, you have to send a database query for every filter ele- ment after you have obtained the query handle. You can monitor the processing of the queries inside the GeViAPI Test Client. Here is a screenshot of a database query sequence which sets a filter for the action type name CrossSwitch. The message setting the filter is highlighted. The filter has been defined in the Database Filter tab of the GeViAPI Test Client. Afterwards, the fetch operation was started from the Database Viewer tab.

Composing Filtered Queries

In this paragraph you will learn how to compose simple filters first and finally extent the exam- ple from above (Iterating over Database Records) with a filter that will only return CustomAction messages with certain primary keys.

Prerequisite for a test on your system is that there are CrossSwitch, CustomAction, and sev- eral other action type entries stored inside your database. To populate your database with these, you can send them with the GeViAPI Test Client. Doing a fetch in the Database Vie- wer’s tab allows you to verify that they are stored correctly afterwards.

Example Filters

Example for a filter that will only return CustomActions:

CDataBaseFilter* myActionNameFilter = new CDBFTypeName(handle->m_Handle, "CustomAction", dbc_LIKE);

After creating your filters, you can send them with GeViAPIClients SendDatabaseQuery method.

CDataBaseAnswer* dbanswer = m_APIClient->SendDatabaseQuery(myActionNameFilter, INFINITE);

Make sure to verify that the answer code is dbac_DBOk and to call the DeleteObject method for your filter after sending it.

Composing complex filters:

You can compose a complex filter by sending a sequence of multiple single filters to the data- base. These filters will then be treated as a conjunction (logical AND) by GeViServer.

Here is an example for a complex filter that only returns actions with primary keys between 500 and 600. This filter has to be composed by sending two simple filters sequentially:

CDataBaseFilter* myMinFilter = new CDBFPK_GrtEqu(handle->m_Handle, 500); CDataBaseFilter* myMaxFilter = new CDBFPK_LowEqu(handle->m_Handle, 600);

Complete Example of a Filtered Database Query

The example Iterating over Database Records will be extended to filter for CustomActions with a primary key between 500 and 600 in this paragraph. To achieve this, the filter messages have to be sent directly after retrieving the database handle. The filters are created in a method called setActionFilter. This message is then called after obtaining the database handle.

Example filtering method:

void setActionFilter(CDBAQueryHandle* handle) { // Create a vector with your filter messages std::vector<CDataBaseFilter*> filterList; filterList.push_back( new CDBFPK_GrtEqu(handle->m_Handle, 500) ); filterList.push_back( new CDBFPK_LowEqu(handle->m_Handle, 600) ); filterList.push_back( new CDBFTypeName(handle->m_Handle, "CustomAction", dbc_LIKE) );

//Send the filters
for (vector<CDataBaseFilter*>::iterator it =
                          filterList.begin(); it != filterList.end();
                          it++)
{
    CDataBaseAnswer* dbanswer = m_APIClient->SendDatabaseQuery(*it, INFI-
    NITE);
    if (dbanswer->m_AnswerCode != dbac_DBOk)
    {
        // Do error handling here!
        (*it)->DeleteObject();
        return;
    }

 (*it)->DeleteObject(); } }

Now you can call that method in your example from above:

/* ... / CDataBaseAnswer dbanswer = m_APIClient->SendDatabaseQuery( geviquery, INFINITE); geviquery->DeleteObject();

if (dbanswer->m_AnswerCode == dbac_QueryHandle) { // Extract the query hande from the answer handle = reinterpret_cast<CDBAQueryHandle*>(dbanswer);

   //Send Filter here
   setActionFilter(handle);

} /* ... */

As a result, you should see the two latest CustomAction records with a primary key between 500 and 600. If you do not get any results, you need to adopt the filtering criteria to match rec- ords in your database.

Datab as e q u er i es an d f i l ter i n g i s i mp l emen ted i n th e SDK’ s examp l e Del p h i / CPP_
Si mp l eDatab as eCl i en t.

C# and .Net specifics This chapter deals with the GeViSoft SDKs .Net capabilities and specifics. It describes the architecture of the wrappers and the specifics of the usage.

Architecture The GeViSoft SDK is delivered with a .Net-Wrapper, allowing you to design applications in C# or other .Net languages. The Geutebrueck.GeViSoftSDKNET.Wrapper.dll encapsulates all the native GeViProcAPI.dll calls. Additionally, the GscActionsNet.dll from the GeV- iScopeSDK is needed to allow for GeViScope interoperability. This wrapper encapsulates the GscActions.dll which itself uses the GscDBI.dll. Diagram of the GeViSoft .Net wrappers

Configuring your IDE for GeViSoft .Net Projects

Visual Studio 2008, C#

1.) Add the .Net wrappers to your project’s references. (You can do this by right-clicking on References in your Solution Explorer. After pressing Add Reference browse to your %GEVISOFTSDKPATH% and add GeViProcAPINET_2_0.dll. If you plan to use GeViScope Actions also add GscActionsNET_2_0.dll. 2.) Change the platform settings to generate X86 code if it is not already set. In the Configuration Manager select Platform -> New ->X86 and use this platform for the Debug and Release configurations. 3.) Change the Output path of your project. The application needs the following files in its path: GeviProcAPI.dll, GscDBI.dll, GscAc- tions.dll, GeViProcAPINET_X_Y.dll, and GscActionsNET_X_Y.dll. All these files are in your %GEVISOFTSDKPATH%, so the output path to c:\gevisoft.

To change the Output path, either right-click on your project in Solution Explorer and press Properties or choose Project -> ProjectName Properties from the menu. Then select the Build tab and set your Output path. 4.) Add the required using directives to your project’s source files. For a project that only uses GeViSoft actions, you need at least.

GEUTEBRUECK.GeViSoftSDKNET.ActionsWrapper

as well as

GEUTEBRUECK.GeViSoftSDKNET.ActionsWrapper.ActionDispatcher

and, additionally for actions from every action class you use,

GEUTEBRUECK.GeViSoftSDKNET.ActionsWrapper.YourActionClass

If you also want to use GeViScope actions, make sure to include

GEUTEBRUECK.GeViScope.Wrapper.Actions.ActionDispatcher

and

GEUTEBRUECK.GeViScope.Wrapper.Actions.YourActionClass

You can find descriptions of the actions and their respective action classes in the API doc- umentation or by inspecting the assemblies with the Object Browser.

Visual Studio 2010, C#

Configure your project as described in paragraph Visual Studio 2008, C#

Common Tasks with C# This chapter describes several common tasks you might need to carry out during your devel- opment. The tasks are described in pseudo code and C#. Connecting to a GeViServer

This paragraph shows you what tasks are needed for connecting to a GeViServer.

Connecting

Pseudo Code

    1. Implement the connect callback method
    2. Create an instance of a database connection object
    3. Call the create() method of your database connection object
    4. Add your callback delegate method to the invocation list
    5. Register your callback method
    6. Call the connect method of your database connection object

C#

// This is the connect progress callback method. // It is called from within GeViSoft during the connection progress void myConnectProgress(object sender, GeViSoftConnectProgressEventArgs e) { Console.WriteLine("Connecting... {0} of {1}", e.Progress, e.Effort); }

// myDB is the database object that encapsulates // all GeViSoft interaction. GeViDatabase myDB = new GeViDatabase();

// Set the server name, user name and password of your // GeViSoft connection myDb.Create("localhost", "sysadmin", "masterkey"); // Add your callback delegate to the invocation list myDb.ConnectProgress += new GeViSoftConnectProgressEventHandler( myConnectProgress);

// Register the callback inside GeViSoft myDb.RegisterCallback();

// Now you can connect to the GeViSoft Server... myDB.Connect();

A straightforward implementation for establishing a connection can be found in example CS_ ConsoleClient.

Message Handling

After having established the connection, you are ready to exchange messages and actions with the server.

Creating and Sending of GeViSoft Messages

There are two approaches that can be taken to create and send GeViSoft messages. You can either create a message instance by calling its constructor and then send this instance, or you can directly send a string representation of a message without instantiating it first.

Exampl e 1 – Creati ng an i nstance of a message and sendi ng i t after- wards // Create a CrossSwitch Action and switch // input 7 to output 1 GeViAct_CrossSwitch myAction = new GeViAct_CrossSwitch( 7, 1, GeViTSwitchMode.sm_Normal);

// Send the action myDB.SendMessage(myAction);

NOT ICE Make sure you have included your action’s corresponding action class namespace in your using directives. See Configuring your IDE for GeViSoft.Net Projects -> VS2008, C#

Exampl e 2 – Di rectl y sendi ng a message from a stri ng

myDB.SendMessage("CrossSwitch(7,1,0)");

Receiving of GeViSoft Actions

GeViSoft action dispatching is event based. Internally, for every action that is received, an event is fired. If you want to process certain GeViSoft action messages inside your appli- cation, you can register an event handler for this particular action. The event handler is called whenever a new action of that type is received.

If you want to process CrossSwitch actions in your application, you can proceed as shown in this example.

Pseudo code: 1. Implement a method that is called whenever the event is fired (action received) 2. Register your method as an event handler for the particular action 3. Register your event handler inside the GeViSoft connection object.

C#:

// Method to be called on receiving a CrossSwitch Action void myDB_ReceivedCrossSwitch(object sender, GeViAct_CrossSwitchEventArgs e) {  String receivedMessage = "CrossSwitch(" + e.aVideoInput + ", " + e.aVideoOutput + ", " + e.aSwitchMode + ")"; }

// Event handler for CrossSwitch Actions myDB.ReceivedCrossSwitch += new GeViAct_CrossSwitchEventHandler(myDB_ReceivedCrossSwitch);

// Don’t forget to register the handler inside the GeViSoft connection object myDB.RegisterCallback();

Receiving of GeViSoft Notifications

Besides actions, GeViSoft also sends messages regarding the server status, the database notifications. You can receive these notifications by registering a GeV- iSoftDatabaseNotificationEventHandler. The procedure is similar to the action subscription as described above.

Here is an example:

void myDB_DatabaseNotification(object sender, GeViSoftDatabaseNotificationEventArgs e) { switch (e.ServerNotificationType) { case GeViServerNotification.NFServer_Disconnected: // ("Disconnected from Server"); break; case GeViServerNotification.NFServer_GoingShutdown: // ("Server is shutting down"); break;  case GeViServerNotification.NFServer_SetupModified: // ("Server setup has been modified"); break; case GeViServerNotification.NFServer_NewMessage: // An “ordinary” action has been received. // Handle this action in a separate Event- Handler // (like myDB_ReceivedCrossSwitchAction) break; } }

// You register the handler as described before myDB.DatabaseNotification += new GeViSoftDatabaseNotificationEventHandler(myDB_DatabaseNotification); myDB.RegisterCallback();

NOT ICE

Please note that the e.ServerNotificationType equals GeViServerNotification.NFServer_New-
Message with every GeViSoft action that is received, regardless if you already subscribed for it
with another event handler.

Handling of GeViScope Actions

You can also send GeViScope actions from your GeViSoft application. Sending GeViScope actions is very similar to sending GeViSoft actions. The only difference is that you need to add the GeViScope server alias to the SendMessage() method’s parameters.

Sending GeViScope Actions

Example – sending a GeViScope message: Prerequisite:

    1. Connection to GeViScope has been configured with GeViSet
    2. The appropriate namespaces are included

// Example for GeViScope namespace needed to handle // a GeViScope Custom Action using GEUTEBRUECK.GeViScope.Wrapper.Actions; using GEUTEBRUECK.GeViScope.Wrapper.Actions.SystemActions;

// Create the GeViScope action GscAct_CustomAction myGscAction = new GscAct_CustomAction(23, "Hello GeViScope!");

// Send the Action to the “GeViScope_Alias” server myDB.SendMessage("GEVISCOPE_ALIAS", myGscAction);

Receiving GeViScope Actions

Receiving GeViScope actions is a little different from handling GeViSoft actions. Due to archi- tectural constraints, whenever a GeViSoft Action arrives, it is encapsulated into a special GeViSoft action. This action is called GscAction. The GscAction itself is retrieved like any other GeViSoft action by implementing a method that processes the GscAction and that is added as an event handler for receiving the GscAc- tion. This method receives the original GeViScope Action embedded into its EventArgs whenever it is called. Normally you then would have to identify and parse the GeViScope action and handle it as needed by hand. For your convenience, the Geutebrueck SDKs provide you with a dispatcher that can simplify that task: There is a Dispatcher method for GeViScope actions that works very similar to the dis- patching mechanism used by GeViSoft. You can simply add event handlers for the GeV- iScope actions you are interested in and process them in there. Example – Receiving and Dispatching GeViScope Actions inside GeViSoft:

Pseudo Code: 1. Create an instance of the GscActionDispatcher class that will dispatch the GeV- iScope actions to your handlers 2. Create an event handler that receives the GeViSoft GscAction. Inside this event handler, call the dispatch method of your GscActionDispatcher instance for every received GscAction. 3. Register the GeViSoft GscAction event handler with your GeViSoft database con- nection object. 4. Create an event handler method for any GeViScope action you want to process 5. Register your GeViScope actions event handler at the dispatcher.

C#:

// Create an instance of the GscActionDispatcher class GscActionDispatcher myGscDispatcher = new GscActionDispatcher();

// GscAction event handler that dispatches the GscAction void myDB_ReceivedGscAction(object sender, GeViAct_GscActionEventArgs e) { myGscDispatcher.Dispatch(e.m_GscAction); }

// Add the handler for GscAction (this is called for any newly received GeV- iScope action) myDB.ReceivedGscAction += new GeViAct_GscActionEventHandler(myDB_ReceivedGscAction);

// Don't forget to register the callbacks! myDB.RegisterCallback();

// Event handler method for the GeViScope Action void myGscDispatcher_OnCustomAction(object sender, GscAct_Cus- tomActionEventArgs e) { Console.WriteLine "Received GEVISCOPE CustomAction("+ e.aInt + ", " + e.aString + ")"); }

// Register the GeViScope CustomAction event handler with the dispatcher myGscDispatcher.OnCustomAction += new GscAct_CustomActionEventHandler(myGscDispatcher_OnCustomAction);

NOT ICE

You can find a complete example application that sends and receives GeViScope actions in CS_
SimpleGscActionClient.

State Queries in C#

This paragraph describes how you can send and receive State Queries from within C#. For an introduction to State Queries in general see chapter SDK-Usage->State Queries.

Creating and Sending State Queries

You can create State Queries with their respective constructors and send them afterwards by calling the SendQuery() method of your database connection instance. The SendQuery() method returns the GeViSoft State Answer via an out parameter.

// myAnswer is filled by the SendQuery() method // with the State Answer. GeViMessage myAnswer; // This is your query GeViMessage myQuery = new GeViSQ_GetFirstVideoInput(true, true); // Send the query myDB.SendQuery(myQuery, out myAnswer); if (myAnswer is GeViSA_VideoInputInfo) { // Do something with my answer here... }

Setting the State Query Timeout

The method SendQuery() blocks until the database answer is retrieved from the GeViServer. If the server does not answer, this leads to a deadlock. A maximum timeout timer for the SendQuery exists to prevent waiting endlessly for a database answer. By default, the timeout is set to 3000 ms. You can change this timeout globally by calling the SetQueryTimeoutInMs () method of your database connection instance.

Example – Setting the SendQuery timeout to one second:

myDB.SetQueryTimeoutInMs(1000);

Enumeration of all video inputs

Pseudo code

1. Create a state query to get the first video input (class GeViSQ_GetFirstVideoInput)

2. Send the query to the server

3. If the answer is a valid input channel then

4. REPEAT a) Get the actual channel’s information from the answer and process it as needed (e.g. print it out, store it to a list) b) Create a state query to get the next video Input (class GeViSQ_  GetNextVideoInput) c) Send the query

5. UNTIL there is no more video input left

C# Example:

private List<GeViSA_VideoInputInfo> getVideoInputsList() { List<GeViSA_VideoInputInfo> myVideoInputs = new List<GeViSA_VideoInputInfo>(0); if (myDB != null) { GeViMessage myAnswer; myDB.SendQuery(new GeViSQ_GetFirstVideoInput(true, true), out myAnswer); while (myAnswer is GeViSA_VideoInputInfo) { int tempID = (myAnswer as GeViSA_VideoInputInfo).sG- lobalID; myVideoInputs.Add(myAnswer as GeViSA_VideoInputInfo); myDB.SendQuery( new GeViSQ_GetNextVideoInput(true, true, tem- pID), out myAnswer); } } return myVideoInputs; }

NOT ICE

You can find a complete example application that sends State Queries and receives State Actions in CS_SimpleClient. This example shows you how to enumerate video in- and outputs as well as digital IO. Supported Development Platforms The SDK is designed for and tested to work with the following development environments:

l   Microsoft Visual Studio 2008, C++
l   Microsoft Visual Studio 2010, C++
l   Microsoft Visual Studio 2008, C#
l   Microsoft Visual Studio 2010, C#
l   Embarcadero RAD Studio XE, Delphi

Examples The SDK is shipped with various examples showing you how to implement common tasks. The examples are grouped by functionality and platform.

By Functionality Connecting/disconnecting to GeViServer l CPP_SimpleActionClient (VS2008/VS2010, C++) l CPP_SimpleClient (VS2008/VS2010, C++) l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l CPP_MonitoredConnectionClient (VS2008/VS2010, C++) l CPP_ConsoleClient (VS2008/VS2010, C++) l CS_SimpleActionClient (VS2008/VS2010, C#) l CS_SimpleClient (VS2008/VS2010, C#) l CS_SimpleDatabaseClient (VS2008/VS2010, C#) l CS_SimpleGscActionClient (VS2008/VS2010, C#) l Delphi _SimpleActionClient (RAD Studio XE) l Delphi _SimpleClient (RAD Studio XE) l Delphi _SimpleDatabaseClient (RAD Studio XE) l Delphi _ConsoleClient(RAD Studio XE)

Monitoring a GeViSoft connection l CPP_MonitoredConnectionClient (VS2008/VS2010, C++)

Automatically reconnecting a GeViSoft connection on loss l CPP_MonitoredConnectionClient (VS2008/VS2010, C++)

Sending/receiving of GeViSoft actions/messages l CPP_SimpleActionClient (VS2008/VS2010, C++) l CPP_MonitoredConnectionClient (VS2008/VS2010, C++) l CPP_SimpleClient (VS2008/VS2010, C++)  l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l CPP_ConsoleClient (VS2008/VS2010, C++) l CS_SimpleActionClient (VS2008/VS2010, C#) l CS_SimpleClient (VS2008/VS2010, C#) l CS_SimpleDatabaseClient (VS2008/VS2010, C#) l CS_ConsoleClient (VS2008/VS2010, C#) l Delphi _SimpleActionClient (RAD Studio XE) l Delphi _SimpleClient (RAD Studio XE) l Delphi _SimpleDatabaseClient (RAD Studio XE) l Delphi _ConsoleClient(RAD Studio XE)

Sending/receiving of GeViScope actions/messages l CS_SimpleGscActionClient (VS2008/VS2010, C#)

Receiving and dispatching of server notifications l CPP_SimpleActionClient (VS2008/VS2010, C++) l CPP_MonitoredConnectionClient (VS2008/VS2010, C++) l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l CPP_ConsoleClient (VS2008/VS2010, C++) l CS_SimpleActionClient (VS2008/VS2010, C#) l CS_SimpleClient (VS2008/VS2010, C#) l CS_SimpleDatabaseClient (VS2008/VS2010, C#) l CS_SimpleGscActionClient (VS2008/VS2010, C#) l CS_ConsoleClient (VS2008/VS2010, C#) l Delphi _SimpleActionClient (RAD Studio XE) l Delphi _SimpleClient (RAD Studio XE)

Converting between ASCII and binary representation of messages l CPP_SimpleActionClient (VS2008/VS2010, C++) l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l CPP_ConsoleClient (VS2008/VS2010, C++) l Delphi _SimpleActionClient (RAD Studio XE) l Delphi _SimpleDatabaseClient (RAD Studio XE) l Delphi _ConsoleClient(RAD Studio XE) Sending/receiving state queries and answers l CPP_SimpleClient (VS2008/VS2010, C++) l CS_SimpleGscActionClient (VS2008/VS2010, C#) l Delphi _SimpleClient (RAD Studio XE)

Enumeration of video input and output channels l CPP_SimpleClient (VS2008/VS2010, C++)

l CS_SimpleClient (VS2008/VS2010, C#) l Delphi _SimpleClient (RAD Studio XE)

Enumeration of digital IO contacts l CPP_SimpleClient (VS 2008/VS2010, C++) l CS_SimpleClient (VS2008/VS2010, C#) l Delphi _SimpleClient (RAD Studio XE)

Sending database action queries l CPP_SimpleDatabaseClient (VS 2008/VS2010, C++) l CS_SimpleDatabaseClient (VS2008/VS2010, C#) l Delphi _SimpleDatabaseClient (RAD Studio XE)

Sending database alarm queries l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l CS_SimpleDatabaseClient (VS2008/VS2010, C#) l Delphi _SimpleDatabaseClient (RAD Studio XE)

Navigating through database entries l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l CS_SimpleDatabaseClient (VS2008/VS2010, C#) l Delphi _SimpleDatabaseClient (RAD Studio XE)

Converting database answers from binary to ASCII representation l CPP_SimpleDatabaseClient (VS2008/VS2010, C++) l Delphi _SimpleDatabaseClient (RAD Studio XE) Building GeViSoft messages from user input l CPP_ConsoleClient (VS2008/VS2010, C++) l CS_ConsoleClient (VS2008/VS2010, C#) l Delphi _ConsoleClient(RAD Studio XE) By Platform Microsoft Visual Studio 2008/2010, C++, MFC CPP_SimpleActionClient l Connecting/disconnecting to GeViServer l Sending/receiving of actions

l Receiving and dispatching of server notifications l Converting between ASCII and binary representation of messages.

CPP_MonitoredConnectionClient l Connecting/disconnecting to GeViServer l Sending/receiving of actions l Receiving and dispatching of server notifications l Converting between ASCII and binary representation of messages l Monitoring a GeViSoft connection l Automatically reconnecting a GeViSoft connection on loss

CPP_SimpleClient l Connecting/disconnecting to GeViServer l Sending/receiving state queries and answers l Sending/receiving of actions l Enumeration of video input and output channels l Enumeration of digital IO contacts l Receiving and dispatching of server notifications

CPP_SimpleDatabaseClient l Connecting/disconnecting to GeViServer l Sending database action queries l Sending database alarm queries l Navigating through database entries l Receiving database entries l Converting database answers from binary to ASCII representation Microsoft Visual Studio 2008/2010, C++, Console CPP_ConsoleClient l Connecting/disconnecting to GeViServer l Building GeViSoft messages from user input l Receiving and displaying messages l Converting between ASCII and binary representation of messages

Microsoft Visual Studio 2008/2010, C# WinForms CS_SimpleActionClient l Connecting/disconnecting to GeViServer l Sending/receiving of actions l Receiving and dispatching of server notifications

CS_SimpleClient l Connecting/disconnecting to GeViServer l Sending/receiving state queries and answers l Sending/receiving of actions l Enumeration of video input and output channels l Enumeration of digital IO contacts l Receiving and dispatching of server notifications

CS_SimpleDatabaseClient l Connecting/disconnecting to GeViServer l Sending database action queries l Sending database alarm queries l Navigating through database entries l Receiving database entries

CS_SimpleGscActionClient l Connecting/disconnecting to GeViServer l Creating/Dispatching GeViScope Actions  l Creating GeViScope Action Event Handlers l Adding/Removing Event Handlers on runtime

Microsoft Visual Studio 2008/2010, C#, Console CS_ConsoleClient l Connecting/disconnecting to GeViServer

l Building GeViSoft messages from user input l Receiving and displaying messages l Composing GeViSoft actions from strings

Embarcadero RAD Studio XE, Delphi, VCL Delphi_SimpleActionClient l Connecting/disconnecting to GeViServer l Sending/receiving of actions l Receiving and dispatching of server notifications l Converting between ASCII and binary representation of messages.

Delphi_SimpleClient l Connecting/disconnecting to GeViServer l Sending/receiving state queries and answers l Sending/receiving of actions l Enumeration of video input and output channels l Enumeration of digital IO contacts l Usage of video input and output descriptors l Usage of digital contact input and output descriptors l Receiving and dispatching of server notifications

Delphi_SimpleDatabaseClient l Connecting/disconnecting to GeViServer l Sending database action queries l Sending database alarm queries  l Navigating through database entries l Receiving database entries l Converting database answers from binary to ASCII representation

Embarcadero RAD Studio XE, Delphi, Console Delphi_ConsoleClient l Connecting/disconnecting to GeViServer l Building GeViSoft messages from user input l Receiving and displaying messages l Converting between ASCII and binary representation of messages