c5617m-a

7/18/2019 C5617M-A

http://slidepdf.com/reader/full/c5617m-a 1/125

Pelco API SDK 2.1.2 Programming Guide

C5617M-A

7/18/2019 C5617M-A


617M-A

7/18/2019 C5617M-A


C5617M-A | Co

Contents

Chapter 1: Introduction...............................................................................7Getting Started with the Pelco SDK.....................................................................................................................7General Requirements.......................................................................................................................................... 8

Installing the Pelco SDK.......................................................................................................................................9System Environment Settings for the Pelco SDK..............................................................................................10

Including Required SDK Components For Your Application..............................................................................10Setting Up Sample Projects............................................................................................................................... 10

Registering the ActiveX Control............................................................................................................. 10

Setting Up the Working Directory...........................................................................................................11Adding References to Managed Libraries for C#...................................................................................14

Chapter 2: Displaying and Controlling Video Streams..........................17Overview..............................................................................................................................................................17Initializing the Pelco API Viewer (C++)..............................................................................................................17

Initializing the Pelco API Viewer (C#)................................................................................................................18

Setting Size and Position of Video Display Area...............................................................................................19Querying an RTP Stream...................................................................................................................................19

Opening, Playing, and Displaying a Live or Playback RTP Stream.................................................................. 20Opening, Playing, and Displaying an RTSP Stream..........................................................................................21

Forward Playback of RTP and RTSP Streams..................................................................................................22

Reverse Playback of RTP and RTSP Streams................................................................................................. 22Fast Forward / Reverse Playback of RTP and RTSP Streams.........................................................................23

Pausing RTP and RTSP Playback Streams......................................................................................................23Frame Forward Playback of the RTP Stream....................................................................................................24

Frame Reverse Playback of the RTP Stream................................................................................................... 24

Resuming the RTP or RTSP Stream from a Paused State...............................................................................24Stopping the RTP and RTSP Stream................................................................................................................24

Setting Audio Volume of a Live or Playback RTP stream.................................................................................25Displaying Analytic Events for an RTP Stream................................................................................................. 25

Displaying Motion Events for an RTP Stream................................................................................................... 25Displaying a Timestamp Overlay for RTP and RTSP Streams......................................................................... 25

Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams...................................................27

Pan, Tilt, Zoom (PTZ) Control for RTP Stream Using PelcoAPIViewer.............................................................27

Chapter 3: Pan, Tilt, Zoom (PTZ) Control............................................... 29Overview..............................................................................................................................................................29

Initializing the PTZ Control Wrapper.................................................................................................................. 29

Continuous Panning............................................................................................................................................30Continuous Tilting............................................................................................................................................... 31

Continuous Diagonal Movement.........................................................................................................................31

Stopping Continuous Movement.........................................................................................................................32Enabling Continuous Pan/Tilt/Move and Zoom APIs via UDP Instead of TCP..................................................32

Panning to a Specific Position........................................................................................................................... 33Tilting to a Specific Position...............................................................................................................................33

Moving to a Specific Position.............................................................................................................................34Moving to a Position Relative to the Current Location...................................................................................... 34

Getting the Camera’s Current Position.............................................................................................................. 34Managing the Magnification (Zoom) Value........................................................................................................ 35

Managing the Focus Value.................................................................................................................................36

Iris Control...........................................................................................................................................................36Scripting...............................................................................................................................................................37

Creating a Preset................................................................................................................................................38

7/18/2019 C5617M-A


ntents | C5617M-A

Updating an Existing Preset...............................................................................................................................38Creating a Pattern.............................................................................................................................................. 38

Going to an Existing Preset............................................................................................................................... 39

Removing an Existing Preset............................................................................................................................. 39Updating an Existing Pattern..............................................................................................................................40

Executing an Existing Pattern............................................................................................................................ 40Stopping a Pattern Currently Being Executed................................................................................................... 40

Chapter 4: Events and Alarms.................................................................41Overview..............................................................................................................................................................41

Where Does the Pelco SDK Fit?........................................................................................................... 41Event Arbiter Library...............................................................................................................................41

Event Manager........................................................................................................................................42Event Arbiter Library Compared to Event Manager...........................................................................................42

Creating an Event Agent....................................................................................................................................43

Returning the Event Subscription URL.............................................................................................................. 44Initializing the Event Arbiter Library................................................................................................................... 45

Initializing the Event Arbiter Library for C++..........................................................................................45Initializing the Event Arbiter Library for C#............................................................................................45

Initializing the Event Manager............................................................................................................................46

Device or Service Specific Subscriptions...........................................................................................................47

Using the Event Arbiter Library to Subscribe Using the Device’s IP Address........................................47Using the Event Arbiter Library to Subscribe Using the Event Subscription URL..................................47Using the Event Arbiter Library to Subscribe to All Instances of a Service........................................... 48

Using the Event Arbiter Library to Unsubscribe from a Service............................................................ 48Mass Subscriptions by Category........................................................................................................................49

Using the Event Manager to Subscribe to All Services.........................................................................49

Using the Event Manager to Unsubscribe from All Services.................................................................50Handling Incoming Events..................................................................................................................................50

Polling Events..................................................................................................................................................... 53

Chapter 5: Extracting Audio and Video Metadata..................................55Extracting Audio and Video Metadata................................................................................................................55Motion Detection Metadata.................................................................................................................................56

Pelco Analytics Drawing Primitives.................................................................................................................... 56Timestamps......................................................................................................................................................... 56

Getting Started....................................................................................................................................................57

Initializing the Metadata Parser Class................................................................................................................57Creating a Metadata Renderer Class................................................................................................................ 58

Retrieving the Current Timestamp Metadata..................................................................................................... 58Motion Detection Metadata.................................................................................................................................59

Retrieving Motion Detection Metadata................................................................................................... 59Rendering Motion Detection Metadata...................................................................................................59

Drawing Metadata...............................................................................................................................................60

Retrieving Drawing Metadata................................................................................................................. 60Rendering Drawing Metadata................................................................................................................. 60

Chapter 6: Exporting Video......................................................................63Overview..............................................................................................................................................................63

Where Does the Pelco SDK Fit?........................................................................................................... 63Custom Application Development.......................................................................................................................63

Getting Started....................................................................................................................................................64Initializing the Exporter....................................................................................................................................... 64

Setting Up Overlay Data on Video to Be Exported........................................................................................... 65

OverlayData Parameters.........................................................................................................................65Resetting Overlay Data...........................................................................................................................69

Exporting Video...................................................................................................................................................69Exporting a Single Video Clip................................................................................................................ 69

7/18/2019 C5617M-A


C5617M-A | Co

Exporting Video Using a Playlist (PPX)................................................................................................. 70Stitching Multiple Clips into a Single Video Export................................................................................71

Polling a Video Export........................................................................................................................................73

Stopping a Video Export.................................................................................................................................... 74Exporting A JPEG Snapshot.............................................................................................................................. 74

Chapter 7: Web Service Proxies..............................................................75Web Service Proxies.......................................................................................................................................... 75General Usage.................................................................................................................................................... 75

Chapter 8: Discovery................................................................................ 77Device and Service Discovery Overview........................................................................................................... 77

Initializing the Pelco SDK System Manager Wrapper........................................................................................78Automatically Determining the System Manager’s IP Address and Port Number..............................................79

Logging In and Logging Out.............................................................................................................................. 79

Querying Available Devices from the System Manager.................................................................................... 80Retrieving the System Manager’s Time Zone........................................................................................81

Retrieving the Network Time Server Address........................................................................................81Retrieving a Web Service’s ID...............................................................................................................82

Retrieving a Specific Web Service’s Control URL................................................................................. 82

Retrieving the NVR Associated with the Device....................................................................................83Retrieving the Device’s Friendly Name..................................................................................................84

Retrieving the Device’s Device Description File (DDF) URL................................................................. 84Retrieving All Web Services Available on a Device...............................................................................85

Retrieving Device Attributes............................................................................................................................... 85Retrieving a System Manager’s Attribute...............................................................................................87

Retrieving a Web Service’s Attribute..................................................................................................... 88

Creating an IDeviceStorage Class..................................................................................................................... 88

Appendix A: Logging................................................................................91

Appendix B: Product Compatibility.........................................................93

Appendix C: Endura..................................................................................95

Appendix D: General Event Messages................................................... 99

Appendix E: Hardware Diagnostics Event Messsages........................101ConfigurationButton (20180).............................................................................................................................101

DriverFailure (20150)........................................................................................................................................ 102Fans (20020).....................................................................................................................................................103

HardDrives (20060)...........................................................................................................................................104ImproperShutdown (20070)...............................................................................................................................106LinkSpeed (20200)............................................................................................................................................107

PowerSupply (20120)........................................................................................................................................108UPS (20170)..................................................................................................................................................... 109

Appendix F: Software Diagnostics Event Messsages......................... 111DataLoss 20040................................................................................................................................................111

InputStreams 20160..........................................................................................................................................112PacketLoss 20080.............................................................................................................................................113

7/18/2019 C5617M-A


ntents | C5617M-A

SEBs 20210...................................................................................................................................................... 114StorageFull 20190.............................................................................................................................................116

StorageTime 20130...........................................................................................................................................117

Temperature 20140...........................................................................................................................................117

Appendix G: Glossary.............................................................................119

7/18/2019 C5617M-A


Chapter

1Introduction

Getting Started with the Pelco SDK

The Pelco SDK is a powerful software developer kit to help third parties use Pelco products alongside non-Pelcoproducts and software. While the Pelco API is both flexible and powerful, it can also potentially overwhelm some

users; of course, developers are still free to directly use the Pelco API as they wish. However, Pelco has found that

many of our customers enjoy the convenience and ease of use that the Pelco SDK provides. The Pelco SDK providesprogrammers ease of use with the following functionality:

• Video rendering

• Device and service discovery

• User and role management

• Pan, tilt, and zoom (PTZ) control

• Eventing support

• Video export

• Audio and video meta-data parsing

What Does the Pelco SDK Contain?

The Pelco SDK contains the following major components:

SDK Component1

Features / Functionality

System Manager Wrapper Device discovery

Service discovery

Pelco API Viewer Display and control MPEG-4 and H.264 streams from Pelco cameras

and DVRs / NVRs / NSMs.

Control Pan/Tilt/Zoom on Pelco PTZ-enabled cameras.

PTZ Control Wrapper Pan and tilt control

Zoom, iris, and focus control

Basic script management

Event Arbiter Library2

Advanced event subscription management:

Subscribe to individual web service events

Subscribe to events from all instances of a particular web service

Cancel an active event subscription

Event Manager

1PelcoGsoap is not a separately installable library, but it is included in the other components as required.

2EventArbiter component also contains Event Manager. Therefore, Event Manager is not a separately installable

component.

7/18/2019 C5617M-A


617M-A | Introduction

Easy to use event subscription, that focuses on subscribing to

categories of events instead of web service specific events.

NOTE:

Event Manager requires an Endura (System Manager)

system.

Meta-data Parser Parses Pelco Video Elementary Stream (VES) meta data: Timestamp,

Motion Detection, Video Analytics PrimitivesRender primitives and other data to video frame

Exporter Export video streams into a variety of popular video formats: AVI, 3GP,

or PEF

Overlay data on exported video

The Pelco SDK also contains sample projects for the following:

Code Sample Default Location

Event Arbiter Sample C:\Program Files\Pelco\API\SampleCode\EventArbiterSample

Event Manager Sample C:\Program Files\Pelco\API\SampleCode\EventArbiterSample

Exporter Sample C:\Program Files\Pelco\API\SampleCode\ExporterSample

MetaDataParser Sample C:\Program Files\Pelco\API\SampleCode\MetaDataParserSample

Pelco API Viewer Sample C:\Program Files\Pelco\API\SampleCode\PelcoAPIViewerSample

PTZ Control Wrapper Sample C:\Program Files\Pelco\API\SampleCode

\PTZControlWrapperSample

System Manager Sample C:\Program Files\Pelco\API\SampleCode

\SystemManagerWrapperSample

General Requirements

Hardware

The minimum hardware requirements for the client machine to use for completing the steps outlined in this document

are the following:

• CPU: Intel 2.4 GHz Core 2 Duo (or higher)

• Memory: 2 GB

• GPU: DirectX9 Compatible; must be a dedicated card and not a motherboard integrated chip

• HD: 1 GB free hard disk space

NOTE: Virtual machines are not supported for streaming video from Pelco cameras.

In addition to your client machine, a Pelco SDK compatible Pelco device is required. A list of currently compatible

Pelco hardware can be found in the Appendix.

Software

The software requirements for completing the steps outlined in this document are the following:

• Windows XP, Windows Vista [32 bit / 64 bit], Windows Server 2003 [32 bit / 64 bit], Windows Server 2008 [32 bit /

64 bit], Windows 7 [32 bit / 64 bit]

7/18/2019 C5617M-A


C5617M-A | Intro

• DirectX 9.0 c (must be installed separately, even if your system already includes DirectX 10 or 11 as part of

Windows Vista or higher)

• Visual Studio 2008

• Microsoft .NET Framework 3.5

NOTE: Improper use of audio/visual recording equipment may subject you to civil and criminal penalties.

Applicable laws regarding the use of such capabilities vary between jurisdictions and may require, among

other things, express written consent from the recorded subjects. You are solely responsible for insuring strict

compliance with such laws and for strict adherence to any/all rights of privacy and personalty.

Installing the Pelco SDK

1. Download the Pelco SDK from the Pelco Developer Network (PDN) at http://pdn.pelco.com . It can be found in thePelco SDK Related Downloads sub-section inside the Downloads section.

2. Once finished downloading, doubleclick on the Pelco SDK installer to begin installation. Simply follow the on-screen

prompts to complete installation.

NOTE: If you have a previous version of the Pelco SDK installed, you must uninstall it before installing the

latest version.

3. After installation, restart the system to ensure that environment variables are running correctly.

Assuming the default installation path was chosen, users can find the following folders:

File Folder Path Description

C:\Program Files\Pelco\API\Include

\C++\PelcoAPI3

Header files for all of the Pelco SDK related classes can be found

here.

C:\Program Files\Pelco\API\Libs

\Release3

Pelco SDK release module libraries can be found within the

Release directory.


\Debug3

Pelco SDK debug module libraries can be found within the Debug

directory.


\Release\Plugins

3Pelco SDK release plugins can be found within the Plugins

directory.

C:\Program Files\Pelco\API

\SampleCode3

Contains all the sample code projects related to Pelco SDK

components.

C:\Program Files\Pelco\API

\WebServices3

The WSDLs files for web services are in this directory. Please note

that the XSDs are embedded within the WSDL files themselves.

Our WSDLs, along with the embedded XSDs, provide the definition

for Pelco web services and related data types. For details, please

refer to the following links:

http://www.w3.org/TR/wsdl20/

http://www.w3.org/XML/Schema.html

C:\Program Files\Pelco\API\Logging

3

Contains an application called LoggingSetup.exe which allowsyou to write a log file for debugging purposes. You can manage

other logging related information by running LoggingSetup.exe.

NOTE:

Each Pelco SDK component may have additional installation and / or configuration requirements.

3On 64-bit systems, C:\Program Files will change to C:\Program Files (x86)

http://www.w3.org/XML/Schema.html

http://www.w3.org/TR/wsdl20/

http://pdn.pelco.com/

7/18/2019 C5617M-A



System Environment Settings for the Pelco SDK

The Pelco SDK installer adds three environment variables/paths to the installed system:

• EVEREST_BIN - the location of all the binaries. By default, this is set to C:\Program Files\Pelco\API\Libs

• EVEREST_ROOT - Location of all the Pelco header files. By default this is set to C:\Program Files\Pelco

\API\Include\C++

• PATH - This initially points to the C:\Program Files\Pelco\API\Libs\Debug folderNOTE: If you want to build the SDK in release mode, you must change the PATH variable to point to theRelease directory (e.g., C:\Program Files\Pelco\API\Libs\Release). If any of the paths have been

changed from the defaults, you will be responsible for removing the path if the SDK is uninstalled.

Including Required SDK Components For Your Application

When distributing your application that relies on the Pelco SDK, you must ensure that the required SDK component

redistributables are installed on the target client machine. As with other re-distributables, a UI will not be presented to

the user, and the re-distributable itself can be called by your custom installer. Once the re-distributable is finished, yourcustom installer can check the status of the install and whether or not it needs a reboot. In addition, the client machines

must have DirectX 9.0c, which is the latest version, and VC9 runtime installed.

As with the full SDK, download individual Pelco SDK components and Pelco SDK re-distributables from the PelcoDeveloper Network (PDN) at http://pdn.pelco.com . Once finished downloading, double click on the Pelco SDK installerto begin installation. Simply follow the on-screen prompts to complete installation.

NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com .

The sample projects assume that the default target installation directory was chosen during installation.

Setting Up Sample Projects

WARNING: Any provided sample code is meant to be a reference implementation focused on educating

developers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intendedfor immediate production use without modification.

NOTE: This entry assumes that users have already installed the Pelco SDK. Moreover, the Pelco API Viewersample project requires Microsoft’s DirectX 9, and a video card that supports DirectX 9.

NOTE: On 64-bit machines, C# code should be compiled specifically for x86.

To begin using the sample project code, locate the appropriate sample within the Pelco SDK SampleCode directory:

C:\Program Files\Pelco\API\SampleCode

NOTE: Some Pelco SDK sample projects, such as the Pelco API Viewer sample, are spread across

more than one class. There may also be more than one sample project associated with the particular SDKcomponent.

It is assumed that you will be examining the sample projects alongside this documentation.

Registering the ActiveX ControlBy default, the installer registers the Active X Component (OCX) in the C:\Program Files\Pelco\API\Libs\Debug directory. To ensure that the OCX registration is successful, change the PATH variable to point to this

directory.

For release builds, you can manually register the Pelco API Viewer ActiveX Component: PelcoAPICOMViewer.ocx.

To register the PelcoAPICOMViewer.ocx ActiveX Component, open the command line and navigate to the PelcoSDK library release directory, which is by default: C:\Program Files\Pelco\API\Libs\Release

Once within the folder, run the Microsoft Register Server (Regsvr32.exe) to register the SDKcomponent as appropriate. This must be run with administrative permissions. For example, to register the

PelcoAPICOMViewer.ocx file: Regsvr32 PelcoAPICOMViewer.ocx




7/18/2019 C5617M-A


C5617M-A | Intro

Setting Up the Working Directory

Next you will need to set the sample project’s working directory. Assuming that you have already opened the sampleproject in MS Visual Studio, right-click on the project and select the Properties menu item.

C++ Example

7/18/2019 C5617M-A



C# Example

Now click on the Debugging menu item on the left navigation of the sample project’s property page window.

7/18/2019 C5617M-A


C5617M-A | Intro

For example, in C++:

For example, in C#:

7/18/2019 C5617M-A



Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug version,change the Working Directory value as appropriate. If you kept the default installation directory for the Pelco SDK,

use C:\\Program Files\Pelco\API\Libs\Release to use the production version of the Pelco SDK libraries.

Conversely, use C:\\Program Files\Pelco\API\Libs\Debug to use the debug version of the Pelco SDKlibraries.

On a 64 bit machine, set the Platform target to support x86.

NOTE: Be sure to set the character set to "Use Multi-Byte Character Set" under the project properties for thesample code to compile properly.

Adding References to Managed Libraries for C#

Once you have registered the PelcoAPICOMViewer ActiveX object and the sample project is located, open it in Visual

Studio 2008. Before building the project, users must add a reference to the managed DLL into the project. Within

Visual Studio’s Solution Explorer window, right click on the References project item. A menu should appear. Click onthe Add Reference menu item.

A dialog window should now appear. Click on the Browse tab. Assuming the default installation directory was notchanged, users should be able to find the managed DLL file within the directory C:\Program Files\Pelco\API\Libs\Debug. Now select the managed DLL file and click on the Ok button.

7/18/2019 C5617M-A


C5617M-A | Intro

NOTE: These references may already appear in the project, possibly with yellow exclamation marks. ("!") Ingeneral, these Pelco library references should still be deleted and re-added, after installing or reinstalling theSDK.

Now that you’ve added the managed DLL reference to the project, we need to add the managed Pelco API MPFViewer.

To add the managed Pelco API MPF Viewer, follow the same steps as before for the managed DLL.

A dialog window should now appear. Click on the Browse tab. Assuming the default installation directory was not

changed, users should be able to find the PelcoAPIMPFViewer.dll file within the directory C:\Program Files\Pelco\API\Libs\Debug. Now select the PelcoAPIMPFViewer.dll file and click on the Ok button.

You should now see both the managed ManagedPTZControlWrapper reference and the PelcoAPIMPFViewerreference within the project. At this point you should be able to run the Pelco API Viewer sample C# project.

7/18/2019 C5617M-A



NOTE: With the PelcoAPICOMViewer.ocx control, you may need to clean and rebuild this project severaltimes before the OCX control will work. This is apparently a Visual Studio / OCX limitation.

7/18/2019 C5617M-A


Chapter

2Displaying and Controlling Video Streams

Overview

The most important thing in any security imaging system, is for the security operator to see what images his IPcameras are capturing. Consequently displaying a video stream and controlling its playback is most likely what you will

need to get working first.

Where Does the Pelco SDK Fit?

To display and control video streams, use the Pelco API Viewer. The Pelco API Viewer is an easy to use Windowsbased tool for viewing MPEG-4 and H.264 streams from Pelco IP cameras and DVRs / NVRs / NSMs. It provides a

Pelco supported player for integrating Pelco devices with 3rd party applications. This player can be configured to work

in both RTP and RTSP mode. In RTP mode, the player uses one of several Pelco API methods to initiate and control

streams. While in RTSP mode, the player expects to work with either devices, such as a Sarix IP camera, where RTSP

is supported by default; or software solutions like the RTSP Server.

The Pelco API Viewer can be used in three ways:

1. C++

2. C#

3. OCX (ActiveX Control)

Support is provided for viewing both MPEG-4 and H.264 streams, but changing a video configuration from one format

to the other causes the video to stop streaming.

What’s Ahead

There are two major tasks for viewing a video stream using the Pelco API Viewer:

• Opening, playing, displaying a stream

• Controlling the stream

Initializing the Pelco API Viewer (C++)

Before you can use the Pelco API Viewer, you need to declare and configure your new instance.

1. Declare the Pelco API Viewer instance.

NOTE: The related source code for this entry can be found in main.cpp’s main function, which resides inthe PelcoAPIViewer sample project.

PelcoAPI::PelcoAPIViewer _pViewer;

2. Set the instance’s plug-in directory.

Assuming that you did not change the default target installation directory, it can be found here: C:\Program

Files\Pelco\API\Libs\Debug\Plugins\

(If running in Release mode, change this path to C:\Program Files\Pelco\API\Libs\Release\Plugins\).

7/18/2019 C5617M-A


617M-A | Displaying and Controlling Video Streams

The plug-in directory contains components that are key to the SDK’s encoding, decoding, and transcodingcapabilities. Without a proper reference, key features of the Pelco SDK may not function properly. Please note that

the plug-in directory is dependent on where you installed the Pelco SDK.

NOTE: The related source code for this entry can be found in main.cpp’s main function, which resides in

the PelcoAPIViewer sample project.

_pViewer.SetPluginDir("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins\\");

3. Create a new window handle and associate it to the Pelco API Viewer instance.Please note that logic to create the window handle can be found in the _DbgCreateParentWindow method.

HWND _hWndParent = NULL;//... Logic to create a window and display it. Refer to _DbgCreateParentWindow ...m_pViewer->SetWindowHandle((_hWnd ? _hWnd : this->m_hWnd));

Initializing the Pelco API Viewer (C#)

NOTE: In release mode, you need to select the Enable unmanaged code debugging checkbox in the

project settings to see console output.

Before you can use the Pelco API Viewer, you need to declare and configure your new instance.

PelcoAPIMPFViewer contains two components: PelcoAPIMPFViewerControl, a convenient, prebuilt control,or a managed version of the PelcoAPIViewer library that enables the developer to control the videostream

programmatically. Both approaches are described below.

To use the more programmable PelcoAPIViewer library, complete the following steps: declare the

PelcoAPIViewer instance, set the plugin directory, and set the window handle.

PelcoAPI.PelcoAPIViewerNet pViewer = new PelcoAPI.PelcoAPIViewerNet();pViewer.SetPluginDir(objstreamparam.PluginDir);pViewer.SetWindowHandle(windowsviewerobj.Handle);

To use the prebuilt control PelcoAPIMPFViewerControl, complete the following steps.

1. Declare the Pelco API Viewer instance.

NOTE: The related source code for this entry can be found in PelcoAPIViewerForm.designer.cs

constructor, which resides in the PelcoAPIViewerSample sample project.

private PelcoAPIMPFViewer.PelcoAPIMPFViewerControl _pViewer;this._pViewer = new PelcoAPIMPFViewer.PelcoAPIMPFViewerControl();

2. Listen for the user selected plug-in directory.

Assuming that you did not change the default target installation directory, it can be found here: C:\ProgramFiles\Pelco\API\Libs\Debug\Plugins

NOTE: The plug-in directory contains components that are key to the SDK’s encoding, decoding, and

transcoding capabilities. Without a proper reference key features of the Pelco SDK may not functionproperly. Please note that the plug-in directory is dependent on where you installed the Pelco SDK.

private void BrowseForPluginDir(object sender, EventArgs e){

try{this._pOpenFolder.ShowDialog(this);this._txtFolder.Text = _pOpenFolder.SelectedPath + "\\";}catch(Exception /*ex*/){}}

3. Save the Plugin folder and do the final initialization.

private void SaveStreamSettings(object sender, EventArgs e){

7/18/2019 C5617M-A


C5617M-A | Displaying and Controlling Video S

try {_pViewer.SetPluginDir(_txtFolder.Text);_pViewer.SetupStream(_txtIP.Text, _txtPort.Text,_txtServiceId.Text,_txtTransport.Text);}catch (Exception /*ex*/) { }}

Setting Size and Position of Video Display Area

Calling the SetDisplayRect method to center the video stream display inside a window with margins does not

automatically center it. You need to set the size and position of the video display rectangle so that its width and heightare equal to the width and the height of the window.

The SetDisplayRect method allows resizing the video display area when the window is resized. Thus,

SetDisplayRect would typically be called from a resize event procedure.

SetDisplayRect contains the following parameters:

top

The starting Y coordinate of the rectangle for its top side.

left

The starting X coordinate of the rectangle for its left side.

width

The width of the rectangle.

height

The height of the rectangle.

PELCO_API_EXPORT void SetDisplayRect(int top, int left, int width, int height)throw ();

For example:

TRACE_INFO("Calling SetDisplayRect\n");

_pViewer.SetDisplayRect(75, 100, 824, 618);

Querying an RTP Stream

The VideoQuery function can be used to query the camera or the NSM to retrieve video properties of a stream.

Query a camera or NSM by calling the VideoQuery method passing in the following parameters:

szStartTime

The starting time in the stream to begin playback. This value should be in UTC format, for example,

2011-08-12T20:32:00.For live streams, set this value to NOW.

szEndTime

The ending time in the stream to stop playback, for example, 2011-10-01T04:00:00. This valueshould be in UTC format. For live streams, set this value to INFINITE.

szIPAddress

The IP address of NSM or camera source of the stream.

szPort

The NSM or camera source of the stream’s port number.

szNVRServiceId

The ID of the NVR to use with playback. This field is not used for live streams. (Required for manual

recording.)

szCameraServiceId

7/18/2019 C5617M-A



The last number of the web service endpoint URL of a camera. For example, when an endpoint URLends with “VideoOutput-4” then 4 is the service ID.

szCamUuid

The IP camera’s UPnP Unique Device Name (UDN)

NOTE: The IP camera’s UDN is required if you want to start manual recording on a

live stream. Otherwise, this parameter is optional.

bLowBandwidth

The flag to start a low bandwidth stream. Live only

pStreamInfo

Streaming data to be filled in. This value can be passed back to live or playback StartStream callin RTP only.

Opening, Playing, and Displaying a Live or Playback RTP Stream

NOTE: The related source code for this entry can be found in main.cpp’s main function, which belongs to

the PelcoAPIViewer sample project SampleConsole9.

Before being able to control a video stream, you must first open the stream, and display it on a Window instance.

1. Initialize the Pelco API Viewer.

Refer to Initializing the Pelco API Viewer (C++) for details.

2. Start the video stream to display, by calling the StartStream method, passing in the following parameters:

szStartTime

For live RTP, this value must be "NOW". For playback RTP, this must be the start time in the

following format: YYYY -MM -DDTHH :MM :SS in UTC (required).

szEndTime

For live RTP, this value must be "INFINITE". For playback, this value must be the end time in thefollowing format: YYYY -MM -DDTHH :MM :SS in UTC (required).

szIpAddress

The IP address and port number of the source of the video stream for NSM, NVR, or EE500. Forlive RTP, this is the IP address of the camera. For playback, this is the IP address of the NSM/NVR

(required).szPort

The IP address and port number of the source of the video stream for NSM, NVR, or EE500. For live

RTP, this is the port number of the camera. For playback, this is the port number of the NSM/NVR(required).

szCameraId

The channel number for the camera, for example, VideoOutput-1 where 1 is the channel number

(required for both live and playback)

szTransport

The video stream’s transport (RTP) URL (optional for live RTP stream, because the camera starts a

MULTICAST stream if no value is supplied. Required for playback.) The IP address must be the IPv4address of the machine on which the code is running, for the network through which it will connect to

the video source. The port number must be an even number, and must not be in use.

Example:rtp:// ip_of_local_machine:open_port_even

szCamUuid

The IP camera’s UDN (required if the user wants to start recording for a live stream. Otherwise,

optional)

NOTE: The IP camera’s UDN is required if you want to start manual recording on a

live stream (required).

szNvrId

7/18/2019 C5617M-A



The NVR’s ID (optional for a live RTP stream. Required for manual recording of a live RTP streamand for a playback RTP stream)

ITimeStampDelegate

Signals if you want the timestamp returned by the API. If no timestamp is required, do not supply avalue for this parameter.

bVideoOnly

Stream video without audio. By default, this parameter is set to FALSE for backwards compatibility.

bLowBandwidth

Sets the stream to low bandwidth stream from camera. The camera needs to be configured or havesecondary low bandwidth stream enabled. This parameter is set to FALSE by default for backwards

compatibility.

NOTE: This parameter is only valid for live streams.

StreamInfo

If you have already queried the NSM/Camera using the VideoQuery method then you can pass the

stream information back into the StartStream call with this parameter. This parameter is set to NULLby default for backwards compatibility.

For a live RTP stream:

MyAppNamespace::TimeStamp _pDelegate;const char* pszSesId = NULL;//... Other logic ...pszSesId = _pViewer.StartStream(const char* StartTime, const *endTime,"10.220.196.149", "49154", "1", "rtp://10.220.196.148:7162","uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", &_pDelegate, False, False, NULL);

where:

• StartTime is the time you want to start video. For live streams, use the value as "NOW",

• endTime is the time you want the video to end. For live streams, use the value “INFINITE”.

NOTE: For NULL/optional values, use “” for strings and NULL for interface values.

• szServiceId is the camera service ID, etc,

For a playback RTP stream:

MyAppNamespace::TimeStamp _pDelegate;const char* pszSesId = NULL;//... Other logic ...pszSesId = _pViewer.StartStream("2010-08-08T18:02:00", "2010-08-08T18:28:00","10.220.196.149", "49154", "1", "rtp://10.220.196.148:7162","uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", &_pDelegate, False, False, NULL);

where:

• szServiceId is the camera service ID,

• szTransport and szCamUuid are required for playback.

If successful, these methods will return a session ID, pszSesId, of the stream. This will be used throughout thisdocument for tasks related to the Pelco API Viewer.

Opening, Playing, and Displaying an RTSP Stream



1. Initialize the Pelco API Viewer.

Refer to Initializing the Pelco API Viewer (C++) or Initializing the Pelco API Viewer (C#) entry for details.

7/18/2019 C5617M-A



2. Start the video stream to display, by calling the StartStream method, passing in the following parameters:

The location of the RTSP stream

The username to use for authentication (Optional)

The password to use for authentication (Optional)

A boolean indicating whether or not the stream is multicast

The timestamp parameter is an object that implements the ITimeStampDelegate interface, or NULL ifyou don’t want to receive timestamps as the video plays. (Optional)

MyAppNamespace::TimeStamp _pDelegate;const char* pszSesId = NULL;//... Other logic e.g. setting up windows, and so on ...//Live example:pszSesId = _pViewer.StartStream("rtsp://10.220.196.169/?deviceid=uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15",NULL, NULL,false, &_pDelegate);//Playback example:pszSesId = _pViewer.StartStream("rtsp://10.221.224.35/?deviceid=uuid:01b766f9-9d87-4613-a168-5e5d179d339d&starttime=2011-12-04T10:00:00&endtime=2011-12-04T11:00:00",NULL, NULL,

false, &_pDelegate);

If successful, the method will return a session ID of the stream. Keep this in mind, as this will be used throughout

for tasks related to the Pelco API Viewer.

Forward Playback of RTP and RTSP Streams



This entry assumes that you have already completed the steps outlined in the Opening, Play ing, and Displaying an

RTSP Stream entry.

To perform a forward or reverse playback of a currently running video stream, call the Pelco API Viewer instance’s

PlayForward or PlayReverse method passing in the following parameters:

The target video stream’s session ID. A successful call to the StartStream method returns this

value.

A float value representing the desired playback speed. Valid possible playback speeds can rangefrom 0 - 300, with 0 representing a paused state and 1 representing regular playback speed. (Also, 1

represents the speed for live video.)

const char* pszSesId = NULL; //... Get pszSesId, the stream’s session ID, by starting a stream ... if(_pViewer.PlayForward(pszSesId, 8.0) !=0 ){ //... Handle error ... }

Reverse Playback of RTP and RTSP Streams

To perform a reverse playback of a currently running video stream, call the Pelco API Viewer instance’s

PlayReverse method; passing in the following parameters:


value.

A float value representing the desired playback speed. Valid possible playback speeds can range

from 0 - 300, with 0 representing a paused state and 1 representing regular playback speed.

7/18/2019 C5617M-A



WARNING: Reverse playback is not possible for live streams.

const char* pszSesId = NULL; //... Get pszSesId, the stream’s session ID, by starting a stream ... if(_pViewer.PlayReverse(pszSesId, 8.0) !=0 ){ //... Handle error ... }

Fast Forward / Reverse Playback of RTP and RTSP Streams

To perform a fast forward (using FrameForward, which advances by a single frame) or fast reverse playback of a

currently running video stream (using FrameReverse, which reverses by a single i-frame that may include multiplep-frames), call the Pelco API Viewer instance’s PlayForward or PlayReverse method (as appropriate), passing

in the following parameters:


value.

A float value representing the desired playback speed. Valid possible playback speeds can rangefrom - 300 to 300, with speed greater than 1 (regular playback speed). Slow motion is supported

where the speed is set at half the regular speed (e.g., -0.5 or 0.5).

Currently, PlayReverse only plays backward, and PlayForward only plays forward, regardless of whether the

speed parameter is negative or positive. Therefore, call PlayForward for fast forward, and call PlayReverse forfast reverse.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.PlayForward(pszSesId, 8.0) !=0 ){//... Handle error ...}

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.PlayReverse(pszSesId, 8.0) !=0 ){//... Handle error ...}

Pausing RTP and RTSP Playback Streams



WARNING: DO NOT pause live streams. Pausing a live stream may produce an unpredictable result.

This entry assumes that you have already completed the steps outlined in the Opening, Playing, and Displaying an

RTSP Stream entry.

To pause currently running video stream, call the Pelco API Viewer instance’s Pause method; passing in the targetvideo stream’s session ID.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.Pause(pszSesId) !=0 ){//... Handle error ...}

7/18/2019 C5617M-A



Frame Forward Playback of the RTP Stream

A frame forward operation advances playback of a currently paused video stream by a single i-frame, which may

include multiple p-frames.

To perform this operation, call the Pelco API Viewer instance’s FrameForward method, passing in the following

parameter:

The target video stream’s session ID. A successful call to the StartStream method, returns thisvalue.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.FrameForward(pszSesId) !=0 ){//... Handle error ...}

Frame Reverse Playback of the RTP Stream

A frame reverse operation steps a currently paused video stream backward by a single frame.

To perform this operation, call the Pelco API Viewer instance’s FrameReverse method; passing in the followingparameter:

The target video stream’s session ID. A successful call to the StartStream method, returns this

value.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.FrameReverse(pszSesId) !=0 ){//... Handle error ...}

Resuming the RTP or RTSP Stream from a Paused State



NOTE: This entry assumes that you have already completed the steps outlined in Opening, Playing, and

Displaying a Live or Playback RTP Stream .

To resume a paused playback stream, call the Pelco API Viewer instance’s Resume method, passing in the targetvideo stream’s session ID.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.Resume(pszSesId) !=0 ){//... Handle error ...}

Stopping the RTP and RTSP Stream



This entry assumes that you have already completed the steps outlined in the Opening, Playing, and Displaying the

Stream entry.

7/18/2019 C5617M-A



To perform a stop playback of a currently running video stream, call the Pelco API Viewer instance’s StopStreammethod; passing in the target video stream’s session ID.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.StopStream(pszSesId) !=0 ){//... Handle error ...}

Setting Audio Volume of a Live or Playback RTP stream

Audio volume of a playback stream can be controlled using the SetAudioVolume method, by passing in the video

stream’s session ID and an integer volume level, where the range is 0 to 100, with 0 representing mute.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.SetAudioVolume(pszSesId, 10) !=0 ){//... Handle error ...}

Displaying Analytic Events for an RTP StreamTo display analytic events for the currently playing video stream, call the DisplayAnalyticEvents method,

passing in the target video stream’s session ID and the bEnable set to true.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.DisplayAnalyticEvents(pszSesId, true) !=0 ){//... Handle error ...}

Displaying Motion Events for an RTP Stream

To display motion events for the currently playing video stream, call the DisplayMotionEvents method, passing

in the target video stream’s session ID and the bEnable set to true.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...if(_pViewer.DisplayMotionEvents(pszSesId, true) !=0 ){//... Handle error ...}

Displaying a Timestamp Overlay for RTP and RTSP Streams

To display a timestamp overlay for live/playback video streams, call the DisplayTimestampOverlay method,

passing in the target video stream's session ID, bEnable set to true, and an instance of ViewerOverlayInfo struct.If the struct (the 3rd parameter) is set to null, the default style overlay is displayed. The default style would be:

• Location: Bottom left

• Date format: MMDDYYYY

• Time format: HHMMSSTT

• Font name: Arial

• Font size: 9

• Font color: Yellow

• Background color: transparent to the current screen

7/18/2019 C5617M-A



C++ Example:

PelcoAPI::ViewerOverlayInfo overlay; PelcoAPI::COLOR fontColor = {0xFF, 0xFF, 0xFF, 0xA0}; PelcoAPI::COLOR fontBgColor = {0x00, 0x00, 0x00, 0x00}; overlay.m_dateFormat = PelcoAPI::VIEWER_DATE_FORMAT_MMDDYY; overlay.m_timeFormat = PelcoAPI::VIEWER_TIME_FORMAT_TTHHMMSS; overlay.m_fontColor = fontColor; overlay.m_fontBgColor = fontBgColor;

overlay.m_location = PelcoAPI::VIEWER_OVERLAY_LOCATION_TOP_LEFT; overlay.m_nFontSize = 12; overlay.m_fontNameStr = "Arial";bool bSuccess = _pViewer.DisplayTimestampOverlay(pszSesId, true, &overlay);

C# Example:

System.Drawing.Color fontColor = System.Drawing.Color.FromArgb(0xFF, 0xFF, 0xFF, 0xA0);System.Drawing.Color fontBgColor = System.Drawing.Color.FromArgb(0x00, 0x00, 0x00, 0x00);ViewerOverlayInfoNet overlay = new ViewerOverlayInfoNet();overlay.m_location = PelcoAPI.ViewerOverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT;overlay.m_dateFormat = PelcoAPI.ViewerDateFormatNet.DATE_FORMAT_MMDDYYYY;overlay.m_timeFormat = PelcoAPI.ViewerTimeFormatNet.TIME_FORMAT_HHMMSSTT;

overlay.m_fontNameStr = "Arial";overlay.m_nFontSize = 16;overlay.m_fontColor = fontColor;overlay.m_fontBgColor = fontBgColor; Boolean bSuccess = _rtpViewer.DisplayTimestampOverlay(_rtpSessionId, true, overlay);

NOTE: Live and playback RTSP streams from Sarix cameras are unable to display timestamp information.

7/18/2019 C5617M-A



Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams

To take a snapshot of the current video frame, call the Pelco API Viewer instance’s TakeSnapShot method;

passing in the target video stream’s session ID, and the desired resulting filename and file path.

const char* pszSesId = NULL;//... Get pszSesId, the stream’s session ID, by starting a stream ...

nResult = m_pViewer->TakeSnapShot(szSessionId, "C:\\snapshots.jpg");

Pan, Tilt, Zoom (PTZ) Control for RTP Stream Using PelcoAPIViewer

Cameras with PTZ functionality can also be controlled using the PelcoAPIViewer. For more information, see Pan, Tilt,

Zoom (PTZ) Control .

NOTE: This only works with PelcoAPIViewer in RTP Live mode.

7/18/2019 C5617M-A



7/18/2019 C5617M-A


Chapter

3Pan, Tilt, Zoom (PTZ) Control

Overview

WARNING: Any provided sample code is meant to be a reference implementation focused on educatingdevelopers about Pelco devices. Though there are exceptions, in general Pelco sample code is NOT intended

for immediate production use without modification.

WARNING: The content below assumes that the default target installation directory was chosen during

installation.

For the latest Pelco documentation, visit http://pdn.pelco.com .

After you’ve found the IP camera on your network and displayed its live stream on your display, you will probably wantto start controlling your camera’s viewing position: up and down and left and right, as well as magnification (zoom),

focus, and camera iris.

The StopContinuous method is available to stop the camera from continually moving, and the Stop() call is

available to stop Lens control (zoom, iris, and focus) actions. To stop continuous positioning calls, pass in a 0 value.For example, after executing ContinuousMove, call ContinuousMove(0, 0) to stop moving.


To move your IP camera’s current view, you need to start using the Pelco SDK’s PTZ Control Wrapper. The PTZ

Control Wrapper is an easy to use tool for controlling various PTZ and lens related functionality. For this section we’ll

only focus on panning and tilting the camera.

As in the previous section we’ll be examining the sample project code. Specifically, this section covers the PTZ ControlWrapper. This sample project exhibits PTZ Control Wrapper functionality.

NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methods

described in this topic, there is an equivalent method in the PelcoAPIViewer API.

Initializing the PTZ Control Wrapper

NOTE: The related source code for this entry can be found in main.cpp’s main function (for C++) or

Program.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper sample project.



To instantiate the managed PTZ Control Wrapper instance, use the following parameters:

Your IP camera’s current IP address

Your IP camera’s port number

Your IP camera’s service ID (usually 1 unless this number represents a channel in a multi-channelencoder)


7/18/2019 C5617M-A


617M-A | Pan, Tilt, Zoom (PTZ) Control

C++ Example

PelcoAPI::PTZControlWrapper ptzControlWrapper("10.220.196.144”, 49152, 1);

After you are finished, stop all PTZ Control Wrapper actions:

bool bSuccess = ptzControlWrapper.Stop();

NOTE: The following stop actions are available:• To stop Lens control actions such as zoom, iris, and focus, use the Stop() call.

• To stop continuous movement triggered by ContinuousMove, ContinuousPan, and ContinuousTilt,

use the StopContinuous() call.

C# Example

ManagedPTZControlWrapperNet managedPTZControl = newManagedPTZControlWrapperNet("10.220.196.144”, 49152, 1);

After you are finished, stop all PTZ Control Wrapper actions:

Boolean bSuccess = managedPTZControl.Stop();

NOTE: The following stop actions are available:

• To stop Lens control actions such as zoom, iris, and focus, use the Stop() call.

• To stop continuous movement triggered by ContinuousMove, ContinuousPan, and ContinuousTilt,

use the StopContinuous() call.

Continuous Panning





This entry covers the portion of the sample project that deals with moving the camera left and right.

1. Initialize the PTZ Control Wrapper.

Refer to Initializing the PTZ Control Wrapper for details.

2. Call the PTZ Control Wrapper instance’s ContinuousPan method.

• To pan your IP camera left, pass in a negative rotational x parameter.

• To pan the IP camera right, pass in a positive value for the rotational x parameter.

For more details on the ContinuousPan method, please refer to the PTZ Control Wrapper API reference documentation .

C++ Example:

//panning left

bool bSuccess = ptzControlWrapper.ContinuousPan(-10000);//panning rightbool bSuccess = ptzControlWrapper.ContinuousPan(10000);

C# Example:

//panning leftBoolean bSuccess = managedPTZControl.ContinuousPan(-10000);//panning rightBoolean bSuccess = managedPTZControl.ContinuousPan(10000);

http://pdn.pelco.com/content/documentation


7/18/2019 C5617M-A


C5617M-A | Pan, Tilt, Zoom (PTZ) C

3. When you want to stop the camera from continually moving, use the StopContinuous() method (refer toContinuous Stop for details), or pass in a 0 value to the ContinuousPan method as shown in the following

example.C++ Example:

bool bSuccess = ptzControlWrapper.ContinuousPan(0);

C# Example:

Boolean bSuccess = managedPTZControl.ContinuousPan(0);

Continuous Tilting


Program.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper C++ sample project.



This entry covers the portion of the sample project that deals with moving the camera up and down.



2. Call the PTZ Control Wrapper instance’s ContinuousTilt method.

• To tilt the IP camera down, pass in a negative rotational y value for the second parameter.

• To tilt the IP camera up, pass in a positive value for the rotational y parameter. Disregard the last four

parameters.

For more details on the ContinuousTilt method, please refer to the PTZ Control Wrapper API reference

documentation .

C++ Example:

//tilting downbool bSuccess = ptzControlWrapper.ContinuousTilt(-9000);//tilting upbool bSuccess = ptzControlWrapper.ContinuousTilt(9000);

C# Example:

//tilting downBoolean bSuccess = managedPTZControl.ContinuousTilt(-9000);//tilting upBoolean bSuccess = managedPTZControl.ContinuousTilt(9000);

3. When you want to stop the camera from continually moving, use the StopContinuous() method (refer toContinuous Stop for details), or pass in a 0 value to the ContinuousTilt method as shown in the following

example.C++ Example:

bool bSuccess = ptzControlWrapper.ContinuousTilt(0);

C# Example:

Boolean bSuccess = managedPTZControl.ContinuousTilt(0);

Continuous Diagonal Movement


Program.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper C++ sample project.



7/18/2019 C5617M-A





This entry covers the portion of the sample project that deals with continuously moving the camera in a diagonal

manner.



2. Call the ContinuousMove method.

The first parameter represents both speed and direction on the X plane. Use a negative integer to pan left and apositive integer to pan right. The second parameter represents both speed and direction on the Y plane. Use a

negative integer to tilt down and a positive integer to tilt up. For more details on the ContinuousMove method,pplease refer to the PTZ Control Wrapper API reference documentation .

C++ Example:

//tilting downbool bSuccess = ptzControlWrapper.ContinuousMove(10000, -10000);//tilting upbool bSuccess = ptzControlWrapper.ContinuousMove(10000, 10000);

C# Example:

//tilting down

Boolean bSuccess = managedPTZControl.ContinuousMove(10000, -10000);//tilting upBoolean bSuccess = managedPTZControl.ContinuousMove(10000, 10000);

3. When you want to stop the camera from continually moving, use the StopContinuous() method (refer to

Continuous Stop for details), or pass in a 0 value to the ContinuousMove method as shown in the followingexample.

C++ Example:

bool bSuccess = ptzControlWrapper.ContinuousMove(0,0);

C# Example:

Boolean bSuccess = managedPTZControl.ContinuousMove(0,0);

Stopping Continuous Movement

To stop the camera from continually moving, call the StopContinuous method.C++ Example:

bool bSuccess = ptzControlWrapper.StopContinuous();

C# Example:

Boolean bSuccess = managedPTZControl.StopContinuous();

Enabling Continuous Pan/Tilt/Move and Zoom APIs via UDP Instead ofTCP

Call the PTZ Control Wrapper's SetLowLatencyMode method, passing in true as an argument. This will send

the subsequent ContinuousMove, ContinuousTilt, ContinuousPan, StopContinuous and Zoom calls viaUDP.

C++ Example:

bool bSuccess = ptzControlWrapper.SetLowLatencyMode(true);


7/18/2019 C5617M-A



C# Example:

Boolean bSuccess = managedPTZControl.SetLowLatencyMode(true);

Zoom API calls over UDP currently work on Sarix firmware 1.7.41.

Panning to a Specific Position





This entry covers the portion of the sample project that deals with moving the camera to a specific point in 2D space.

Units are shown in centidegrees (hundredths of a degree).



2. Call the PTZ Control Wrapper’s AbsolutePan method, passing in the desired position on the rotational X plane.

• Passing a negative value moves left of the home position.

• Passing a positive value moves right of the home position.For more details on the AbsolutePan method, please refer to the PTZ Control Wrapper API reference documentation .

Generally, the panning range is limited to 0 to 360 degrees (0 to 36,000 centidegrees). This limit might differ,depending on the type of camera used.

C++ Example:

bool bSuccess = ptzControlWrapper.AbsolutePan(36000);

C# Example:

Boolean bSuccess = managedPTZControl.AbsolutePan(36000);

Tilting to a Specific Position









2. Call the PTZ Control Wrapper’s AbsoluteTilt method, passing in the desired position on the rotational X plane.• Passing a negative value moves down from horizontal..

• Passing a positive value moves up from horizontal..

For more details on the AbsoluteTilt method, refer to the PTZ Control Wrapper API reference documentation .

Generally, the tilting range is limited to 0 to -90 degrees (0 to -9000 centidegrees). This limit might differ, depending

on the type of camera used.

C++ Example:

bool bSuccess = ptzControlWrapper.AbsoluteTilt(-9000);




7/18/2019 C5617M-A



C# Example:

Boolean bSuccess = managedPTZControl.AbsoluteTilt(-9000);

Moving to a Specific Position









2. Call the PTZ Control Wrapper’s AbsoluteMove method, passing in the desired position on the rotational X and Yplanes.

• Passing a negative value for X moves the camera left of the home position.

• Passing a positive value for X moves the camera right of the home position.

• Passing a negative value for Y moves the camera down from horizontal.• Passing a positive value for Y moves the camera up from horizontal.

Refer to your camera model’s specifications for tilt position limits. For more details on the AbsoluteMove method,

please refer to the PTZ Control Wrapper API reference documentation .

C++ Example:

bool bSuccess = ptzControlWrapper.AbsoluteMove(20, 40);

C# Example:

Boolean bSuccess = managedPTZControl.AbsoluteMove(20, 40);

Moving to a Position Relative to the Current Location

Call the PTZ Control Wrapper's RelativeMove method, passing in the relative X and Y plane values that the

camera should move from the current location.


C++ Example:

bool bSuccess = ptzControlWrapper.RelativeMove(3000, 5000);

C# Example:

Boolean bSuccess = managedPTZControl.RelativeMove(3000, 5000);

Getting the Camera’s Current Position





This entry covers the portion of the sample project that deals with returning the camera current position expressed as a

specific point in 3D space.



7/18/2019 C5617M-A





2. Call the PTZ Control Wrapper’s GetAbsolutePosition method.

For more details on the GetAbsolutePosition method, please refer to the PTZ Control Wrapper API reference documentation .

C++ Example:

int positionX = 0;int positionY = 0;bool bSuccess = ptzControlWrapper.GetAbsolutePosition(&positionX, &positionY);

C# Example:

int positionX = 0;int positionY = 0;Boolean bSuccess = managedPTZControl.GetAbsolutePosition(ref positionX,ref positionY);

Managing the Magnification (Zoom) Value

NOTE: The related source code for this entry can be found in main.cpp’s main function (for C++) orProgram.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper sample project.



This section describes how to change the camera’s current magnification level. Magnification refers to the camera’s

zoom level, which in turn describes the focal length for which the camera's lens is currently set. Zoom level is

expressed as 100 times the level of magnification that you want. For example, 1x magnification becomes 100, and 18x

magnification becomes 1800.

To change the current magnification level, and to later retrieve the current magnification value, do the following:



2. Call the PTZ Control Wrapper’s AbsoluteZoom method passing in the desired zoom level.

If the request was successful, your camera’s magnification level should now be changed. For more details on the

AbsoluteZoom method, refer to the PTZ Control Wrapper API reference documentation .

C++ Example:

bool bSuccess = ptzControlWrapper.AbsoluteZoom(150);

C# Example:

Boolean bSuccess = managedPTZControl.AbsoluteZoom(150);

3. Call the GetAbsoluteZoom method to return the camera’s current magnification setting.

If the request was successful, your camera’s magnification level should be returned. For more details on the

GetAbsoluteZoom method, refer to the PTZ Control Wrapper API reference documentation .

C++ Example:

int magnification = 0;bool bSuccess = ptzControlWrapper.GetAbsoluteZoom(magnification);

C# Example:

int magnification = 0;Boolean bSuccess = managedPTZControl.GetAbsoluteZoom(ref magnification);






7/18/2019 C5617M-A



Managing the Focus Value





NOTE: We recommend that you let your IP camera manage focus automatically.

This portion of the documentation covers how to focus near the IP camera or focus far away from the IP camera.



2. Call the SetFocus method, passing in the desired focus command.

For a little background, the SetFocus method takes in only the following values:

0

To stop all focus related operations.

1

To start focusing farther.

2To start focusing nearer.

If the request was successful, your camera’s focus should now be changing (unless you passed a 0). This will

not stop until a SetFocus request is made with a different value, or if you call the Stop method, which will stopmovement or lens related action the camera is currently doing.

C++ Example:

bool bSuccess = ptzControlWrapper.SetFocus(1);bool bSuccess = ptzControlWrapper.SetFocus(2);bool bSuccess = ptzControlWrapper.SetFocus(0);

C# Example:

Boolean bSuccess = managedPTZControl.Focus(1);Boolean bSuccess = managedPTZControl.Focus(2);Boolean bSuccess = managedPTZControl.Focus(0);

3. Alternatively the recommended way of controlling focus is to let your IP camera manage it automatically. To enable

this feature, call the AutoFocus method and pass a boolean value of true. To disable it, just pass a boolean valueof false.

C++ Example:

bool bSuccess = ptzControlWrapper.AutoFocus(true);

C# Example:

Boolean bSuccess = managedPTZControl.AutoFocus(true);

Iris Control





NOTE: We recommend that you let your IP camera manage its iris automatically.

7/18/2019 C5617M-A



This section demonstrates how to open and close your camera’s iris.



2. Call the SetIris method, passing in the desired iris command.

For a little background, the SetIris method takes only following values:

0

To stop all iris related operations.

1

To start closing the iris.

2

To start opening the iris.

If the request was successful, your camera’s iris should now be changing (unless you passed a 0). This will not

stop until the SetIris request is made with a different value, or if you call the Stop method, which will stopmovement or lens related action the camera is currently doing.

C++ Example:

bool bSuccess = ptzControlWrapper.SetIris(1);bool bSuccess = ptzControlWrapper.SetIris(2);

C# Example:

Boolean bSuccess = managedPTZControl.Iris(1);Boolean bSuccess = managedPTZControl.Iris(2);

3. Alternatively the recommended way of controlling the iris is to let your IP camera manage it automatically. Toenable this feature, call the AutoIris method and pass a boolean value of true. To disable it, just pass a boolean

value of false.C++ Example:

bool bSuccess = ptzControlWrapper.AutoIris(true)

C# Example:

Boolean bSuccess = managedPTZControl.AutoIris(true)

Scripting

One of Pelco’s most powerful features enables users to manage and run scripts. Scripts allow you to extend the

behavior of Pelco devices with little effort. Before we show you how to use the SDK’s scripting related features, it’simportant to know about the different types of Pelco scripts:

Preset

A preset is a script that allows you to save a camera's stationary position, zoom, and other settings such as auto-iris

and auto-focus, collectively known as a bookmark. Users can save multiple presets per camera. For example if you’re

monitoring several specific points using the same camera, you can set one preset for each location that needs to bemonitored; each with its own set of zoom, iris, and focus values.

Presets that you create must be names, such as “PRESETX ”, where the keyword PRESET must be used (uppercase)

followed by a positive integer . For example, PRESET9 .

The number of presets that can be saved and activated is dependent on the Pelco device.

Pattern

A pattern is like a group of presets combined. For example, you might control an IP PTZ camera guarding a hallway

with two entrances and a window. With patterns, you can set a bookmark for camera behavior that changes the

camera’s view from one of the three points of interest to another every 15 seconds.

7/18/2019 C5617M-A



Patterns that you create must be names as “PATTERNX ”, where the keyword PATTERN must be used (uppercase)

followed by a positive integer . For example, PATTERN5 .

NOTE: There are pre-configured patterns that cannot be created. You cannot create a Pattern by combining

existing Presets.

Like a preset, patterns are typically only relevant for IP cameras. The number of patterns that can be recorded and

activated is dependent on the Pelco device. For example, the 16X and 18X models of the Spectra IV can store only a

single pattern, while the 22X, 23X and 35X Spectra IV models can store up to eight patterns.

Normal Script

A general script consists of a group of commands that run over a set period of time. It is akin to a macro.

Creating a Preset





These steps will show you how to create a preset.



2. Now set up your Pelco IP camera with a combination of settings that you want to save.

For example, the IP camera’s current viewing position, iris setting, focus setting, zoom, and so on.

3. Then call the SetPreset method, passing in the desired name of the preset.

Depending on whether the preset already exists or not, it will either create a new one or modify an existing one by

that name.

C++ Example:

bool bSuccess = ptzControlWrapper.SetPreset("PRESET99");

C# Example:

Boolean bSuccess = managedPTZControl.SetPreset("PRESET99");

Updating an Existing Preset

To update an existing preset, just following the steps outlined in Creating a Preset , ensuring that you use the name

of the existing preset to modify as the parameter for the SetPreset method.

Creating a Pattern





This is just like creating a preset, except you will be saving more than one camera state.



2. Now set up your Pelco IP camera with a combination of settings that you want to save.

For example, the IP camera’s current viewing position, iris setting, focus setting, zoom, and so on.

3. Then call the StartPatternRecording method, passing in the desired name of the preset.

7/18/2019 C5617M-A



Depending on whether the pattern already exists or not, it will either create a new one or modify an existing one bythat name.

C++ Example:

bool bSuccess = ptzControlWrapper.StartPatternRecording("PATTERN99");

C# Example:

Boolean bSuccess = managedPTZControl.StartPatternRecording("PATTERN99");

4. At this point start performing the actions that you’d want your camera to remember as a pattern.

For example, if you have three points of interest you would first go to the first point of interest with a certain zoomand focus level. After waiting for some predetermined time, you then move the camera’s view into the second point

of interest which has a different zoom level and iris setting; and do the same for the final point of interest.

5. Finally, call the EndPatternRecording method, passing in the same pattern name as you did before.C++ Example:

bool bSuccess = ptzControlWrapper.EndPatternRecording("PATTERN99");

C# Example:

Boolean bSuccess = managedPTZControl.EndPatternRecording("PATTERN99");

Going to an Existing Preset





To move the device to a specific preset state, call the PTZ Control Wrapper’s GotoPreset method, passing in the

name of the preset.

The camera or device will move to the preset and then stop.

C++ Example:

bool bSuccess = ptzControlWrapper.GotoPreset("PRESET99");

C# Example:

Boolean bSuccess = managedPTZControl.GotoPreset("PRESET99");

Removing an Existing Preset



NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the methodsdescribed in this topic, there is an equivalent method in the PelcoAPIViewer API.

To remove an existing preset, call the PTZ Control Wrapper’s RemovePreset method, passing in the name of thepreset.

The preset will then be deleted.

C++ Example:

bool bSuccess = ptzControlWrapper.RemovePreset("PRESET99");

7/18/2019 C5617M-A



C# Example:

Boolean bSuccess = managedPTZControl.RemovePreset("PRESET99");

Updating an Existing Pattern

To update an existing pattern, just following the steps outlined in Creating a Pattern . Ensure that you use the nameof the pattern to modify as the parameter for both the StartPatternRecording and EndPatternRecordingmethods.

Executing an Existing Pattern





To run a a script, call the PTZ Control Wrapper’s RunPattern method, passing in the name of the script to run.

The script will continue to run until stopped by the user using the HaltPattern method, detailed Stopping a

Pattern Currently Being Executed on page 40.C++ Example:

bool bSuccess = ptzControlWrapper.RunPattern("PATTERN99");

C# Example:

Boolean bSuccess = managedPTZControl.RunPattern("PATTERN99");

Stopping a Pattern Currently Being Executed





If you want to stop a script that is currently running, call the PTZ Control Wrapper’s HaltPattern method, passingin the name of the script to stop.

C++ Example:

bool bSuccess = ptzControlWrapper.HaltPattern("PATTERN99");

C# Example:

Boolean bSuccess = managedPTZControl.HaltPattern("PATTERN99");

7/18/2019 C5617M-A


Chapter

4Events and Alarms

Overview



WARNING: The content in this section assumes that the default target installation directory was chosen

during installation.


For a list of the latest special issues and problems regarding the Event Arbiter library, visit http://pdn.pelco.com/

content/event-arbiter-library-issues .

For a list of the latest special issues and problems regarding the Event Manager, visit http://pdn.pelco.com/content/

event-manager-issues .

Events and alarms are essentially XML formatted messages triggered by Pelco products, when some particular criteria

is met. Specifically Pelco products, acting as event providers, send these events and alarms to their subscribers.Typically event providers are web services, while subscribers are software clients. For example, if an IP camera’s

MotionDetection service detected movement within a particular region in the video frame, it can send an event to all ofits subscribers such as a VMS.

Where Does the Pelco SDK Fit?The Pelco SDK provides you with two components for eventing: the Event Arbiter Library and the Event Manager. The

Event Arbiter Library and Event Manager both allow you to subscribe, unsubscribe, and renew subscriptions to events.

However there are differences between the two components. The Event Arbiter Library is the primary componentfor dealing with eventing. It is for users looking for the most flexibility and control. Conversely, the Event Manager

is a component that sits on top of the Event Arbiter Library. Its main purpose is to provide users with ease of use inexchange for decreased control.

Event Arbiter Library

The Event Arbiter Library allows you to either subscribe directly to a device’s web service events or indirectly; allowing

you to choose to subscribe to the particular web service from all devices providing the service.

Once a subscription is established, the software client just has to wait for an event to fire. The web service will direct

the event to your software client through the Pelco SDK. As for subscription renewals, it should be noted that the Event

http://pdn.pelco.com/content/event-manager-issues




http://pdn.pelco.com/content/event-arbiter-library-issues

http://pdn.pelco.com/content/event-arbiter-library-issues


7/18/2019 C5617M-A


617M-A | Events and Alarms

Arbiter Library now also handles subscription renewals automatically. You will no longer have to worry about renewingan event subscription.

Environment Pelco SDK Consequence

No System Manager Only direct device subscription available.

Not all event data will be parsed by Pelco SDK.

System Manager available; EventArbiter web serviceactive Able to subscribe to all devices at once that provide aspecific web service.

All event data is available and parsed.

System Manager available; EventArbiter web service

NOT active

Only direct device subscription is available.

Event Manager

The Event Manager represents a new tool for eventing and a new component within the Pelco SDK. The Event

Manager provides another abstraction on top of the Event Arbiter Library, and simplifies event operations even

further. It allows subscriptions to all available web services for all devices on a given network that fall under a specificcategory. To subscribe, all you have to provide is the event category. The categories are as follows:

• Alarm Array Configuration events• Relay Array Configuration events

• Motion Detection events

Environment Pelco SDK Consequence

No System Manager Does not apply -- can’t use Event Manager.

System Manager available; EventArbiter web service

active

Able to subscribe to all available web services that are

under a specified category via the SM EventArbiter web

service, in one subscription.

System Manager available; EventArbiter web serviceNOT active

All event data is available and parsed. If the SMEventArbiter web service is not active, however, or

if you choose not to use it, the EventManager library

will automatically subscribe to each individual device'sweb service in the specified category, resulting in many

subscriptions.

Event Arbiter Library Compared to Event Manager

Event Arbiter Event Manager

Harder to use, but with more options and flexibility. Easier to use, but not as flexible: the user only needsto choose the category of events he is interested in

receiving.

Does not require a System Manager. Requires a System Manager.

Able to subscribe to a single device’s web service using

either an IP address or UDN.

Able to subscribe to all instances of a particular

web service. That is, a user can subscribe to allMotionDetection web services for all devices with just one

request.

NOTE: For more Endura specific information, refer to the Appendix .

7/18/2019 C5617M-A


C5617M-A | Events and

What’s Ahead

This is a high level overview of what steps are needed for handling events.

1. Subscribe to the desired web service's events through the Event Arbiter Library or the Event Manager.

2. Create the method that will handle the event. Associate that method with the Event Arbiter Library instance’s event

handler. Wait for an event to occur (or trigger an event to test), then handle it.

3. When no longer interested in receiving events (or when finished testing), unsubscribe from the subscribed web

service.

Creating an Event Agent

NOTE: The related source code for this entry (for C++) can be found in the MyEventAgent header file, which

belongs to the Event Arbiter Library C++ sample project. The related source code for this entry (for C#) can be

found in the class MyEventAgentNet in the ManagedEventArbiterSample.cs file, which belongs to the

Event Arbiter Library C# sample project.

The main purpose of an EventAgent class is to deal with any incoming events that have been subscribed to by the

Event Arbiter.

To create your own EventAgent class, implement the NotifyEvent method in the IEventAgent interface.

NotifyEvent includes parameters for the response and the event.

Details of implementation are left to the user. However in the MyEventAgent sample class, we demonstrate basicfunctionality for accessing event related data.

C++ Example:

#ifndef MYEVENTAGENT_H #define MYEVENTAGENT_H #include "PelcoAPI/IEventAgent.h" using namespace PelcoAPI; class MyEventAgent : public IEventAgent { public: STDCALL MyEventAgent(); virtual STDCALL ~MyEventAgent(); void STDCALL NotifyEvent(const char * szResponse, const Event * pEvent); private: int m_nCounter; }; #endif

C# Example:

class MyEventAgentNet:PelcoAPI.IEventAgentNet { Int32 nCounter = 0; public void NotifyEvent(String sResponse, PelcoAPI.EventNet eventNet) { Console.Write("\nNotify EVENT {0}:\n", ++nCounter); Console.Write("\tUDN: {0}\n", eventNet.m_sUdn); Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);

Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime); Console.Write("\tType: {0}\n", eventNet.m_nType); Console.Write("\tFriendly Name: {0}\n", eventNet.m_sDeviceFriendlyName); if (eventNet.m_nType == 1) { Console.Write("\tAssociated Camera UDN: {0}\n", eventNet.m_sAssociateCameraUdn); for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++) { Console.Write("\tAlarm ID: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nId);

7/18/2019 C5617M-A



Console.Write("\t\tSeverity: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nSeverity); Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off")); } } else if (eventNet.m_nType == 2) { for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++) { Console.Write("\tAlarm ID: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nId); Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off")); } } else if (eventNet.m_nType == 4) { Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" : "Off")); } else if (eventNet.m_nType == 8) { Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" : "Off")); Console.Write("\tSeverity: {0}\n", eventNet.m_nVideoAnalyticsSeverity); } Console.Write("EVENT Details:\n{0}\n", sResponse); } }

Returning the Event Subscription URL

NOTE: The related source code for this entry can be found in main.cpp’s main function (for C++), or

Program.cs’s Main function (for C#), which belongs to the System Manager Wrapper C++ and C# sample

project.

1. Initialize the System Manager Wrapper.Refer to Initializing the System Manager Wrapper for details.

2. Call the System Manager Wrapper instance’s GetDeviceServiceAttribute method, passing in the following:

login ID

A result returned from a successful call to the UserLogin method.

target device’s Unique Device Name (UDN)

To retrieve a deviceUDN , cycle through the stored results of a GetDevices call within your

IDeviceStorage class instance. For details, refer to Querying Available Devices from the System Manager .

web service’s Service ID

A URN value found in the web service’s corresponding WSDL file.

attribute name of SYS_UpnpEventSubUrlpointer to the variable that will hold the result

PelcoAPI::xstring sEvntUrl;bSuccess = sm.GetDeviceServiceAttribute(loginId,"UUID:B11DBF247E984B9BB83B7E74497DE6CA","urn:schemas-pelco-com:service:MotionDetection:1","SYS_UpnpEventSubUrl", &sEvntUrl)

7/18/2019 C5617M-A



Initializing the Event Arbiter Library

Initializing the Event Arbiter Library for C++

NOTE: The related source code for this entry can be found in EventArbiterSample.cpp’s main function

which belongs to the Event Arbiter Library sample project. This assumes that you have already completed the

steps outlined in Creating an Event Agent .

1. Initialize the System Manager Wrapper.

Refer to Initializing the System Manager Wrapper for details.

2. Declare the Event Arbiter Library instance. Set the Event Arbiter Library instance's network location and port

number, using the System Manager’s IP address and port number.

Refer to Automatically Determining the System Manager’s IP Address and Port Number for more details.

PelcoAPI::IEventArbiter * pEventArbiter = new PelcoAPI::EventArbiter("10.220.196.187", "60001", true);

3. Set the Event Arbiter Library instance's network location and port number, using the local host IP address and portnumber.

pEventArbiter->SetupIPAndPort("10.220.196.200", "9716");

4. Register your Event Agent class with the Event Arbiter Library instance.

For details on creating an Event Agent, refer to Creating an Event Agent .

MyEventAgent agent;pEventArbiter->RegisterEventAgent(&agent);

Initializing the Event Arbiter Library for C#



A System Manager Is Available on Your Network

NOTE: The related source code for this entry can be found in ManagedEventArbiterSample.cs’s mainfunction, which belongs to the Event Arbiter Library C# sample project. This assumes that you have already

completed the steps outlined in Creating an Event Agent .



2. Initialize your implemented Event Agent.

Refer to Creating an Event Agent for details.

MyEventAgentNet pAgent = new MyEventAgentNet();

3. Next, declare the Event Arbiter Library instance. Set the following parameters:

Event Arbiter Library instance's network location and port number

The client machine where it resides.

Your implemented Event Agent to register

The System Manager’s IP address and port number.

Refer to Automatically Determining the System Manager’s IP Address and Port Number for moredetails.

boolean

True to force the EventArbiter library to use the System Manager, false otherwise.

PelcoAPI.EventArbiterNet pEventArbiter = new PelcoAPI.EventArbiterNet("10.220.196.200", "9716", pAgent, "10.220.196.187", "60001", true);

7/18/2019 C5617M-A



A System Manager Is Not Available on Your Network







Use empty strings for parameters representing the System Manager’s IP address and port number.

Set the last parameter to false.

Explicitly not rely on the System Manager‘s EventArbiter service.

PelcoAPI.EventArbiterNet pEventArbiter = new PelcoAPI.EventArbiterNet("10.220.196.200", "9716", pAgent, "", "", false);

Initializing the Event Manager

The related source code for this entry (for C++) can be found in EventManagerSample.cpp’s main function, which

belongs to the Event Manager Library C++ sample project. The related source code for this entry (for C#) can be foundin the ManagedEventManagerSample.cs’s main function, which belongs to the Event Manager C# sample project.

This assumes that you have already completed the steps outlined in the Creating an Event Agent . These steps also

require the existence of a System Manager on your network.





MyEventAgentNet pAgent = new MyEventAgentNet();





The System Manager’s IP address and port number.

Refer to Automatically Determining the System Manager’s IP Address and Port Number for moredetails.

boolean

True to force the EventArbiter library to use the System Manager, false otherwise.

C++ Example:

MyEventAgent agent;PelcoAPI::IEventManager * pEventManager = new PelcoAPI::EventManager(

"10.220.196.200", "9716", &agent, false, "10.220.196.187", "60001");

C# Example:

PelcoAPI.EventManagerNet pEventManager = new PelcoAPI.EventManagerNet("10.220.196.200", "9716", pAgent, false, "10.220.196.187", "60001");

7/18/2019 C5617M-A



Device or Service Specific Subscriptions

If you want to subscribe to events from a specific web service or device, then this section will show you the most

common scenarios.

Using the Event Arbiter Library to Subscribe Using the Device’s IP Address

NOTE: This entry is relevant for users who are not relying on either the System Manager or its EventArbiterservice. The related source code for this entry can be found in EventArbiterSample.cpp’s main function

(for C++) or ManagedEventArbiterSample.cs’s main function (for C#), which belongs to the Event Arbiter

Library sample project.

This topic describes how to use the Event Arbiter Library to subscribe to a specific device’s particular web service

using the device’s IP address. Having an event subscription simply tells a device that you would like to receive its

event notifications. To request a event subscription, the following must be done:

1. Initialize the Event Arbiter Library.

Refer to Initializing the Event Arbiter Library for details.

2. Call the Event Arbiter wrapper instance's SubscribeToEvents method (SubscribeEvents in C#), passing the

event subscription URL.

For details, refer to Returning the Event Subscription URL. If the request was successful, the method will return

the event subscription's unique ID which will allow users to either renew or unsubscribe the event subscription. Ifunsuccessful, the method returns NULL.

NOTE: Pelco SDK now automatically handles subscription renewals.

C++ Example:

const char * szSid_1 = pEventArbiter->SubscribeToEvents("http://10.220.196.184:80/event/AlarmArrayConfiguration-1");

C# Example:

String strSid_1 = pEventArbiter.SubscribeEvents("http://10.220.196.184:80/event/AlarmArrayConfiguration-1”);

Using the Event Arbiter Library to Subscribe Using the Event Subscription URL

This topic describes how to use the Event Arbiter Library to subscribe to a specific device’s particular web service

using the Event Subscription URL.

NOTE: This entry is ONLY relevant for users who use an Endura network, specifically with an

active System Manager and an enabled EventArbiter service on the System Manager. The related

source code for this entry can be found in EventArbiterSample.cpp’s main function (for C++) or

ManagedEventArbiterSample.cs’s main function (for C#), which belongs to the Event Arbiter Library

sample project.



2. Construct an event service ID.

It consists of the device’s UDN and the web service’s URN, which is its namespace on its WSDL file. (For detailson determining a web service’s ID, refer to Returning the Event Subscription URL.)

C++ Example:

std::string strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/urn:pelco-com:serviceId:AlarmArrayConfiguration-1";

C# Example:

String strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/urn:pelcocom:serviceId:AlarmArrayConfiguration-1";

7/18/2019 C5617M-A



3. Call the Event Arbiter Library instance's SubscribeToEvents method (SubscribeEvents in C#), passing theevent service ID.

If the request was successful, the method will return the event subscription's unique ID which will allow users to

either renew or unsubscribe the event subscription.


C++ Example:

const char * szSid_1 = pEventArbiter->SubscribeToEvents(strEventServiceId.c_str());

C# Example:

String strSid_1 = pEventArbiter.SubscribeEvents(strEventServiceId);

Using the Event Arbiter Library to Subscribe to All Instances of a Service

NOTE: This entry is ONLY relevant for users who use an Endura network, specifically with an

active System Manager and an enabled EventArbiter service on the System Manager. The related

source code for this entry can be found in EventArbiterSample.cpp’s main function (for C++) or

ManagedEventArbiterSample.cs’s main function (for C#), which belongs to the Event Arbiter Library

sample project.

If you want to subscribe to all devices that provide a specific web service like MotionDetection (or any other web

service that has events), do the following:



2. Construct an event URN.

It is essentially the SOAP web service URN. You can determine this URN value looking at the web service’s

associated WSDL file (it should be near the top of the file).

C++ Example:

std::string strEventUrn = "urn:schemas-pelco-com:service:MotionDetection:1";

C# Example:

String strEventUrn = "urn:schemas-pelco-com:service:MotionDetection:1";

3. Call the Event Arbiter wrapper instance's SubscribeToEvents method (SubscribeEvents in C#), passing theevent URN.

If the request was successful, the method will return the event subscription's unique ID which will allow users toeither renew or unsubscribe the event subscription.


C++ Example:

const char * szSid_1 = pEventArbiter->SubscribeToEvents(strEventUrn.c_str());

C# Example:

String strSid_2 = pEventArbiter.SubscribeEvents(strEventUrn);

Using the Event Arbiter Library to Unsubscribe from a Service

NOTE: The related source code for this entry can be found in EventArbiterSample.cpp’s main function

(for C++) or ManagedEventArbiterSample.cs’s main function (for C#), which belongs to the Event Arbiter

Library sample project. This entry assumes that the user has already completed the steps outlined in any of

the Event Arbiter subscription-related entries.

7/18/2019 C5617M-A



To unsubscribe from an existing event subscription, call the Event Arbiter wrapper instance's

UnSubscribeToEvents method (UnsubscribeEvents in C#), passing the subscription identifier.

You should receive subscription IDs on successful calls to SubscribeToEvents. If the request was successful,

the method will return a 1 (for C++) or true (for C#). Otherwise it will return a 0 (for C++) or false (for C#).

C++ Example:

const char * szSid_1 = pEventArbiter->SubscribeToEvents("urn:schemas-pelco-com:service:MotionDetection:1");

// ... misc logic ...pEventArbiter->UnSubscribeToEvents(strSid_1);

C# Example:

String strSid_1 = pEventArbiter.SubscribeEvents("urn:schemas-pelco-com:service:MotionDetection:1");// ... misc logic ...Boolean ret = pEventArbiter.UnsubscribeEvents(strSid_1);

Mass Subscriptions by Category

If you don’t really know what particular events or devices where you would like a subscription, then this section is for

you. It will show you how to subscribe to all events that fall under your desired category.

Using the Event Manager to Subscribe to All Services

NOTE: The related source code for this entry can be found in EventManagerSample.cpp’s main function

(for C++) or ManagedEventManagerSample.cs’s main function (for C#), which belongs to the Event

Manager Library sample project. Also note that the Event Manager requires the presence of a System

Manager on the network.

The following steps will allow you to subscribe to all events that fall under one of several categories defined by the

Pelco SDK.

1. Initialize the Event Manager.

Refer to Initializing the Event Manager for details.

2. Call the Event Manager instance's Start method, passing the desired event type as defined by the Pelco SDK.The Event Manager will now start ‘listening’ to events. Use one or more of the following options (you can addseveral of these values together to subscribe to more than one category of event at a time):

C++ Example:

enum EventType { EVENT_TYPE_UNKNOW = 0x00000000,EVENT_TYPE_ALARM_ARRAY_CONFIGURATION = 0x00000001,EVENT_TYPE_RELAY_ARRAY_CONFIGURATION = 0x00000002,EVENT_TYPE_MOTION_DETECTION = 0x00000004,EVENT_TYPE_MASK = 0x0000001F };

C# Example:

enum REGISTER_EVENTS { ALARM_ARRAY = 0x00000001, RELAY_ARRAY = 0x00000002, MOTION_DETECTION = 0x00000004, }

Alarm Array Configuration

Events that are related to the AlarmArrayConfiguration web service, such as an alarm circuitconnected to the camera has been turned on or off.

7/18/2019 C5617M-A



Relay Array Configuration

Events that are related to the RelayArrayConfiguration web service.

Motion Detection

Events that are related to the MotionDetection web service, such as the camera started or stopped

detecting motion.

Unknown

This is a system-reserved value and can be disregarded.

Mask

A system-reserved value that combines all the different event categories, allowing you to subscribeto all of them at once.

NOTE: Always refer to the EventArbiterDefs header for the latest options. If the request was successful,

the method will return true; false otherwise.

C++ Example:

bool ret = pEventManager->Start(PelcoAPI::EVENT_TYPE_MASK);

C# Example:

Boolean ret = pEventManager.Start(REGISTER_EVENTS.EVENT_TYPE_MASK);


Using the Event Manager to Unsubscribe from All Services

NOTE: The related source code for this entry can be found in EventManagerSample.cpp’s main function

(for C++) or ManagedEventManagerSample.cs’s main function (for C#), which belongs to the Event

Manager Library sample project. Also note that the Event Manager requires the presence of a System

Manager on the network. This entry assumes that the user has already completed the steps outlined in the

Event Manager subscription-related entry.

To unsubscribe from an existing event subscription for Event Manager, call the Event Manager instance’s Stopmethod.

If successful it will return true, false otherwise. The following example unsubscribes from all active event

subscriptions at once.

C++ Example:

bool ret = pEventManager->Stop();

C# Example:

Boolean ret = pEventManager.Stop();

Handling Incoming Events

NOTE: The related source code for this entry can be found in MyEventAgent.cpp’s NotifyEvent function

(for C++), or the NotifyEvent function in the class MyEventAgentNet (for C#), which belongs to the EventArbiter Library sample project. The availability of some data is dependent on the availability of a System

Manager on your network, that is, if a System Manager is not online, then some event data will be missing.

The Pelco SDK already parses event related data for you. All that is required is for you to figure out how to use our

provided Event struct.

1. Define a class that implements the EventAgent interface.

For details, refer to Creating an Event Agent .

2. Within your EventAgent implementation is the NotifyEvent method.

7/18/2019 C5617M-A



This is where you will process any incoming event notifications. Events will be represented by the Event struct asdefined in the EventArbiterDefs header. (The raw event XML string data will be encapsulated by the parameter.)

Common to most events are the following attributes (listed below respectively):

• Device UDN, web service ID

• The timestamp in UTC

• The event type as defined by the Pelco SDK

• The device’s friendly name

C++ Example:

void MyEventAgent::NotifyEvent(const char * szResponse, const Event * pEvent) { //... other logic ... pEvent->m_strUdn.c_str(); pEvent->m_strServiceId.c_str(); pEvent->m_strUtcEventTime.c_str(); pEvent->m_nType; pEvent->m_strDeviceFriendlyName.c_str();

C# Example:

Int32 nCounter = 0; public void NotifyEvent(String sResponse, PelcoAPI.EventNet eventNet) { Console.Write("\nNotify EVENT {0}:\n", ++nCounter); Console.Write("\tUDN: {0}\n", eventNet.m_sUdn); Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId); Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime); Console.Write("\tType: {0}\n", eventNet.m_nType); Console.Write("\tFriendly Name: {0}\n", eventNet.m_sDeviceFriendlyName);

If the incoming event is an alarm from the AlarmArrayConfiguration web service, it will provide information onthe camera it is associated with as well as general alarm data.

C++ Example:

if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION) { //the camera associated to this event pEvent->m_strAssociateCameraUdn.c_str(); for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size(); i++) { //alarm ID pEvent->m_alarmOrRelayInfo[i]->m_nId; //alarm severity pEvent->m_alarmOrRelayInfo[i]->m_nSeverity; //the state of the alarm 0 off 1 on pEvent->m_alarmOrRelayInfo[i]->m_bState;

} }

C# Example:

if (eventNet.m_nType == 1) { Console.Write("\tAssociated Camera UDN: {0}\n", eventNet.m_sAssociateCameraUdn); for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++) { Console.Write("\tAlarm ID: {0}\n",

7/18/2019 C5617M-A



eventNet.m_alarmOrRelayInfo[i].m_nId); Console.Write("\t\tSeverity: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nSeverity); Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off")); } }

If the incoming event is an alarm from the RelayArrayConfiguration web service, it will provide as general

relay data such as the relay ID and whether or not it is enabled.C++ Example:

if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_RELAY_ARRAY_CONFIGURATION) { for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size(); i++) { pEvent->m_alarmOrRelayInfo[i]->m_nId; pEvent->m_alarmOrRelayInfo[i]->m_bState; } }

C# Example:

else if (eventNet.m_nType == 2) { for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++) { Console.Write("\tAlarm ID: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nId); Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off")); } }

If the incoming event is from the MotionDetection web service, it will show whether or not the motion detection

region is active or inactive.

C++ Example:

if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_MOTION_DETECTION) { pEvent->m_bAlarmState; }

C# Example:

else if (eventNet.m_nType == 8) { Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" : "Off")); Console.Write("\tSeverity: {0}\n",

eventNet.m_nVideoAnalyticsSeverity); }

The szResponse parameter contains the raw event data in XML format. This is useful for debugging, or XML data

binding to your classes.

C++ Example:

TRACE_INFO("EVENT Details: \n%s\n", szResponse);

7/18/2019 C5617M-A



C# Example:

Console.Write("EVENT Details:\n{0}\n", sResponse);

Polling Events

NOTE: The related source code for this entry can be found in EventArbiterSample.cpp's main function

(for C++) or ManagedEventArbiterSample.cs's Main function (for C#), which belongs to the Event Arbiter

Library sample project. The availability of some data is dependent on the availability of a System Manager on

your network, that is, if a System Manager is not online, then some event data will be missing.

This API allows you to poll events instead of having to perform a callback.

1. Set the EventAgent to NULL in the RegisterEventAgent method.C++ Example:

pEventArbiter->RegisterEventAgent(NULL);

C# Example:

MyEventAgentNet pAgent = null;

2. To poll events one by one using Event Arbiter or Event Manager, call the Event Arbiter or Event Managerinstance's PollEvent method.

std::string strRawEvent;PelcoAPI::Event pelcoEvent// Additional logic...if (pEventArbiter->PollEvent(strRawEvent, pelcoEvent))// ...

String sRawEvent = "";PelcoAPI.EventNet pelcoEvent = null;// Additional logic...if (pEventManager.PollEvent(ref sRawEvent, ref pelcoEvent))// ...

7/18/2019 C5617M-A



7/18/2019 C5617M-A


Chapter

5Extracting Audio and Video Metadata

Extracting Audio and Video Metadata




installation.


There will always be special situations, such as custom video analytics, that call for processing video meta-data like

timestamps.


The Meta-data Parser is a utility for parsing Pelco Video Elementary Stream (VES) meta-data from Pelco streams.

Pelco VES frames contain the following meta-data:

• MotionDetection active areas

• Timestamps

• Pelco Analytics drawing primitives

• RSA Signature and other information necessary to verify the frame

The Meta-data Parser consists of an interface that provides access to the various objects within the elementary

stream.


7/18/2019 C5617M-A


617M-A | Extracting Audio and Video Metadata

Motion Detection Metadata

Motion detection involves computing the difference between two images. If the difference between the comparedimages crosses a certain threshold value, then motion is detected and the selected Alert is triggered.

The key to Pelco’s motion detection feature is the Region of Interest (ROI). The ROI denotes a motion detection regionwithin a video frame. A motion detection region is essentially a grid of motion detection 16x16 pixel cell blocks. These

cells have sensitivity and movement threshold limits. The sensitivity level dictates the amounts of movement that are

registered within the ROI, while the threshold dictates the amounts of blocks that are registered within the ROI beforethe selected alarm is triggered.

What motion detection metadata is available? Currently in terms of metadata, each video frame can only hold a singleROI. Consequently, for each frame, the metadata describes the length and width of the ROI, while also holding a Pelco

base64 bit mask for the state of the ROI.

NOTE: The difference between Pelco base64 and standard base64 implementations is that the Pelco version

always appends an = character at the end of the encoded value.

Pelco Analytics Drawing Primitives

Drawing primitives are basic graphical elements. They encompass drawing points, fills, lines, arcs, and even text. This

basically contains information related to the points, lines, arcs, and so on.

Timestamps

Timestamp metadata represents the exact date and time when the video frame was captured. The Metadata Parser

Library can return this data in a number of ways.

struct timeval

The timestamp represented as a struct timeval.

tv_sec

The time interval in seconds since the epoch.

tv_usec

The time interval in microseconds since the epoch.

typedef struct timeval {long tv_sec;long tv_usec;} timeval;

struct tm

The timestamp represented as a struct tm.

tv_sec

The time interval in seconds. (0-59)

7/18/2019 C5617M-A


C5617M-A | Extracting Audio and Video Me

tv_min

The time interval in minutes. (0-59)

tv_hour

The time interval in hours. (0-23)

tv_mday

The time interval in day of the current month. (1-31)

tv_mon

The time interval in months since January. (0-11)

tv_year

The time interval in years since 1900.

tv_wday

The time interval in days since Sunday. (0-6)

tv_yday

The time interval in days since January 1st. (0-365)

tv_isdst

A boolean that is true if it is currently daylight savings time, false otherwise.

typedef struct tm {

int tm_sec;int tm_min;int tm_hour;int tm_mday;int tm_mon;int tm_year;int tm_wday;int tm_yday;int tm_isdst;}

In addition to returning the data above, the Metadata Parser Library also returns the daylight savings offset, the currenttimezone, and values in local time.

Getting Started

For more information about getting started and setting up the working directory, refer to Setting Up Sample Projects .

Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug version,

change the Working Directory value as appropriate. Assuming that you did not change the default installation directoryfor the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Release to use the production version of the

Pelco SDK libraries. Conversely, use C:\\Program Files\Pelco\API\Libs\Debug to use the debug version of

the Pelco SDK libraries.

What’s Ahead

This is a high level overview of possible tasks related to metadata:

1. Access the metadata from the stream.

2. Render metadata onto a video frame.

Initializing the Metadata Parser Class


the Metadata Parser C++ sample project.

1. Create a MetaDataParser instance.

7/18/2019 C5617M-A



2. Call its SetData method, passing the buffer containing the data to analyze and the buffer length as parameters.

PelcoAPI::MetaDataParser parser;parser.SetData(videoBuffer, length);

Creating a Metadata Renderer Class

NOTE: The related source code for this entry can be found in SampleMetaDataRenderer.cpp, whichbelongs to the MetaDataParser C++ sample project. You are expected to implement the actual logic.

This class is used for drawing onto video frames.

1. Implement the following required protected methods:

a) DrawLine to draw a line using two given points: 'v1' and 'v2'

virtual void DrawLine(const PelcoAPI::VECTOR &v1, const PelcoAPI::VECTOR &v2,PelcoAPI::COLOR color) throw();

b) DrawRectangle to draw a rectangle whose upper left corner is determined by the parameter v1, while the

lower right corner is determined by the parameter v2. If the fill parameter is set to true, the rectangle should besolid. Otherwise, it should only be an outline.

virtual void DrawRectangle(const PelcoAPI::VECTOR &v1, const PelcoAPI::VECTOR &v2,PelcoAPI::COLOR color, bool fill) throw();

c) DrawPolygon to draw a polygon with corners defined within the Vector array. If the fill parameter is set to true,the polygon should be solid. Otherwise, it should only be an outline.

virtual void DrawPolygon(PelcoAPI::VECTOR *vectors, unsigned intcount,PelcoAPI::COLOR fillColor, PelcoAPI::COLOR borderColor, bool fill) throw();

d) DrawText

virtual void DrawText(const std::string &text, const PelcoAPI::VECTOR &location,PelcoAPI::COLOR color) throw();

2. (Optional) Implement the following protected methods:

a) BeginDraw to perform any pre-drawing work.

virtual void BeginDraw() throw();

b) EndDraw to perform any post-drawing work.

virtual void EndDraw() throw();

c) TransformVectorForDisplay to handle point translation and scaling.

virtual PelcoAPI::VECTOR TransformVectorForDisplay(const PelcoAPI::VECTOR &v)throw();

Retrieving the Current Timestamp Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessTimestamp function,

which belongs to the Metadata Parser C++ sample project.

1. Initialize the MetaDataParser.

For details, refer to Initializing the Metadata Parser Class .

7/18/2019 C5617M-A



2. Verify whether the parser has found a timestamp by calling the HasTimeStamp method, which will return true iffound, false otherwise.

if(true == parser.HasTimestamp()){

3. If there is a timestamp, call the GetTimeStampAsString method, passing in a local time Boolean parameter,which if true returns the timestamp in local time, while false returns the UTC value:

std::string timestamp = parser.GetTimestampAsString(true, "%c");

Motion Detection Metadata

Retrieving Motion Detection Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessMotionData function,


1. Initialize the MetaDataParser. For details, refer to Initializing the Meta-Data Parser Class .

2. Check if the parser has found motion detection data by calling the HasMotionData method, which will return

true if found, false otherwise.

if(true == parser.HasMotionData()){

3. If there is motion detection metadata, call the GetMotionData method and pull the result into a new MotionDatainstance.

PelcoAPI::MotionData *data = parser.GetMotionData();

4. Parse the resulting data from the MotionData instance.

if(NULL != data){unsigned int cols = data->Columns();unsigned int rows = data->Rows();unsigned char *mask = data->Bitmask(); // Do something with the data here

// Delete the motion data object

Rendering Motion Detection Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessMotionData function,


NOTE: This entry assumes that the user has already completed the steps outlined in Creating a Metadata

Renderer Class .


2. Check if the parser has found motion detection data. Call the HasMotionData method, and if true, retrieve themotion metadata.

if(true == parser.HasMotionData()){ PelcoAPI::MotionData *data = parser.GetMotionData();

3. After you retrieve the motion detection metadata, declare your MetaDataRenderer class.

SampleMetaDataRenderer renderer;

7/18/2019 C5617M-A



4. Create a new COLOR struct, setting the desired alpha transparency and colors to display on the screen. In thisexample, the colors (red, green, blue) are fully opaque with zero transparency.

PelcoAPI::COLOR color = {255,0,128,255};

5. Render the motion metadata onto the screen by calling the RenderMotionData method.

renderer.RenderMotionData();

Drawing Metadata

Retrieving Drawing Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessDrawingData function,



2. Determine if the parser has found drawing data by calling the HasDrawingData method, which will return true if

found, false otherwise.

if(true == parser.HasDrawingData()){

3. If drawing metadata is found, call the GetDrawingData method, pulling the result into a DrawingData instance.

PelcoAPI::DrawingData *data = parser.GetDrawingData();

4. Parse the resulting data by iterating through the returned drawing primitives.

PelcoAPI::DrawingPrimitive *primitive = data->GetNextPrimitive();;while(primitive != NULL){primitive->GetPrimitiveType();PelcoAPI::DrawingPrimitive::FreePrimitive(primitive);primitive = data->GetNextPrimitive();}

Rendering Drawing Metadata

NOTE: The related source code for this entry can be found in main.cpp’s RenderDrawingData function,


This entry assumes that the user has already completed the steps outlined in Creating a Metadata Renderer Class .

1. Iinitialize the MetaDataParser. For details, refer to Initializing the Metadata Parser Class .

2. Determine if the parser has found drawing data by calling the HasDrawingData method, and if true, retrieve thedrawing metadata by calling the GetDrawingData.

if(true == parser.HasDrawingData()){ PelcoAPI::DrawingData *data = parser.GetDrawingData();

3. After you grab the drawing metadata, declare your MetaDataRenderer class.

SampleMetaDataRenderer renderer;

4. Create a new COLOR struct, setting the desired alpha transparency and colors to show on the screen. In this

example, the colors (red, green, and blue) are fully opaque with zero transparency.

PelcoAPI::COLOR color = {255,0,128,255};

5. Render the drawing metadata onto the screen by calling the RenderDrawingData method.

renderer.RenderDrawingData();

7/18/2019 C5617M-A



7/18/2019 C5617M-A


Chapter

6Exporting Video

Overview



NOTE: The content in this section assumes that the default target installation directory was chosen during

installation.


At some point, you’ll need to export your video into a variety of major formats.


The Exporter module is a Pelco API SDK component that can export playback video, and save it in either AVI, MP4,3GP, or PEF format. It is multi-threaded to help ensure good performance and to export as many streams as possible

at any given time. Moreover, users will be able to export or playback saved streams without having to initialize thestream. Consequently it provides the flexibility to specify the camera, the start time and an end time value. This

tool is also able to embed meta-data (timestamp, and so on) into streams (this requires transcoding which affectsperformance and authentication). When available, audio will be included in the export in either PEF or AVI format.

Custom Application Development

Using the Exporter, a simple application can be written to select, initiate, and receive these streams to save them to

a video file. The most common file format for such video files is AVI. However, AVI is only a container format, not acompression format. From this point forward, there are two principally different implementations for video storage: re-

coding and native.

Re-coding Video

To avoid a complicated process, decoding and re-encoding is often employed to allow the video to be played back

using the standard codecs provided with the Windows Media Player.

The native video format is either MPEG-4 or H.264, depending on the camera settings. If the video stream coming

from the camera is encoded using MPEG-4, the exported file will generally use MPEG-4 as well. No re-coding will be

necessary unless you add overlays to the export. If the video stream coming from the camera is encoded using H.264,the exported file may use H.264 or MPEG-4, depending on the container format (3GP, AVI, MP4, PEF) and whether

you add overlays to the export. (There is relatively little difference in size between container formats and compression

formats.)

By default, Windows Media Player supports MPEG-4, but not H.264. VLC supports both MPEG-4 and H.264.

Native Video

For recording large amounts of video data, such as when building near line storage solutions, storage in the original (or

native) format is essential as it preserves the bit rate. To play back these native video files, a codec that supports the

full ISO MPEG-4 standard (or at least the ISO MPEG4 SP profile) must be installed in the end user's media player. If


7/18/2019 C5617M-A


617M-A | Exporting Video

a codec does not support the ISO MPEG-4 SP profile, the video received from the Endura system will not play back.

Fortunately there are many complete ISO MPEG-4 codecs available; ranging from free, open source versions to highly

optimized commercial versions

Getting Started


What’s Ahead

This is a high level overview of possible tasks related to export.

1. Set up desired video clips to export.

• Configure desired parameters for each video clip to export.

• If overlays are desired, set up overlays for each video clip.

2. Start the export, and continue to poll its status until it finishes successfully or encounters an error.

Initializing the Exporter

The related source code for this entry (for C++) can be found in main.cpp’s main function, which belongs to the

Export C++ sample project. The related source code for this entry (for C#) can be found in Program.cs’s Mainfunction, which belongs to the Export C# sample project.



Create the EnduraExporter instance, and then call its Setup method, passing the following:

The location of the plugins directory.

The plugin directory contains components that are key to the SDK’s encoding, decoding, andtranscoding capabilities. Without a proper reference, key features of the Pelco SDK may not function

properly. Assuming that you didn’t change the default target installation directory, it can be foundhere: C:\Program Files\Pelco\API\Libs\Debug\Plugins\ (if running in debug mode) or

here: C:\Program Files\Pelco\API\Libs\Release\Plugins\ (release mode).

The System Manager’s IP address.

For details on the importance of the System Manager for the Exporter, refer to Video Exports in the

Appendix.

The IP Address to use for receiving incoming stream(s)

The client machine using the Pelco SDK.

(Optional) The name of the user that is performing the export.

(Optional) The initial local port to use for the export.

NOTE: If you are running simultaneous exports, you must provide different portvalues.

(Optional) The end port to use if initial port is in use.

The exporter will keep increasing port numbers starting with the initial port number until the end port

is reached.

C++ Example:

PelcoAPI::EnduraExporter exporter;exporter.Setup("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins", "10.220.196.187", "10.220.196.189", USERNAME, 8000, -1);

C# Example:

PelcoAPI.EnduraExporterNet pEnduraExporterNet = new PelcoAPI.EnduraExporterNet();pEnduraExporterNet.Setup("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins",

7/18/2019 C5617M-A


C5617M-A | Exporting

"10.220.196.187", "10.220.196.189", USERNAME, 8000, -1);

Setting Up Overlay Data on Video to Be Exported


Export C++ sample project. The related source code for this entry (for C#) can be found in Program.cs’s Main

function, which belongs to the Export C# sample project.

NOTE: This entry assumes that you are already familiar with the content in Exporting Video .

NOTE: If you choose to embed overlays with your video export, regardless of input source stream’s format,

the resulting exported file will be in MPEG-4 format.

1. First decide on what type of overlay that you would like to create.

There are several types as defined in the EnduraExporterDefines header file:

enum OverlayType { OVERLAY_TYPE_TIMESTAMP = 0, OVERLAY_TYPE_CAMERANAME = 1, OVERLAY_TYPE_TEXTSTRING = 2, OVERLAY_TYPE_PICTURE = 3

};

2. Next, create the overlay structure.

• If performing a single video clip export as described in Exporting A Single Video Clip , the user must use the

OverlayData method for each desired overlay type before starting the export.

exporter.OverlayData(PelcoAPI::OVERLAY_TYPE_TIMESTAMP,PelcoAPI::OVERLAY_LOCATION_BOTTOM_LEFT, NULL, FONTNAME, 10,fontColor, fontBgColor, 0);

pEnduraExporterNet.OverlayData(PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP,PelcoAPI.OverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT, "",FONTNAME, 10, FONTCOLOR, FONTBGCOLOR, 0, DATEFORMAT,TIMEFORMAT);

• If performing a stitched video clip export described in Stitching Multiple Clips Into a Single Video Export , theuser must use an OverlayInfo / OverlayInfoNet instance for each overlay type wanted before starting the

export.

exportInfo[i].overlayInfo = newPelcoAPI::OverlayInfo[overlayNum]; exportInfo[i].overlayInfo[0].type =PelcoAPI::OVERLAY_TYPE_TIMESTAMP; // configure other parameters for the 1st overlay

PelcoAPI.OverlayInfoNet overlayInfo_0 = newPelcoAPI.OverlayInfoNet(); overlayinfo_0.type =PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP; // configure other parameters for the 1st overlay

OverlayData Parameters

OverlayData contains the following parameters. (Note that PPX export does not currently support overlays.)

timestamp

The overlay displays a timestamp that provides the time in local time.

cameraname

7/18/2019 C5617M-A



The overlay displays a camera’s name. Typically the camera name displayed is the source of the

video stream.

textstring

The overlay displays text that the user specifies.

picture

The overlay displays a picture that the user specifies.

Now create a new instance of OverlayInfoNet and, based on the type of overlay you chose, simply start assigning

the desired values with it such the font to use, the color of the font, the location of the overlay, and so on.

The following is a list of other overlay settings (some may or may not apply to certain overlay types as noted):

location

The general screen location of the overlay. (Refer to the DataMixerPluginDefines header for the

latest definition of OverlayLocation.)

enum OverlayLocation { OVERLAY_LOCATION_UNKNOWN, OVERLAY_LOCATION_TOP_LEFT, OVERLAY_LOCATION_TOP_MIDDLE, OVERLAY_LOCATION_TOP_RIGHT, OVERLAY_LOCATION_CENTER, OVERLAY_LOCATION_BOTTOM_LEFT,

OVERLAY_LOCATION_BOTTOM_MIDDLE, OVERLAY_LOCATION_BOTTOM_RIGHT,OVERLAY_LOCATION_COORDINATE};

unknown

This denotes that the overlay will not appear on the screen.

top_left

The overlay will appear in the top left corner of the screen.

top_middle

The overlay will appear in the top of the screen.

top_right

The overlay will appear in the top r ight corner of the screen.center

The overlay will appear in the center of the screen.

bottom_left

The overlay will appear in the bottom left corner of the screen.

bottom_middle

The overlay will appear in the bottom of the screen.

bottom_right

The overlay will appear in the bottom right corner of the screen.

coordinate

This is a system reserved value. Please disregard this value.

value

The actual value to display. For picture overlays, this is the full path to the picture to display. Whilefor cameraname overlays, this is the name of the camera. Finally for textstring overlays, this is just

the alphanumeric value to display on the overlay. (This does not apply to timestamp overlays.)

fontName

This is the name of an available font to use for displaying overlays. (This does not apply to picture

overlays. )

fontSize

This is the size of a font. (This does not apply to picture overlays .)

7/18/2019 C5617M-A



fontColor

This is the color of a font. (This does not apply to picture overlays.)

fontBgColor

This is the font’s color. (This does not apply to picture overlays.)

pictureOpacity

The opacity of the overlay. This ranges from transparent (0% opacity) to solid (100% opacity). (This is only relevant for picture overlays.)

dateFormat

This is only relevant to the timestamp overlay.

enum DateFormat { DATE_FORMAT_MDYYYY = 0,DATE_FORMAT_MDYY = 1,DATE_FORMAT_MMDDYY = 2,DATE_FORMAT_MMDDYYYY = 3,DATE_FORMAT_YYMMDD = 4,DATE_FORMAT_YYYY_MM_DD = 5,DATE_FORMAT_DD_MM_YY = 6,DATE_FORMAT_DMYY = 7,DATE_FORMAT_DDMMYY = 8,DATE_FORMAT_DMYYYY = 9,DATE_FORMAT_DDMMYYYY = 10,DATE_FORMAT_YYMD = 11,DATE_FORMAT_YYYYMD = 12,DATE_FORMAT_YYYYMMDD = 13,DATE_FORMAT_YYYY_M_D = 14,};

mdyyy

This date format conforms to the following structure: m/d/yyyy (month/day/year), where both 'm' and

'd' could be either one or two digits, for example, 12/8/2001 or 2/23/2001

mdyy

This date format conforms to the following structure: m/d/yy (month/day/year), where both 'm' and 'd'could be either one or two digits, for example, 12/8/01 or 2/23/01

mmddyyThis date format conforms to the following structure: mm/dd/yy. (month/day/year), for example,02/23/01

mmddyyyy

This date format conforms to the following structure: mm/dd/yyyy (month/day/year), for example,02/23/2001

yymmdd

This date format conforms to the following structure: yy/mm/dd (year/month/day), for example,

01/02/23

yyyy_mm_dd

This date format conforms to the following structure: yyyy_mm_dd (year_month_day), for example,

2001-02-23

dd_mm_yy

This date format conforms to the following structure: dd_mm_yy (day_month_year), for example,

02-23-01

dmyy

This date format conforms to the following structure: d/m/yy (day/month/year), where both 'm' and 'd'could be either one or two digits, for example, 23/2/01 or 8/12/01

ddmmyy

This date format conforms to the following structure: dd/mm/yy (day/month/year), for example,08/12/01 or 23/02/01

7/18/2019 C5617M-A



dmyyyy

This date format conforms to the following structure: d/m/yyyy (day/month/year), where both 'm' and

'd' could be either one or two digits, for example, 23/2/2001 or 8/12/2001

ddmmyyyy

This date format conforms to the following structure: dd/mm/yyyy (day/month/year), for example,

21/03/2001

yymd

This date format conforms to the following structure: yy/m/d (year/month/day), where both 'm' and 'd'could be either one or two digits, for example, 54/1/31 or 73/12/1

yyyymd

This date format conforms to the following structure: yyyy/m/d (year/month/day), where both 'm' and'd' could be either one or two digits, for example, 1954/1/31 or 1973/12/1

yyyymmdd

This date format conforms to the following structure: yyyy/mm/dd (year/month/day), for example,2001/02/23

yyyy_m_d

This date format conforms to the following structure: yyyy_m_d (year_month_day), where both 'm'

and 'd' could be either one or two digits, for example, 1954-1-31 or 1973-12-1

timeFormat

This is only relevant to the timestamp overlay.

enum TimeFormat { TIME_FORMAT_HHMMSSTT = 10, TIME_FORMAT_HMMSSTT = 11,TIME_FORMAT_HMMSS = 12,TIME_FORMAT_HHMMSS = 13,TIME_FORMAT_HMSTT = 14,TIME_FORMAT_TTHMS = 15,TIME_FORMAT_TTHHMMSS = 16,TIME_FORMAT_HMS = 17,};

hhmmsstt

This time format conforms to the following 12 hour structure: hh:mm:ss tt (hours:minutes:secondsAM/PM), for example, 06:07:12 AM or 12:07:12 PM

hmmsstt

This time format conforms to the following 12 hour structure: h:mm:ss tt (hours:minutes:seconds AM/

PM), where 'h' could be either one or two digits, for example, 6:07:12 AM or 12:07:12 PM

hmmss

This time format conforms to the following 24 hour structure: h:mm:ss (hours:minutes:seconds),

where 'h' could be either one or two digits, for example, 6:07:12 or 18:07:12

hhmmss

This time format conforms to the following 24 hour structure: hh:mm:ss (hours:minutes:seconds), for

example, 06:07:12 or 18:07:12

hmsttThis time format conforms to the following 12 hour structure: h:m:s tt (hours:minutes:seconds), where'h', 'm', or 's' could be either one or two digits, for example, 6:7:12 AM, 12:17:12 PM, or 12:3:2 PM

tthms

This time format conforms to the following 12 hour structure: tt h:m:s (AM/PMhours:minutes:seconds), where 'h', 'm', or 's' could be either one or two digits, for example, AM

6:7:12, PM 12:17:12, or PM 12:3:2

tthhmmss

This time format conforms to the following 12 hour structure: tt hh:mm:ss (AM/PM

hours:minutes:seconds), for example, AM 06:07:12, PM 12:17:12, or PM 12:03:02

7/18/2019 C5617M-A



hms

This time format conforms to the following 24 hour structure: H:m:s (hours:minutes:seconds), where

'h', 'm', or 's' could be either one or two digits, for example, 6:7:12, 12:17:12, or 12:3:2

Resetting Overlay Data

To reset overlay data to default values for the video being exported, call the ResetData method.C++ Example:

bool bSuccess = exporter.ResetData();

C# Example:

Boolean bSuccess = pEnduraExporterNet.ResetData();

Exporting Video

This section describes various video export methods and scenarios.

Exporting a Single Video Clip


Export C++ sample project. The related source code for this entry (for C#) can be found in Program.cs’s Main

function, which belongs to the Export C# sample project.

1. Determine the System Manager’s IP address.

Refer to Automatically Determining the System Manager’s IP Address and Port Number in the Device and ServiceDiscovery section for details.

2. Initialize the Exporter.

Refer to Initializing the Exporter for details.

3. Optional: If you would like to overlay data onto the resulting export, do so now.

Refer to Setting Up Overlay Data on Video to Be Exported

4. Begin the video export by calling the Exporter’s StartExport method, passing in the following parameters:

The full path, including file name, of the resulting exported video.The format changes based on the operating system, for example, Windows or Linux.

The UUID of the camera from which to export video

The desired resulting video format for the export

Refer to the EnduraExporterDefines header for the latest options.

enum VideoCodecType{CODEC_ID_NONE = 0,/* video codecs */CODEC_ID_MPEG1 = 1,CODEC_ID_MPEG2 = 2,CODEC_ID_MJPEG = 8,CODEC_ID_MPEG4 = 13,CODEC_ID_H264 = 28};

The starting time of the recorded video to export in UTC (GMT), not local time, using the format yyyy-

mm-ddThh:mm:ss

The ending time of the recorded video to export in UTC (GMT), not local time, using the format yyyy-mm-ddThh:mm:ss

The videoOnly parameter

7/18/2019 C5617M-A



Set to true to export only video, while setting this to false to include audio (if it is available). If youwant audio to be included, it will be available in either PEF or AVI format.

The UUID of the stream to export’s audio source, if separate from the video source of the export

C++ Example:

bool bSuccess = exporter.StartExport("D:\\Video\\test123.avi","uuid:691fd745-006c-4fc9-9262-23c13e977ce4",PelcoAPI::CODEC_ID_MPEG4, "2010-01-11T22:10:35", "2010-01-11T22:11:15", false, "uuid:691fd745-006c-4fc9-9822-23c13e977ce4");

C# Example:

Boolean bSuccess =exporter.StartExport("D:\\Video\\test123.avi", "uuid:691fd745-006c-4fc9-9262-23c13e977ce4",PelcoAPI::CODEC_ID_MPEG4, "2010-01-11T22:10:35", "2010-01-11T22:11:15", false, "uuid:691fd745-006c-4fc9-9822-23c13e977ce4");

5. Poll the status of the video export repeatedly, for example, once per second, until it is finished. For moreinformation, see Polling a Video Export .

Exporting Video Using a Playlist (PPX)

The playlist (PPX) format supports advanced playback features, including synchronized and sequential (stitched)

playback.

For the following play-list example consider the following scenario; we have a system with nine cameras, named

“camera_x”, where “x” is the spelling of a number from zero to eight. We want to play the files in the following way;

camera_zero from 9:05-9:10, followed by camera_one and camera_three played together in a 2x1 layout both from

9:11 to 9:15. Assume that the video from camera_one for 9:13 has been deleted. Following this we want to play

camera_four from 9:20 to 9:30, then we want to play camera_two, camera_six, and camera_seven from 9:30 to

9:45, assume that camera_two’s video for 9:31-9:33 has been deleted, and that its video from 9:42 to 9:44 has been

deleted. Finally, we want to view camera_eight from 9:42 to 10:00. The following diagram illustrates the view flow.





3. Call the PlaylistExportInfo method to set up the clip groups that will be played sequentially in the order

provided.

PlaylistExportInfo contains the following parameters:

DeviceID

The UUID of the camera from which to export video

7/18/2019 C5617M-A



AudioDeviceID

The UUID of the stream to export’s audio source, if separate from the video source of the export.

StartTime

The start time in UTC (GMT), not local time, using the format yyyy-mm-ddthh:mm:ss

EndTime

The end time in UTC (GMT), not local time, using the format yyyy-mm-ddThh:mm:ss

VideoOnly

A boolean indicating if the clip should be exported with video only. If false, audio will also be

included.

ClipGroup

An integer representing the sequential order to play video clips. Up to 4 clips can be in the same clipgroup which will play in sync within the export player.

C++ Example:

PelcoAPI::PlaylistExportInfo playlistExportInfo[ NUM_CLIPS ]; playlistExportInfo[0].sDeviceID = CAMERA_1; playlistExportInfo[0].sStartTime = START_TIME_1; playlistExportInfo[0].sEndTime = END_TIME_1; playlistExportInfo[0].bVideoOnly = false; playlistExportInfo[0].nClipGroup = 1;

C# Example:

ArrayList playlistExportInfo = new ArrayList( num_clips ); playlistExportInfo.Add( new PelcoAPI.PlaylistExportInfoNet( CAMERA_1,"", START_TIME_1, END_TIME_1, false, 1 ) );


exportFolder

The path of the folder for exports. (The format changes based on operating system.)

playlistName

The name of the playlist. This should be a simple name with no extensions

playlistExportInfo

An array of playlist information for export.

exportInfoCount

The number of export info entries

C++ Example:

bool bSuccess = exporter.StartExport("D:\\Video\\test123",“PlaylistName”, PlaylistExportInfo, exportInfoCount);

C# Example:

Boolean bSuccess = pEnduraExporterNet.StartExport("D:\\Video\\test123",“PlaylistName”, PlaylistExportInfo, exportInfoCount);

5. Poll the status of the video export repeatedly, for example, once per second, until it is finished.For more information, see Polling a Video Export .

Stitching Multiple Clips into a Single Video Export

NOTE: This stitching procedure is DEPRECATED. Stitched video clips do not play correctly with Pelco Export

Player. Please use Exporting Video Using a Playlist (PPX).

NOTE: Enabling sequential stitching may or may not be much slower than exporting a single video clip,

depending on whether any of the clips need to be transcoded.

There are occasions where you will need to export a single video from multiple video clips.

7/18/2019 C5617M-A



• First initialize as many video clip export settings (ExportInfo) instances as you will need. For details on how to

set up one set of video clip export settings, refer toSetting Up Overlay Data on Video to Be Exported .

• At this point determine if you want to associate any overlays to the video clips. If so, create and initialize any

overlays to associate with the video clip to export. In the example excerpt below, we have associated four

previously created OverlayInfo instances with two ExportInfo instances.





3. Optional: If you would like to overlay data onto the resulting export, do so now.

Refer to Setting Up Overlay Data on Video to Be Exported for details.


The full path, including file name, of the resulting exported video.

The format changes based on operating system, for example, Linux or Windows.

The desired resulting video format for the export.

Refer to the EnduraExporterDefines header for the latest options.

enum VideoCodecType

{ CODEC_ID_NONE = 0, /* video codecs */ CODEC_ID_MPEG1 = 1, CODEC_ID_MPEG2 = 2, CODEC_ID_MJPEG = 8, CODEC_ID_MPEG4 = 13, CODEC_ID_H264 = 28 };

An array of the ExportInfo instances, containing instances of OverlayInfo.

The number of ExportInfo instances, one for each clip to stitch.

Below is a stitched video export example:

C++ Example:

int i = 0; int clipNum = 2; int overlayNum = 4; PelcoAPI::ExportInfo * exportInfo = newPelcoAPI::ExportInfo[clipNum]; exportInfo[0].sDeviceID ="uuid:00047D01-4CA5-5370-6563-747261495605"; exportInfo[0].sStartTime = "2009-08-16T05:08:00"; exportInfo[0].sEndTime = "2009-08-16T05:09:00"; exportInfo[0].bVideoOnly = false; exportInfo[0].overlayNum = overlayNum; exportInfo[1].sDeviceID =

"uuid:691fd745-006c-4fc9-9262-23c13e977ce4"; // configure other export settings for the 2nd clip to export if (overlayNum > 0) { for (i = 0; i < clipNum; i++) { exportInfo[i].overlayInfo = new PelcoAPI::OverlayInfo[overlayNum]; exportInfo[i].overlayInfo[0].type = PelcoAPI::OVERLAY_TYPE_TIMESTAMP; // configure other settings for the 1st overlay exportInfo[i].overlayInfo[1].type =

7/18/2019 C5617M-A



PelcoAPI::OVERLAY_TYPE_CAMERANAME; // configure other settings for the 2nd overlay exportInfo[i].overlayInfo[2].type = PelcoAPI::OVERLAY_TYPE_PICTURE; // configure other settings for the 3rd overlay exportInfo[i].overlayInfo[3].type = PelcoAPI::OVERLAY_TYPE_TEXTSTRING; // configure other settings for the 4th overlay } } bool bSuccess = exporter.StartExport("D:\\Video\\test123.mp4", PelcoAPI::CODEC_ID_MPEG4, exportInfo, 2);

C# Example:

PelcoAPI.ExportInfoNet exportInfo_0 = new PelcoAPI.ExportInfoNet(); exportInfo_0.sDeviceID = "uuid:00047D01-4CA5-5370-6563-747261495605"; exportInfo_0.sStartTime = "2009-08-16T05:08:00"; exportInfo_0.sEndTime = "2009-08-16T05:09:00"; exportInfo_0.bVideoOnly = true; PelcoAPI.ExportInfoNet exportInfo_1 = new

PelcoAPI.ExportInfoNet(); // initialize another export video clip setting exportInfo_0.overlayInfo = new ArrayList(); exportInfo_0.overlayInfo.Add(overlayInfo_0); // add any other overlay settings here exportInfo_1.overlayInfo = new ArrayList(); exportInfo_1.overlayInfo.Add(overlayInfo_0); // add any other overlay settings here ArrayList exportInfo = new ArrayList(2); exportInfo.Add(exportInfo_0); exportInfo.Add(exportInfo_1); Boolean bSuccess = pEnduraExporterNet.StartExport("C:\\test456.avi", PelcoAPI.VideoCodecTypeNet.CODEC_ID_MPEG4, exportInfo, 2);

5. Poll the status of the video export repeatedly, for example, once per second, until it is finished.For more information, see Polling a Video Export .

Polling a Video Export

To poll the status of the video export until it is finished, perform the following:

C++ Example:

for( int clipCounter = 0; clipCounter < NUM_CLIPS; ++clipCounter ) { int status = 0; while( status < 100 && status != -1 )

{ int temp = exporter.PollStatus(); if (temp != status) { status = temp; TRACE_INFO("Polling status %d\n", status); } } }

C# Example:

Int32 clipCounter = 0;

7/18/2019 C5617M-A



while (clipCounter < num_clips) { Int32 status = 0; Int32 temp = 0; while (status < 100 && status != -1) { temp = pEnduraExporterNet.PollStatus(60); if (temp != status) { status = temp; Console.WriteLine("Polling status - {0}\n", status); } } ++clipCounter; }

Stopping a Video Export

When you want to force a video export that is currently in progress to stop, just call the StopExport method.

C++ Example:

bool bSuccess = exporter.StopExport();

C# Example:

Boolean bSuccess = exporter.StopExport();

Exporting A JPEG Snapshot

To create a JPEG snapshot, call the ExportSnapshot method, passing in a .jpeg or .jpg file name, camera uuid,and timestring (use "NOW" for a live snapshot).

The following is an example of a live snapshot.

C++ Example:

bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "NOW");

C# Example:

Boolean bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "NOW");

The following is an example of a recorded snapshot.

C++ Example:

bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "2011-11-07T19:30:00");

C# Example:

Boolean bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "2011-11-07T19:30:00");

7/18/2019 C5617M-A


Chapter

7Web Service Proxies

Web Service Proxies




installation.


Overview

PelcoGSoap is a static linked library generated by gSOAP tools, based on the WSDL files with minor modifications.

The PelcoGSoap library provides an interface for SOAP clients to make SOAP calls to Pelco devices. It accounts for

most issues regarding making SOAP calls to Pelco devices.

General Usage

NOTE: This entry assumes that users have already installed the Pelco SDK.

1. Include the stdsoap2 header and the web service proxy header. For example, if you want to utilize theCameraConfiguration web service, you should include the CameraConfigurationProxy header.

#include "PelcoAPI/stdsoap2.h"#include "PelcoAPI/CameraConfigurationProxy.h"

2. Declare your web service proxy. In this case, it will be CameraConfigurationProxy.

CameraConfigurationProxy CameraConfiguration;

3. Set the SOAP header.

pSoap->header = (struct SOAP_ENV__Header *) soap_malloc(CameraConfiguration,sizeof(struct SOAP_ENV__Header));

4. Set the web service’s control point URL. For details on the proper way to retrieve the control point URL, refer toRetrieving a Specific Web Service’s Control URL.

CameraConfiguration.soap_endpoint = strEndPointURL.c_str();

5. Create a new web service action request instance.

This will hold your request parameters for the web service action ResetConfiguration.

6. Create a new web service action response instance. In the below example, we create an instance of

CameraConfiguration’s ResetConfigurationResponse data type.

_CameraConfiguration__ResetConfigurationResponse * pResetConfigurationResponse =soap_new__CameraConfiguration__ResetConfigurationResponse(



7/18/2019 C5617M-A


617M-A | Web Service Proxies

&CameraConfiguration, -1);

This will hold the web service’s response including related values to your request.

7. Call the CameraConfiguration web service proxy ResetConfiguration action, passing in both the earliercreated ResetConfiguration and ResetConfigurationResponse parameters. Then determine if the

operation was successful.

CameraConfiguration.ResetConfiguration(pResetConfiguration,

pResetConfigurationResponse);#include "PelcoAPI/stdsoap2.h"#include "PelcoAPI/LensControlProxy.h" #include "GSOAPSample.h" using namespace PelcoAPI; void GSOAPSample::StopLens() throw(){LensControlProxy LensControl; std::string cameraAddress = "10.18.129.231";std::string cameraPort = "49152";pSoap->header = (struct SOAP_ENV__Header *) soap_malloc(LensControl, sizeof(struct SOAP_ENV__Header));

std::string strEndPointURL = "http://" + cameraAddress + (cameraPort.empty() ? "" : ":" + cameraPort) + "/control/LensControl-1";LensControl.soap_endpoint = strEndPointURL.c_str(); _LensControl__Stop * pStop = soap_new__LensControl__Stop(&LensControl, -1); _LensControl__StopResponse * pStopResponse =soap_new__LensControl__StopResponse(&LensControl, -1);if (LensControl.Stop(pStop, pStopResponse) != SOAP_OK)

7/18/2019 C5617M-A


Chapter

8Discovery

Device and Service Discovery Overview




installation.


One of the most basic tasks is to programmatically determine what devices and services are available on your

network.


The key to performing device and service discovery related tasks is the System Manager Wrapper. The System

Manager Wrapper is a component of the Pelco SDK. It provides users with convenience functions for device and

service queries.

The majority of the tasks covered in this section can be found in the the System Manager Wrapper C++ sample

project. You should examine the sample project source code while reading this documentation.

NOTE: For more Endura specific information, refer to the Endura appendix.

Getting Started



7/18/2019 C5617M-A


617M-A | Discovery

Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug version,

change the Working Directory value as appropriate. Assuming that you did not change the default installation directory

for the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Release to use the production version of the

Pelco SDK libraries. Conversely, use C:\\Program Files\Pelco\API\Libs\Debug to use the debug version of

the Pelco SDK libraries.

Next Steps

The following set of tasks are essential for using the Pelco SDK:

• Determine the System Manager’s IP address and port number, either manually, or automatically through the Pelco

SDK as described in Automatically Determining the System Manager’s IP Address and Port Number .

• Create a class that implements the IDeviceStorageNet interface.

• Query all available Pelco devices on your network.

Initializing the Pelco SDK System Manager Wrapper


Program.cs’s Main function (for C#), which belongs to the System Manager Wrapper sample project.

Before performing any of the tasks associated with the System Manager Wrapper, you must initialize an instance of

it. Then you can use the instance to log in to the System Manager, since most System Manager Wrapper methods

require a login ID.



1. Declare and initialize the System Manager Wrapper.

a) If you need to determine the System Manager’s IP address, refer to Automatically Determining the System

Manager’s IP Address and Port Number .

b) If you already know the System Manager’s IP address, enter it into the SetSMAddress method as shown

below.

C++ Example:

PelcoAPI::SystemManagerWrapper sm;int nRet = sm.SetSMAddress((char *) sSMIPAddress);

C# Example:

PelcoAPI.SystemManagerWrapperNet sm = new PelcoAPI.SystemManagerWrapperNet();int nRet = sm.SetSMAddress("192.168.1.1");

2. Log in to the System Manager with the proper credentials. Call the System Manager Wrapper instance’s

UserLogin method, passing in the username and password.C++ Example:

int loginId = sm.UserLogin("brian", "pelco");

C# Example:

Int32 loginId = sm.UserLogin("brian", "pelco");

If successful, this step should return an ID of your login session. Make a note of this login ID, because it is used for

many of the System Manager Wrapper’s methods.

3. After you have logged in to System Manager, you will eventually have to log out. When you have finished allSystem Manager related operations, log out by calling the System Manager Wrapper instance’s UserLogoutmethod, passing in your login ID as the parameter.

For more details on authenticating to a Pelco system, refer to Logging In and Logging Out .

C++ Example:

sysMgr.UserLogout(loginId);

7/18/2019 C5617M-A


C5617M-A | Dis

C# Example:

sm.UserLogout(loginId);

Automatically Determining the System Manager’s IP Address and PortNumber



1. Initialize the System Manager Wrapper by calling its AutoDiscoverSM method to automatically determine the

System Manager's IP address and port number.

The 120 parameter represents the duration in seconds before a timeout.

int nRet = sm.AutoDiscoverSM(120);

2. To access the System Manager’s IP address and port number, call the GetSMAddress method.C++ Example:

int rPort = 0;// ... Auto discover SM ...

// Return the SM IP AddressPelcoAPI::xstring sIpAddress;sm.GetSMAddress(&sIpAddress,&rPort);TRACE_INFO("The SM IpAdress - %s and Port - %d\n", sIpAddress.data, rPort);PelcoAPI::xfree(&sIpAddress);

C# Example:

// ... Auto discover SM ...String sSmIpAddress = "";Int32 nPort = -1;if( sm.GetSMAddress(ref sSmIpAddress, ref nPort ) )Console.WriteLine("SM address -> {0}:{1}\n", sSmIpAddress, nPort);elseConsole.WriteLine( "Could not get SM address\n" );

Logging In and Logging Out



In many cases, you might need to both log in and log out of System Manager.

1. To log in to the System Manager with the proper credentials, call the System Manager Wrapper instance’s

UserLogin method, passing in the username and password.


If successful, this step should return an ID of your login session.NOTE: Make a note of this login ID, because it is used for many of the System Manager Wrapper’smethods.

2. When you have finished all System Manager related operations, log out of the System Manager. Call the System

Manager Wrapper instance’s UserLogout method, passing in your login ID as the parameter.

sysMgr.UserLogout(loginId);

7/18/2019 C5617M-A


617M-A | Discovery

Querying Available Devices from the System Manager



NOTE: Before proceeding with this entry, it is assumed that you have already completed the steps outlined in

Creating an IDeviceStorage Class .

The first major task that you need to complete is to query all Pelco devices available on your network. Completingthis enables you to access a device’s Unique Device Name (UDN) and many other device-related attributes that are

needed for other Pelco SDK related tasks.

1. Initialize the System Manager Wrapper. See Initializing the System Manager Wrapper for details.

2. Make a call to the System Manager Wrapper's GetDevices method, passing in the following parameters:

• Your login ID: This ID is returned after a successful login. See Initializing the System Manager Wrapper for

details.

• The sequence number: This is used to filter results, only returning newly added or changed devices.

GetDevices calls return a new integer value once every few minutes during successive calls. New values are1 larger than the one before, for example, if the 1st call returned 1, then the subsequent call will return a 2.

• The device type you would like to use to filter the results. Known device types include the following:

• Camera

• Encoder• Decoder

• Monitor

• a NULL value (to not filter results by type of device)

NOTE: This is not a definitive list of Pelco device types. This list will expand as Pelco expands its product

line.

• A pointer to your IDeviceStorage implementation.

C++ Example:

int seqNum = 0;MyStorage storage; // ... You must define this class ...int loginId = sm.UserLogin("brian", "pelco");sm.GetDevices(loginId, &seqNum, "Camera", &storage);

C# Example:

int seqNum = 0;DeviceInformation devStore = new DeviceInformation(); // You must define this classint loginId = sm.UserLogin("brian", "pelco"); Boolean bSuccess = sm.GetDevices(loginId, seqNum, "Camera", devStore);

3. Perform the needed operations on the returned device data and store them into your IDeviceStorage class

instance. See Creating an IDeviceStorage Class for further details.

4. To query any changes with available devices from the System Manager, use the returned sequence number valuefrom your last call to the GetDevices method with your next call to the same method.

This call returns Pelco devices that have changed or are new to the network. Every subsequent call returns onlynew changes within your network.

C++ Example:

int seqNum = 0;MyStorage storage; // ... You must define this class ...int loginId = sm.UserLogin("brian", "pelco");sm.GetDevices(loginId, &seqNum, "Camera", &storage); // ... seqNum changes here to 1 ...// ... Misc logic ...

7/18/2019 C5617M-A


C5617M-A | Dis

sm.GetDevices(loginId, &seqNum, "Camera", &storage); // ... seqNum changes here to 2 ...

C# Example:

int seqNum = 0;DeviceInformation devStore = new DeviceInformation(); // You must define this classint loginId = sm.UserLogin("brian", "pelco");

sm.GetDevices(loginId, ref seqNum, "Camera", &storage); // seqNum changes here to 1 ...// ... Misc logic ...sm.GetDevices(loginId, ref seqNum, "Camera", &storage); // seqNum changes here to 2 ...

Retrieving the System Manager’s Time Zone



To determine your System Manager’s current time zone, do the following:

1. Initialize the System Manager Wrapper. (Refer to Initializing the System Manager Wrapper for details.)

2. Call the System Manager Wrapper’s GetSystemAttribute method, passing in the following parameters:

Your login ID

This ID is returned after a successful login. (Refer to Initializing the System Manager Wrapper fordetails.)

SYS_CFG_TzInfo

The time zone attribute’s ID.

&sTimezoneInfo

A pointer to your time zone variable.

C++ Example:

PelcoAPI::xstring sTimezoneInfo;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo", &sTimezoneInfo);

C# Example:

int loginId = sm.UserLogin("brian", "pelco");String sTimeZone = "";Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo", ref sTimeZone);

Retrieving the Network Time Server Address



To your network’s network time server’s IP Address, do the following:



Your login ID


SYS_CFG_NtpAddr

The network time server's attribute’s ID.

&sTimezoneInfo

A pointer to your NTP address variable.

7/18/2019 C5617M-A


617M-A | Discovery

C++ Example:

PelcoAPI::xstring sNtpAddress; int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr", &sNtpAddress);

C# Example:


String sNtpAddress = "";Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr",ref sNtpAddress);

Retrieving a Web Service’s ID



NOTE: This entry assumes that you have already completed the steps outlined in Querying Available Devices

from the System Manager , which provides you with UDNs for Pelco devices available on your network.

To determine your web service's ID, do the following:


2. Call the System Manager Wrapper’s GetServiceID method, passing in the following parameters:

Your login ID

This ID is returned after a successful login. (Refer to Initializing the System Manager Wrapper for

details.)

The target device’s Unique Device Name (UDN) value

To retrieve a deviceUDN, cycle through the stored results of a GetDevices call within your

IDeviceStorage class instance. For details, refer to Querying Available Devices from the System

Manager .

sServiceType

The name of desired web service, such as VideoOutput.

sServiceId

The pointer to the variable that will hold the result.C++ Example:

PelcoAPI::xstring sServiceId;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetServiceID(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","VideoOutput", &sServiceId);

Retrieving a Specific Web Service’s Control URL



NOTE: This entry assumes that you have already completed the steps outlined in Querying Available Devices from the System Manager , which provides you with UDNs for Pelco devices available on your network.

Obtaining a web service’s control URL is essential for many Pelco-related operations.


2. Call the System Manager Wrapper’s GetDeviceServiceAttribute method, passing in the following

parameters:

Your login ID


7/18/2019 C5617M-A


C5617M-A | Dis




The target web service’s ID

Refer to Retrieving a Web Service’s ID for details.

SYS_UpnpControlUrl

The control URL attribute’s ID.

sCtrlUrl

A pointer to the variable that will store the result of the web service control URL.

C++ Example:

PelcoAPI::xstring sCtrlUrl;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceServiceAttribute(loginId,"urn:schemas-pelco-com:service:MotionDetection:1","uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpControlUrl",&sCtrlUrl);

C# Example:

String sCtrlUrl = “”; int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetDeviceServiceAttribute(loginId,"urn:schemas-pelco-com:service:MotionDetection:1", "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpControlUrl",ref sCtrlUrl);

Retrieving the NVR Associated with the Device





To determine to which NVR or NSM your camera is connected to record, complete the following steps:


2. Call the System Manager Wrapper’s GetDeviceAttributeValue method, passing in the following parameters:

Your login ID





Manager .

SYS_NvrAssoc

The NVR association attribute’s ID.

sNvr

The pointer to the variable that will hold the result.

C++ Example:

PelcoAPI::xstring sNvr;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc",&sNvr);

7/18/2019 C5617M-A


617M-A | Discovery

C# Example:

String sNvr = “”;int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc", ref sNvr);

Retrieving the Device’s Friendly NameNOTE: The related source code for this entry can be found in main.cpp’s main function (for C++) or




To determine a device’s friendly name, you can simply parse through the results of a GetDevices method call, which

includes both the device UDN and its accompanying attributes. Alternatively, you can complete the following steps:



Your login ID


details.)




Manager .

SYS_UpnpFriendlyName

The attribute name.

sFriendlyName


C++ Example:

PelcoAPI::xstring sFriendlyName;

int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","SYS_UpnpFriendlyName", &sFriendlyName);

Retrieving the Device’s Device Description File (DDF) URL



What is DDF? The Device Descriptor File (DDF) is file containing device related data such as manufacturer, model

name, and so on, in XML format. To get the location of a specific device’s DDF, do the following:


2. Call the System Manager Wrapper’s GetDeviceAttributeValue method, passing in the following parameters:Your login ID


details.)




SYS_UpnpDevDescUrl

7/18/2019 C5617M-A


C5617M-A | Dis

The attribute ID.

sDdfUrl


C++ Example:

PelcoAPI::xstring sFriendlyName;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","SYS_UpnpDevDescUrl", &sDdfUrl);

C# Example:

String sFriendlyName = “”;int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","SYS_UpnpDevDescUrl", ref sDdfUrl);

Retrieving All Web Services Available on a Device



To show all available web services on a particular Pelco device, complete the following steps:


2. Call the System Manager Wrapper’s GetServiceInfoSync method, passing in the following parameters:

Your login ID


details.)

The sequence number

This has the same function as other Pelco query methods, in that it can help limit the results to

only new or changed items. This makes sense for querying devices on a network. However, adevice’s available web services does not change very often, if ever, without a new firmware update.

Therefore, this value should almost always be a 0.




storage


C++ Example:

int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm. GetServiceInfoSync(loginId, 0,"uuid:00047D01-4CA5-5370-6563-747261495605", &storage);

C++ Example:

int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm. GetServiceInfoSync(loginId, 0,"uuid:00047D01-4CA5-5370-6563-747261495605", storage);

Retrieving Device Attributes



7/18/2019 C5617M-A


617M-A | Discovery



Device attributes are values that describe the device in some way such as its model number or its model name. The

following are the most common device attributes:

SYS_UpnpPelcoDeviceUdn

A Pelco device’s Unique Device Name (UDN); a special device identifier for networks.

SYS_UpnpFriendlyName

A more human readable version of the device’s name. A separate attribute, friendlyName, may be

present. Endura users can customize this attribute. When present, friendlyName should be used

in place of SYS_UpnpFriendlyName for display purposes.

SYS_UpnpDeviceType

A URN that denotes the device’s category.

SYS_UpnpDevDescUrl

This shows the location of the device’s UPnP Device Descriptor File (DDF).

SYS_UpnpSerialNumber

The device’s serial number.

SYS_UpnpModelNumber

The device’s model number.

SYS_UpnpModelDescription

A more detailed description of the device.

SYS_UpnpManufacturerUrl

The device manufacturer’s website.

SYS_UpnpModelName

The device’s model name.

This outlines the steps needed to return a specific device attribute:



Your login ID





The name of the device attribute to query.


C++ Example:

PelcoAPI::xstring sModelNumber;int loginId = sm.UserLogin("brian", "pelco");

bool bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","SYS_UpnpModelNumber", &sModelNumber);

C# Example:

String sModelNumber = "";int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","SYS_UpnpModelNumber", ref sModelNumber);

7/18/2019 C5617M-A


C5617M-A | Dis

Retrieving a System Manager’s Attribute



A System Manager’s attributes are similar to a generic Pelco device’s attributes, except in most cases a System

Manager attribute is exclusive to Pelco System Managers. If you aren’t familiar with device attributes, System Manager

attributes are simply values that describe the System Manager in some way such as its current time zone or its current

security mode. The following are the more common System Manager attributes:

SYS_CFG_NtpAddr

This value is used to indicate the location at which the NTP server (if any) can be located. The

expected value is an IP address.

SYS_CFG_SecMode

This value is used to identify the system's current security mode.

SYS_CFG_SmtpAddr

This value is used to indicate the location at which the SMTP server (if any) can be located. The

expected value is an IP address.

SYS_CFG_TzInfo

This value is used to report time zone information. This value is comma delimited (without

whitespace). The following describes each number in the order in which they appear in the comma-

delimited list (for example, 1205056800,60,480):

Change Time

This number is the absolute daylight savings time (in time_t time() seconds). If this value is zero,

there is no daylight savings time for the time zone and nothing will have to be done to support

daylight savings. If the value is non-zero, the time zone does support daylight savings time. In this

case, if the value is negative, the time value is being used to indicate the time to turn off daylight

savings time. If the value is positive, the value is being used to indicate the time at which daylight

savings time is to be turned on.

DST Offset

This number is the number of minutes to adjust the time when daylight savings time is in affect. The

offset should be added to the GMT time after adding the GMT offset (see next value).

GMT Offset

This value indicate the number of minutes to adjust the GMT time in order to get the local time (this isthe minutes "west" of the GMT). To get the current local time, simply subtract this number of minutes

from the current GMT time.

SYS_CFG_UPNP_RENEWAL

The UPnP renewal value in seconds. The default setting is 1800 seconds (30 min).

SYS_CFG_UserLanguage

This value is used to indicate the default user language.

To determine a particular attribute value on your System Manager, do the following:



Your login ID


systemAttribute

The name of the System Manager attribute. Parameter of type pointer to xstring, value

SYS_CFG_TzInfo.

A pointer to the variable that will hold the result.

C++ Example:

int iUpnpRenewal;int loginId = sm.UserLogin("brian", "pelco");

7/18/2019 C5617M-A


617M-A | Discovery

bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL",&iUpnpRenewal);

C# Example:

int iUpnpRenewal;int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL",ref iUpnpRenewal);

Retrieving a Web Service’s Attribute






2. Call the System Manager Wrapper’s GetDeviceServiceAttribute method, passing in the following

parameters:

Your login ID





Manager .

The target web service’s ID

Refer to Retrieving a Web Service’s ID for details.

The ID of the web service attribute

For example, SYS_UpnpControlUrl or SYS_UpnpEventSubUrl

A pointer to the variable that will store the result.

C++ Example:

PelcoAPI::xstring sCtrlUrl;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceServiceAttribute(loginId,"urn:schemas-pelco-com:service:MotionDetection:1","uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpControlUrl",&sCtrlUrl);

C# Example:

String sCtrlUrl = "";int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetDeviceServiceAttribute(loginId,"urn:schemas-pelco-com:service:MotionDetection:1","uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpControlUrl",

ref sCtrlUrl);

Creating an IDeviceStorage Class

NOTE: The related source code for this entry can be found in the MyStorage.h and MyStorage.cpp files

(for C++) or DeviceInformation.cs file (for C#), which belongs to the System Manager Wrapper sample

project.

7/18/2019 C5617M-A


C5617M-A | Dis

What is the IDeviceStorageNet class? An IDeviceStorageNet is simply an interface that parses XML

responses from the System Manager and stores the resulting device data from the XML response internally. Users

need an implementation of this interface, if they wish to manage device data using the System Manager Wrapper.

1. Ensure that the IDeviceStorageNet class implements the following methods:

• virtual bool AddDevice(const char* sUDN, const char* sAttributes): This method adds anew device to the IDeviceStorageNet class. It takes the following parameters:

• The device’s Unique Device Name (UDN)• The devices’s attributes, given as XML

• virtual bool DeleteDevice(const char* sUDN): This method deletes an existing device within

IDeviceStorageNet.

• The device’s Unique Device Name (UDN)

• virtual bool UpdateDevice(const char* sUDN, const char* sAttributes)

The System Manager Wrapper will use these methods every time you call its GetDevices method, which in turn

will update your IDeviceStorage instance contents.

C++ Example:

#ifndef PELCO_API_IDEVICE_STORAGE_H#define PELCO_API_IDEVICE_STORAGE_H

#include <string> namespace PelcoAPI{class IDeviceStorage{public:virtual ~IDeviceStorage(){}; virtual bool AddDevice(const char* sUDN, const char* sXmlAttributes)=0; virtual bool DeleteDevice(const char* sUDN)=0; virtual bool UpdateDevice(const char* sUDN, const char* sXmlAttributes)=0;};

} #endif

C# Example:

using System;using System.Collections.Generic;using System.Text;namespace SystemManagerWrapperNet{class DeviceInformation : PelcoAPI.IDeviceStorageNet{public void AddDevice(string sUDN, string sAttributes){// ... User implemented logic here ...}public void DeleteDevice(string sUDN){// ... User implemented logic here ...}}}

2. Note that the System Manager Wrapper sample project has an implementation of IDeviceStorage called

MyStorage.

7/18/2019 C5617M-A


617M-A | Discovery

MyStorage is a stub class. It does not implement anything that is essential for production usage, such as parsingthe System Manager’s XML response data (attributes). Nor does it associate the device UDN/attribute XML pairs

into any constructs. Those exercises are left to the user.

7/18/2019 C5617M-A


Appendix

ALogging

Logging is specific to Endura, and is configurable.

1. To configure logging, run the LoggingSetup application in the C:\Program Files\Pelco\API\Loggingfolder.

2. Select the items that you want to log, as well as the folder where the logs should be stored and the max logfilesize.

3. Click Set to save the settings.

NOTE: Logging should be run by an administrative account, because other users do not have write

permissions to C:\Program Files (x86) or subdirectories by default.

4. To view the current log, run the LoggingSetup application in the C:\Program Files\Pelco\API\Loggingfolder. Click the View Log File button.

NOTE: The maximum log size is 50MB. Any settings over that value will be reset back to the default

50MB restriction. Usually, logging should be off (no items checked) unless Pelco technical support asks for

logging information when tracing issues.In the Logging dialog box, the following settings are available:

Error

Logs error messages. This is usually the most important item.

Memory

Logs memory allocation statistics. This should usually be left unchecked.

Info

The next level of severity below Error.

Verbose

7/18/2019 C5617M-A


617M-A | Logging

Logs actions that occur often and should normally not be logged because they fill up the logfilequickly.

7/18/2019 C5617M-A


Appendix

BProduct Compatibility

The following table shows the compatability of Pelco products with API components.

Product Event Arbiter EventManager

Exporter Meta-dataParser

Pelco APIViewer

PTZ ControlWrapper

SM Wrapper

DX Video

Recorders

N N N N N N N

Digital

Sentry

N N N N N N N

DVR5100 Y Y Y Y Y Y4 Y

EnduraExpress

Y Y5

Y5

Y Y Y4

Y5

IP110 Y Y5

N Y Y Y Y5

IP3701 Y Y5

N Y Y N Y5

NET5301R Y Y5

N Y Y N Y5

NET5402R-

HD

Y Y5

N Y Y N Y5

NET5301T Y Y5

N Y Y Y4

Y5

NET5308T Y Y5

N Y Y Y4

Y5

NET5301T-I Y Y5 N Y Y Y4 Y5

NET5400T-I Y Y5

N Y Y Y4

Y5

NSM5200 Y Y5

Y5

Y Y Y4

Y5

Sarix Y Y5

N Y Y N Y5

Spectra HD Y Y5

N Y Y Y Y5

Spectra IV

IP

Y Y5

N Y Y Y Y5

Spectra Mini Y Y5

N Y Y Y Y5

SM5000 Y Y N Y N Y4

Y

4Active only if the attached IP camera is PTZ capable.

5Active only if an active System Manager is available on the network.

7/18/2019 C5617M-A


617M-A | Product Compatibility

7/18/2019 C5617M-A


Appendix

CEndura

In 2005, Endura provided a distributed architecture that delivered both flexibility and performance. Endura is a

complete solution for high definition video encoding, recording, and display. It controls the origination, transport,

recording, and display of integrated, security-related audio and video.

From a technical standpoint, what defines an Endura system?

System Manager + Endura Devices = Endura System

System Manager (SM)

First and foremost, an Endura system must have a System Manager (SM). The SM is the heart of Endura. It isresponsible for the following:

• Managing devices such as cameras, decoders, and NVRs, including administering rights and privileges

• Storing device information, like status

• Administering users, which includes permissions management

• Logging errors and alarms

• Security key management

Endura Devices

Endura devices can be defined as IP cameras, encoders, decoders, NVRs, or even work stations. Each Endura

device, including the SM itself, has an Application Programming Interface (API). An API is simply a specified way

for software clients to programmatically communicate with Endura devices, allowing access to their functionality.

All Endura devices provide an API through a set of related web services. These web services adhere to the SOAPstandard. (For more details on SOAP, please refer to the following http://en.wikipedia.org/wiki/SOAP.) It is beyond the

scope of this documentation to fully describe all Endura web services. For details, such as the SOAP web service API

reference, please refer to the Pelco Developer Network (PDN) at http://pdn.pelco.com .

One of the main purposes of a System Manager is to provide a central place to retrieve information on all Endura

devices. How does the System Manager collect all of this information?


7/18/2019 C5617M-A


617M-A | Endura

1. The System Manager constantly provides a broadcast of its location on the Endura Network. Once a device comesonline, it will listen for this broadcast. When the new device finds the SM, it will then register itself to the System

Manager.

2. At some point the System Manager will query the device’s available web services and its attributes, using a variety

of sources including the UPnP Device Description File (DDF). DDFs are files containing device attributes in XML

format.

3. After the initial query, the System Manager will periodically update the device’s status. To be considered online, a

device must constantly notify the SM that it is still ‘alive’.

4. At any point a client can make requests to the System Manager regarding devices, including the SM itself, and their

web services.

Endura Events and Alarms

There are two major ways to subscribe to Endura web service events:

• Directly contacting the device on which the target web service resides

• Using the System Manager as an intermediary to perform actual eventing related work

On newer Endura network deployments, the first option is the default. Users can enable the System Manager to act as

an intermediary by enabling its EventArbiter web service (not to be confused with the Event Arbiter Library). The

EventArbiter web service is used for receiving GENA events from devices within an Endura network. The Event

Arbiter provides two ways for subscribing to events:

• Through control URLs

• By subscribing to events with event URIs provided

7/18/2019 C5617M-A


C5617M-A |

Figure 1: Subscribing to Events through Control URLs

Figure 2: Subscribing to Events with Event URIs Provided

The URI is provided by the user through the System Manager's EventArbiter service.

What is the advantage of using the System Manager as an intermediary for Endura events? The System Manager can

help manage all event related network traffic, ensuring that an Endura network never gets overwhelmed by eventing

network traffic.

7/18/2019 C5617M-A


617M-A | Endura

Video Exports

Currently the Exporter library requires a System Manager to be present to function. How does it work? The Exporter

client sends its request for video clips to export with atimestamp range filter to the System Manager; that is, it wants

clips that fall within a starting date time and an ending date time. The System Manager will then query all available

NSMs for clips that meet both the starting timestamp and the ending timestamp. Specifically, there may be instances

where the API must ‘stitch’ the end result from more than one NSM source of video clips to meet the filter.

Where Does the Pelco API SDK Fit Within Endura?

The Pelco API SDK is meant to make using Endura web services easier by providing convenience methods and

utilities. It protects the user from all of the potentially overwhelming and complicated details of Endura SOAP web

services. Of course users are still free to directly use Endura web services. However Pelco has found that many of our

customers enjoy the convenience and ease of use that the Pelco API SDK provides.

7/18/2019 C5617M-A


Appendix

DGeneral Event Messages

LoggableEvent

This defines the general structure of logged data for events. It does not have a set of enclosing tags. For further

details, refer to the event message descriptions below.

<element name="deviceUdn" type="xs:int"/><element name="deviceUrn" type="xs:string"/><element name="serviceUrn" type="xs:string"/><element name="logId" type="xs:int"/><element name="major" type="xs:int"/>

<element name="minor" type="xs:int"/><element name="type" type="xs:int"/><element name="reason" type="xs:int"/><element name="parameters" type="tns:LoggableEventParameters"/>

deviceUdn

The unique device name. For example: uuid:AK-2

deviceUrn

The device's resource name. For example: urn:schemas-pelco-com:device:Pelco:1

serviceUrn

The service's resource name.

logId

The log item's unique identifier. major

A major issue identifier.

minor

A minor issue identifier.

type

A event type identifier.

reason

An identifier that represents the cause of the event.

parameters

A LoggableEventParameters data type.

LoggableEventParameters

This contains a list of LoggableEventParameter data types. For further details, refer to the event message

descriptions below.

<complexType name="LoggableEventParameters"> <sequence> <element minOccurs="0" maxOccurs="unbounded" name="parameter"type="tns:LoggableEventParameter"/> </sequence></complexType>

7/18/2019 C5617M-A


617M-A | General Event Messages

0

parameter

A LoggableEventParameter data type.

LoggableEventParameter

This represents an event-related parameter. For further details, refer to the event message descriptions below.

<complexType name="LoggableEventParameter">

<sequence><element name="paramId" type="xs:int"/><element name="name" type="xs:string"/><element name="value" type="xs:int"/><element name="type" type="xs:int"/></sequence></complexType>

paramId

The parameter's unique identifier.

name

The parameter's name.

value

The parameter's value.

type

The parameter's type identifier.

7/18/2019 C5617M-A


Appendix

EHardware Diagnostics Event Messsages

ConfigurationButton (20180)

This event triggers if the front panel configuration button has failed.

PdDiagnostic

This is the data subscribers will receive when the event triggers.

<complexType name="ConfigurationButton"><sequence><element name="objGuid" type="xs:string"fixed="394af82c-2b05-4df8-b2a6-2caed9ad4fae"/><element name="objId" type="xs:int" fixed="20180"/><element name="current" type="xs:int"/><element name="previous" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: 394af82c-2b05-4df8-

b2a6-2caed9ad4fae

objId

The event's unique database identifier. The value must be: 20180current

The current state of the button. Possible values are:

1 for BUTTON_CONFIG

The button is in "Configuration mode".

2 for BUTTON_REBOOT

The button is in "Reboot system".

3 for BUTTON_RESET

The button is in "Reset configuration".

4 for BUTTON_NORMAL

The button currently does not have a state.

previous

The previous state of the button. For possible values, refer to current.

<pdDiagnostic><objGuid>394af82c-2b05-4df8-b2a6-2caed9ad4fae</objGuid><objId>20180</objId><current>1</current><previous>3</previous></pdDiagnostic>

7/18/2019 C5617M-A


617M-A | Hardware Diagnostics Event Messsages

2

LoggableEvent Object

For more details, refer to LoggableEvent .

<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>4</type><reason>1</reason><parameters></parameters>

DriverFailure (20150)

A DriverFailure PdDiagnostic object is only sent when a device's driver fails, so a LoggableEvent object is

used to set the correct major, minor, type, and reason. This is typically used for multi-channel encoder (MCE) devices.

PdDiagnostic

This is the data that subscribers receive when the event triggers.

<complexType name="DriverFailurePdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/><element name="objId" type="xs:int" fixed="20150"/><element name="name" type="xs:string"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: 94b6d2d3-

c68e-4b13-974a-08f69f50cb67

objId

The event's unique database identifier. The value must be: 20150name

The name of the device driver

<complexType name="DriverFailurePdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/><element name="objId" type="xs:int" fixed="20150"/><element name="name" type="xs:string"/></sequence></complexType>




7/18/2019 C5617M-A


C5617M-A | Hardware Diagnostics Event Mes

Fans (20020)

Any device with any fans having a changed state will have a LoggableEvent fired.

PdDiagnostic


<complexType name="FanPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/><element name="objId" type="xs:int" fixed="20050"/><element name="states" type="tns:FanStates"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: 31e41907-53be-4f57-8ae2-

a56c12d98d0e

objId

The event's unique database identifier. The value must be: 20050states

A FanStates data type.

FanStates

This contains list of one or more FanState data types.

<complexType name="FanStates"><sequence><element name="state" maxOccurs="unbounded" minOccurs="1"type="tns:FanState"/></sequence></complexType>

state

A FanState data type.

FanState

This represents the current and previous condition of a fan.

<complexType name="FanState"><sequence><element name="cur" type="xs:int"/><element name="prev" type="xs:int"/></sequence></complexType>

cur

The current state identifier. Possible values are the following:

1 for FAN_OK

The fan is operating normally.

2 for FAN_FAILED

The fan has failed.

3 for FAN_UNKNOWN

The state of the fan is currently unknown; this fan does not have an initial state registered. NOTE:

This will always be the final stream state.

7/18/2019 C5617M-A



4

prev

The previous state identifier. This has the same possible values as cur.

<pdDiagnostic><objGuid>31e41907-53be-4f57-8ae2-a56c12d98d0e</objGuid><objId>20220</objId><states><state><cur>1</cur>

<prev>0</prev></state><state><cur>0</cur><prev>0</prev></state><state><cur>0</cur><prev>0</prev></state></states></pdDiagnostic>




HardDrives (20060)

For each CPdDiagHarddrives object, you can send loggable events for hard drives that have a state change. Setthe state of the hard drive to the appropriate major, minor, type, and reason.

PdDiagnostic


<complexType name="HardDrivesPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/><element name="objId" type="xs:int" fixed="20060"/><element name="states" type="tns:HardDrivesStates"/></sequence>

</complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: 31e41907-53be-4f57-8ae2-

a56c12d98d0e

objId

The event's unique database identifier. The value must be: 20060

states

A HardDrivesStates data type.

7/18/2019 C5617M-A



HardDrivesStates

This contains a list of one or more HardDrivesState data types.

<complexType name="HardDrivesStates"><sequence><element name="state" maxOccurs="unbounded" minOccurs="1"type="tns:HardDrivesState"/></sequence></complexType>

state

A HardDrivesState data type.

HardDrivesState

This represents the current and previous condition of a hard drive.

<complexType name="HardDrivesState"><sequence><element name="cur" type="xs:int"/><element name="prev" type="xs:int"/></sequence></complexType>

cur

The current state identifier. Possible values are the following:

1 for HDS_READY

Indicates that the hard disk is currently in use.

NOTE: This may indicate a problem if the disk is known to be currently NOT in use.

2 for HDS_ONLINE

Indicates that a disk is online and currently being used.

3 for HDS_FAILED

Indicates that a disk has failed.

4 for HDS_HOTSPAREIndicates that a disk is currently being used as a 'hot spare' within the array.

5 for HDS_REBUILD

Indicates that a disk is currently being rebuilt.

6 for HDS_NONE

Shows that there is currently no hard drive connected, and there is room for a hard drive.

7 for HDS_UNKNOWN

The hard drive's state is currently unknown; this typically means that the hard drive has yet to

register any state.

NOTE: This will always be the final stream state.

prevThe previous state identifier. This has the same possible values as cur.

<pdDiagnostic><objGuid>8dda89bd-3c2c-4a35-aad4-1256cb5e1d27</objGuid><objId>20060</objId><states><state><cur>1</cur><prev>2</prev></state><state><cur>1</cur>

7/18/2019 C5617M-A



6

<prev>1</prev></state><state><cur>1</cur><prev>1</prev></state></states></pdDiagnostic>



<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>9</type><reason>1</reason><parameters><param><paramId>6</paramId>

<name>HardDriveId</name><value>0</value><type>1</type></param></parameters>

ImproperShutdown (20070)

A ImproperShutdownPdDiagnostic object is sent when an improper shutdown occurs, so a LoggableEvent object canbe initialized with the appropriate major, minor, type, and reason data.

PdDiagnostic


<complexType name="ImproperShutdownPdDiagnostic"><sequence> <element name="objGuid" type="xs:string"fixed="a44945e0-fa54-4fb0-a614-2e71886c508f"/><element name="objId" type="xs:int" fixed="20070"/><element name="mode" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: a44945e0-fa54-4fb0-

a614-2e71886c508f

objIdThe event's unique database identifier. The value must be: 20070

mode

The mode of the shutdown.

<pdDiagnostic><objGuid>a44945e0-fa54-4fb0-a614-2e71886c508f</objGuid><objId>20070</objId><mode>4</mode></pdDiagnostic>

7/18/2019 C5617M-A






LinkSpeed (20200)

This event triggers when the link speed changes. We then set the correct major, minor, type, and reason for

LoggableEvent. The current LinkSpeed is sent as a parameter with the LoggableEvent object.

PdDiagnostic


<complexType name="LinkSpeedPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="b9359885-711a-4d71-b908-4bdf8753dbe8"/><element name="objId" type="xs:int" fixed="20200"/><element name="min" type="xs:int"/><element name="cur" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: b9359885-711a-4d71-

b908-4bdf8753dbe8

objId

The device's unique database identifier. The value must be: 20200

min

The minimum link speed. For example: 100

cur

The current state. For example: 10

<pdDiagnostic><objGuid>b9359885-711a-4d71-b908-4bdf8753dbe8</objGuid><objId>20200</objId><min>100</min><cur>10</cur></pdDiagnostic>



<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>6</type><reason>0</reason>

7/18/2019 C5617M-A



8

<parameters><param><paramId>5</paramId><name>CurrentLinkSpeed</name><value>10</value><type>1</type></param></parameters>

PowerSupply (20120)

A PowerSupplyPdDiagnostic object is sent when a power supply encounters a problem so that a

LoggableEvent object can be initialized with the appropriate major, minor, type, and reason data.

PdDiagnostic


<complexType name="PowerSupplyPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="26f051aa-009b-4a5d-ab20-09b064a07a52"/>

<element name="objId" type="xs:int" fixed="20120"/><element name="inAlarm" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be: 26f051aa-009b-4a5d-

ab20-09b064a07a52

objId

The device's unique database identifier. The value must be: 20200

inAlarm

This represents whether or not a device is in a problem state. Possible values are:

0

The power supply is operating properly; not in an alarm state.

1

Problems with the power supply; in alarm state.

<pdDiagnostic><objGuid>26f051aa-009b-4a5d-ab20-09b064a07a52</objGuid><objId>20120</objId><inAlarm></inAlarm></pdDiagnostic>




7/18/2019 C5617M-A



UPS (20170)

This event triggers if a UPS either fails or runs out of power.

PdDiagnostic


<complexType name="UPSPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="e746c2c8-0b97-402e-abc3-c784890c8d99"/><element name="objId" type="xs:int" fixed="20170"/><element name="cur" type="xs:int"/><element name="pre" type="xs:int"/><element name="rem" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be: e746c2c8-0b97-402e-abc3-

c784890c8d99

objId


cur

The current state identifier. For example: 4

pre

The previous state identifier. For example: 1

<pdDiagnostic><objGuid>e746c2c8-0b97-402e-abc3-c784890c8d99</objGuid><objId>20170</objId><Cur>4</Cur><Pre>1</Pre><Rem>0</Rem>

</pdDiagnostic>



<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>24</type><reason>0</reason><parameters><param><paramId>4</paramId><name>TimeRemaining</name><value>0</value><type>1</type></param></parameters>

7/18/2019 C5617M-A



0

7/18/2019 C5617M-A


Appendix

FSoftware Diagnostics Event Messsages

DataLoss 20040

When this is triggered by a data loss, set the correct major, minor, type, reason for the LoggableEvent.

PdDiagnostic

This is the data that subscribers will receive when the event triggers.

<complexType name="DataLossPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/><element name="objId" type="xs:int" fixed="20040"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: 94b6d2d3-

c68e-4b13-974a-08f69f50cb67

objId


<complexType name="DataLossPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/><element name="objId" type="xs:int" fixed="20040"/></sequence></complexType>

LoggableEvent object



7/18/2019 C5617M-A


617M-A | Software Diagnostics Event Messsages

2

InputStreams 20160

For each stream entry that has its state changed from previous state, we send out a loggable event with appropriate

major, minor, type and reason.

<complexType name="InputStreams"><sequence>

<element name="objGuid" type="xs:string"fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/><element name="objId" type="xs:int" fixed="20160"/><element name="states" type="tns:InputStreamsEntries"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be set to: 31e41907-53be-4f57-8ae2-a56c12d98d0e

objId


entries

An InputStreamsEntries data type.

<pdDiagnostic><objId>20160</objId><context>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</context><entries><entry><id>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</id><mediaType>0</mediaType><hardwareId>1</hardwareId><channelId>1</channelId><stateCur>4</stateCur><statePrev>2</statePrev></entry></entries></pdDiagnostic>

InputStreamsEntries

A list of InputStreamsEntry data types.

<pdDiagnostic><objId>20160</objId><context>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</context><entries><entry><id>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</id><mediaType>0</mediaType><hardwareId>1</hardwareId><channelId>1</channelId><stateCur>4</stateCur>

<statePrev>2</statePrev></entry></entries></pdDiagnostic>

entry

An InputStreamsEntry data type.

InputStreamsEntry

<complexType name="InputStreamsEntry">

7/18/2019 C5617M-A


C5617M-A | Software Diagnostics Event Mes

<sequence><element name="id" type="xs:string"/><element name="mediaType" type="xs:int"/><element name="hardwareId" type="xs:string"/><element name="stateCur" type="xs:int"/><element name="statePrev" type="xs:int"/></sequence></complexType>

idThe entry's unique identifier, for example: 2

mediaType

A media type identifier, for example: 0

hardwareId

A hardware identifier, for example: hwidv1

stateCur

The current state identifier. Possible values are:

1 for ISS_RECORDING

Currently recieving a stream and it is being recorded.

2 for ISS_RECORD_ERROR

Currently receiving a stream, but it is unable to be recorded due to an error.3 for ISS_RECEIVING

Currently recieving a stream.

4 for ISS_RECEIVE_ERROR

Unable to receive a stream.

5 for ISS_MISSING

Expecting a stream but there is no available stream. In analog inputs, this means the device is

unable to detect a connection.

6 for ISS_UNKNOWN

The state of the stream is currently unknown; this stream does not have an initial state registered.

NOTE: This will always be the final stream state.

statePrev

The previous state identifier. Refer to stateCur for possible valid values.

PacketLoss 20080

This event is fired when there is data loss during video data writing. Sets the appropriate major, minor, type, andreason in Loggable Event .

PdDiagnostic


<complexType name="PacketLossPdDiagnostic"> <sequence> <element name="objGuid" type="xs:string" fixed="ddfa09d6-64f1-4b39-a7e7-de0c5f7780cc"/> <element name="objId" type="xs:int" fixed="20080"/> <element name="max" type="xs:float"/> <element name="cur" type="xs:float"/> </sequence></complexType>

objGuid

7/18/2019 C5617M-A



4

The event's Universally Unique Identifier. The value must be: ddfa09d6-64f1-4b39-a7e7-

de0c5f7780cc

objId


max

The maximum acceptable packet loss percentage, for example: 1.1235

cur

The current packet loss percentage, for example: 5.1235



<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>11</type><reason>0</reason><parameters><param><paramId>3</paramId><name>PercentageOfCurrentPacketLoss</name><value>5.1235</value><type>0</type></param></parameters>

SEBs 20210

For each PdDiagSebs object, loggable events are sent only when the state of a particular SEB changes. Set the stateof the SEB to the appropriate major, minor, type, and reason.

PdDiagnostic


<complexType name="SEBsPdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/><element name="objId" type="xs:int" fixed="20210"/><element name="entries" type="tns:SEBSEntries"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be: 31e41907-53be-4f57-8ae2-a56c12d98d0e

objId


entries

An SEBsEntries data type.

7/18/2019 C5617M-A



SEBsEntries

A list of SEBsEntry data types.

<complexType name="SEBsEntries"><sequence><element name="entry" maxOccurs="unbounded" minOccurs="1"type="tns:SEBsEntry"/></sequence></complexType>

entry

An SEBsEntry data type.

SEBsEntry

<complexType name="SEBsEntry"><sequence><element name="stateCur" type="xs:int"/><element name="statePrev" type="xs:int"/></sequence><attribute name="id" type="xs:string" fixed="US"/></complexType>

stateCur

The current state identifier.

statePrev

The previous state identifier. Refer to stateCur for valid possible values.

id

(Attribute) The entry's identifier - string.

<pdDiagnostic><objGuid>2e9f0d2e-adf3-453b-aabc-a0223a604040</objGuid><objId>20210</objId><entries><entry id="hello0"><stateCur>0</stateCur>

<statePrev>0</statePrev></entry><entry id="hello1"><stateCur>0</stateCur><statePrev>0</statePrev></entry><entry id="hello2"><stateCur>0</stateCur><statePrev>0</statePrev></entry><entry id="hello5"></entry></entries></pdDiagnostic>



<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>9</type><reason>2</reason><parameters>

7/18/2019 C5617M-A



6

<param><paramId>7</paramId><name>SEBId</name><value>hello4</value><type>0</type></param></parameters>

StorageFull 20190

When this event triggers from a device with fully used storage, the appropriate major, minor, type, and reason is set inthe Loggable event.

PdDiagnostic

This is the data that subscribers receive when the event triggers.

<complexType name="StorageFullPdDiagnostic"><sequence><element name="objGuid" type="xs:string" fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/><element name="objId" type="xs:int" fixed="20190"/>

<element name="inAlarm" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be: 94b6d2d3-

c68e-4b13-974a-08f69f50cb67

objId


inAlarm

This represents whether or not a device is in a problem state. Possible values are:

0for storage is not full

Not in an alarm state.

1 for full storage

In an alarm state.

<pdDiagnostic><objGuid>3df223ee-8041-4c1a-be77-2d140e5588aa</objGuid><objId>20190</objId><inAlarm></inAlarm></pdDiagnostic>


For more details, refer to DataLoss 20040 LoggableEvent above.


7/18/2019 C5617M-A



StorageTime 20130

This event is fired if the NVR/DVR is unable to achieve the user-configured video storage time.

PdDiagnostic


<complexType name="StorageTimePdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0"/><element name="objId" type="xs:int" fixed="20130"/><element name="min" type="xs:int"/><element name="cur" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be: e08fa1d1-9b30-4e62-

bc8b-16cca0f57cb0

objId


min

The minimum number of hours of storage time allowed.

cur

The current number of hours of storage time available.

<pdDiagnostic><objGuid>e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0</objGuid><objId>20130</objId><min>5</min><cur>4</cur></pdDiagnostic>



<deviceUdn>uuid:AK-2</deviceUdn><deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn><serviceUrn></serviceUrn><logId></logId><major>7</major><minor>0</minor><type>12</type><reason>0</reason><parameters><param><paramId>8</paramId><name>CurrentStorageTime</name><value>4</value><type>1</type></param></parameters>

Temperature 20140

A Temperature PdDiagnostic object is triggered when temperature goes beyond specific range. The current

range is set between 10°C - 50°Celsius. This verifies if the current temperature is below minimum or above maximum

7/18/2019 C5617M-A



8

threshold, and then determines whether to send Loggable Events, with reason set to either LOW or HIGHaccordingly.

PdDiagnostic


<complexType name="TemperaturePdDiagnostic"><sequence><element name="objGuid" type="xs:string"fixed="26f051aa-009b-4a5d-ab20-09b064a07a52"/><element name="objId" type="xs:int" fixed="20140"/><element name="min" type="xs:int"/><element name="max" type="xs:int"/><element name="cur" type="xs:int"/></sequence></complexType>

objGuid

The event's Universally Unique Identifier. The value must be: 26f051aa-009b-4a5d-

ab20-09b064a07a52

objId


min

The minimum allowable temperature.

max

The maximum allowable temperature.

cur

The current temperature.

<pdDiagnostic><objGuid>7448f68a-de77-4ea9-b000-65b63bf54bd5</objGuid><objId>20140</objId><min>10</min><max>20</max>

<cur>5</cur></pdDiagnostic>




<parameters><param><paramId>1</paramId><name>CurrentTemperature</name><value>5</value><type>1</type></param></parameters>

7/18/2019 C5617M-A


Appendix

GGlossary

ActiveX

Active X is an integration platform that provides developers, users, and Web producers a fast and easy way to create

integrated programs and content for Microsoft based Internet and Intranet software. For more information, refer tohttp://support.microsoft.com/kb/154544

Advertisement (UPnP)In a UPnP network, advertisement is the act of one device presenting its services for another device to use. In Endura,

the UPnP advertisement startup and renew intervals are set from the System Configuration tab of the Setup window.Alarm

In video security: An alarm occurs when a camera detects motion or there is a change in a physical alarm input, such

as a door opening or closing.

In card access: This is a condition caused by a system event or action to raise awareness to security staff.

Alarm relay

The alarm relay is the relay used to output an alarm condition based on a specific system or event message criteria.Auto-focus

Auto-focus is the ability of the lens to remain in focus during zoom-in, zoom-out, and motion functions.

bitAbbreviation for binary digit; the smallest unit of information a computer can use. A bit is either a 1 or a 0 (a high or low

voltage state).bit rate

Bit rate is the number of bits that are transferred between devices in a specified amount of time, typically one second.Brightness

In NTSC and PAL video signals, the brightness information at any particular instant in a picture is conveyed by the

corresponding instantaneous DC level of active video. Brightness control should be adjusted so that the black picturecontent displays as true black on your monitor.

bpsBits per second. This is a bit rate measurement.

Bps

Bytes per second. Also abbreviated as B/s.Broadcast

In an IP network environment, broadcast refers to sending information from one device to every device on the network.When broadcasting, it is not possible to control or specify which devices can receive this information.

byte

A byte is a string of bits processed as a unit by a digital computer. A byte is equal to eight bits (256 possibilities) and islarge enough to hold one character (like an “A”) or an unsigned integer from 0 to 255.

Camera groupIn an Endura system, a camera group is a collection of cameras associated with each other as part of the setup

process. Camera groups may be used in filtering cameras displayed in the Nav window, as well as those selected forschedules, scripts, or permissions.

Coaxitron

Coaxitron is the Pelco protocol that uses “up the coax” technology. Commands to control pan/tilt devices aretransmitted during the vertical blanking interval of the video signal. Instead of separate wiring for control commands

and video, Coaxitron uses the coaxial cable for both video and control.

Standard: This older technology uses 15 bits to send a command.

Extended: This newer technology uses 32 bits to send a command.

codec

http://support.microsoft.com/kb/154544

http://support.microsoft.com/kb/154544

7/18/2019 C5617M-A


617M-A | Glossary

0

Codec is an acronym for compression/decompression. This term is commonly used in the context of multimediacompression and decompression, such as video or audio.

Common Intermediate Format (CIF)

A standard video and digital image size. Also refer to SIF.

CIF: 352 x 288 for PAL

2CIF: 704 x 288 for PAL

4CIF: 704 x 480 for PAL

QCIF: 176 x 144 for PAL

Compression

Compression is any algorithm used to reduce the size of a file.Contrast

Contrast is a common term used in reference to the difference between the darkest and the brightest parts of an

image. Once brightness is set correctly, contrast should be set for comfortable viewing brightness.D1

D1 is a digital video format developed by Society of Motion Picture and Television Engineers (SMPTE). The D1 formatresolution is 720 × 480 for NTSC and 720 × 576 for PAL.

Decoder

In an Endura system, the decoder is a high-performance video device that converts digital video streams back intoanalog output for viewing on an analog video monitor, S-video monitor, or VGA monitor.

DecodingDecoding is the opposite of encoding: decompressing a compressed digital image and then turning it back into an

analog signal.Device

A device is a piece of hardware (camera, alarm, DVR, NVR, storage expansion box) that is part of a network.

Device IDA device ID is a unique identifier for an individual device on a network.

EncoderIn an Endura system, the encoder is a high-performance MPEG-4 device that takes analog video signals through

a standard BNC coax and digitizes, compresses, signs, and packetizes them for the network. It also provides an

interface for relays, alarms, and audio connections.Encoding

Encoding is the process of taking an analog signal and converting it to a digital format (A to D conversion).Compression is applied at this point in the process.

Firmware

Firmware is a process or program that is embedded in a hardware platform that instructs the hardware unit how tobehave and what action to perform.

FocusFocus means to adjust a lens to allow objects at various distances from the camera to be sharply defined.

Frame rateThe frame rate is the number of frames or images that are captured, stored, projected, or displayed per second.

Gamma

Gamma is the correction of the linear response of a camera to compensate for the nonlinear response of a monitor’sphosphor screen. It is measured with the exponential value of the curve describing the nonlinearity. A typical

monochrome monitor gamma is 2.2, and a camera needs to be set to the inverse value of 2.2 (which is 0.45) for theoverall system to respond linearly (that is, unity).

H.264

Developed by the ITU-T Video Coding Experts Group (VCEG), H.264 is a low-bit-rate compressed video formatstandard.

HueHue is one of the characteristics that distinguishes one color from another. Hue defines color on the basis of its

position in the spectrum, that is, whether red, blue, green or yellow, etc. Hue is one of the three characteristics of

television color; the other two are saturation and luminance. In NTSC and PAL video signals, the hue information atany particular point in the picture is conveyed by the corresponding instantaneous phase of the active video subcarrier.

I-frameIn a compressed digital image, I-frames (intraframes) are the frames that are compressed independently of the other

frames in the sequence.IP

Internet Protocol. IP is the main method of transmitting data across the Internet.

IP address

7/18/2019 C5617M-A


C5617M-A | G

(static and DHCP) The IP address identifies a particular computer on a network to other computers. An IP addressis similar to your home address. In a neighborhood, each house has a unique address; on a network each computer

must have a unique address. An IP address is a four-byte number, usually written in dotted-decimal notation with

periods separating the bytes (for example, 192.168.0.100). There are two types of IP addresses: static and DCHP.A static address is assigned when someone physically connects to a computer and defines the IP address for

that computer. A static address does not change unless someone physically changes it. A DHCP (Dynamic HostConfiguration Protocol) address is assigned dynamically from a server that contains a pool of addresses. The server

leases the computer one of the available addresses for a specified amount of time. Once the time has expired, thecomputer renews the lease or requests a new IP address.

IP camera

An IP camera is a digital video camera that outputs IP packets over Ethernet cabling. An IP camera may use TCPprotocol, as well as UDP or RTP.

IP headerAn IP packet can be divided into two main parts: the payload and the header. The header is the part of the packet that

contains the routing information, and is is comprised of many parts. The header contains all IP and MAC addressing

information. The header is the only part of the packet that a router examines when trying to determine where to send apacket.

IrisThe iris is a means of controlling the size of a lens aperture and therefore the amount of light passing through the lens.

marshalling

Marshalling is synonymous with serialization.MPEG-4

Developed by Moving Picture Experts Group (MPEG), MPEG-4 expands the MPEG-1 specification to support AV‘objects’, 3D content, low bit-rate encoding, and Digital Right Management (DRM).

MulticastA single device sends information across a network and that stream is received by all listening devices on the network.

A special IP address range has been reserved for this purpose: 224.0.0.1-239.255.255.255 with a sub-net mask

of 255.255.0.0. Each multicast transmitting device sends a data stream to an address from the above range. Anydevice on the network can then listen for transmissions to that IP address and receive the stream. Multicast offers a

reduction of bandwidth consumption over the unicast and broadcast delivery methods. Multicast also offers controlover which devices on a network can receive a multicast stream. In an Endura system, only Endura devices can

receive Endura multicast streams. Multicast traffic is not routable across the Internet without a specially reserved

address or encapsulation.Multicast server

A multicast server is any server that takes a unicast transmission on behalf of a client and converts it to a multicasttransmission on the network.

Namespace

Namespace is an identifier that denotes a group of names. It is used to prevent resource identifier conflicts.Network Time Protocol (NTP)

NTP is a protocol designed to synchronize the clocks of computers over a network. On systems that have an NTPserver, you may use the WS5050 to configure the NTP settings (NTP server IP and renew interval). By default, time

and date information is included with video streams and other device data. The software relies on the PC system clockfor other needed time information.

National Television System Committee (NTSC)

NTSC developed the U.S. color TV specifications. It specifies 525 lines/screen. It also specifies 59.94 fields persecond, although most people refer to this frame rate as 30 frames per second. NTSC now describes the American

system of color telecasting. It is used in North America, Japan, and some parts of South America.Network Storage Manager (NSM)

A combination of high performance, scalable hardware and advanced software for managing pooled storage of

recorded video and audio streams.Phase Alternation by Line (PAL)

PAL is the European (50 Hz) color TV standard. It is used by most foreign countries around the world. It specifies 625lines/screen, and 25 frames per second.

Parity

Parity is a method of checking the accuracy of data to identify whether the bits being moved arrived successfully.Parity bit checking can be based on odd or even bits. No parity means that a parity bit is not transmitted or checked.

P-frameIn a compressed digital image, a P-frame (predicted frame) is a frame calculated based on the change from one frame

to the next. An area of the display that does not change from one frame to the next does not need to be contained inthe P-frame. If an area of the display does not change but does move on the screen, then only the vector describing

this movement is contained in the P-frame. This allows a reduction in overall file size.

PIN

7/18/2019 C5617M-A


617M-A | Glossary

2

Personal Identification Number. PIN is used to provide security in a system.Power over Ethernet (PoE)

PoE enables both power and video to transmit on a single cable.Protocol

Protocol is a set of rules governing the transmission of data between equipment:

D Pelco protocol that uses 7 bytes to send a command.

M Pelco protocol for communicating with M devices (KBD960/KBR960 keyboards, ALM2064 alarm interface units, and

REL2064 relay interface units).

P Pelco protocol that uses a variable number of bytes to send a command. Eight bytes are used to send commands todome systems.

Relay groupA relay group is a defined set of relays acting in a coordinated pattern.

Remote Procedure Calls (RPCs)RPC is a protocol that allows a computer program running on one host to cause code to be executed on another host.

Real-time Transport Protocol (RTP)

A protocol that uses a standardized packet format for delivering data over networks.Real Time Streaming Protocol (RTSP)

A protocol for streaming data, which allows clients to remotely control the server streaming the data.Saturation

Saturation is the intensity of the colors in the active picture: the degree by which the eye perceives a color as departing

from a gray or white scale of the same brightness. A 100% saturated color does not contain any white; adding whitereduces saturation. In NTSC and PAL video signals, the color saturation at any particular instant in the picture is

conveyed by the corresponding instantaneous amplitude of the active video subcarrier.Sequence

To view a group of cameras, one after the other, either manually or automatically.Server

A server is a computer and its software that provides some service for other computers connected to it through a

network.Service

Service is the ability of a device within the Endura system to perform such functions as pan/tilt/zoom, record video,and playback video. When a device comes online, these services are automatically advertised to other devices on the

network. For a user to access these services, the user must be assigned a role with the proper permissions.Sharpness

Sharpness refers to a function that allows a user to adjust the image between a “soft” look and a sharp look.

SIF Source Input Format. Resolution depends on the source: NTSC SIF equals 352 x 240 pixels. Also refer to CIF.

System Manager (SM)A piece of software that authenticates devices on the Endura network. This software runs on an Endura DVR or NVR

or as a standalone device.

TCP/IP connectionTransmission Control Protocol/Internet Protocol. TCP/IP is the standard way of communicating over a network that

ensures all devices on a network can communicate and information is passed without any errors.UDN

Universal Device Number.

UDPUser Data-gram Protocol is a connectionless protocol that, like TCP, runs on top of IP networks. Unlike TCP/IP, UDP/

IP provides very few error recovery services, offering instead a direct way to send and receive data-grams over an IPnetwork. It is used primarily for broadcasting messages over a network.

UID Universal Identification Number.Unicast

The standard method to transport IP traffic. In a unicast transmission, information is sent from one computer directly toanother computer on the network.

UPnPUPnP is a family of networking protocols used to create a “hands off” network. In a Universal Plug and Play network,

objects are plugged into a network and automatically recognized and configured. All IP addresses in a UPnP network

are assigned dynamically through DHCP. If DHCP becomes unavailable in a UPnP network, devices will default toAuto IP. Endura devices use the UPnP process when plugged into an Endura network.

Uniform Resource Identifier (URI)URI is used to identify a resource over a network.

7/18/2019 C5617M-A


C5617M-A | G

Uniform Resource Name (URN)A URN identifies, or more specifically, names a resource within a namespace.

Varifocal

Varifocal refers to a lens with a variable focal length. Varifocal lenses are low cost zoom lenses that can be adjusted

(zoomed) over a range of focal lengths. These lenses are much lower in cost than normal zoom lenses because theyhave fewer elements in them.

Disadvantage: Unlike a zoom lens, a varifocal lens does not maintain focus when zoomed. It is practical only for usewith cameras where the zoom is set once at installation.

Advantage: The installer can adjust a varifocal lens for optimum field of view without changing the lens.

WSDL

Web Services Description Languages (WSDLs).

7/18/2019 C5617M-A


617M-A | Glossary

4

7/18/2019 C5617M-A


Pelco by Schneider Electric 3500 Pelco Way Clovis, California 93612-5699 United States

USA & Canada Tel (800) 289-9100 Fax (800) 289-9150

International Tel +1 (559) 292-1981 Fax +1 (559) 348-1120

c5617m-a

Documents