Pelco SDK 3.3.1 Programming Guidepdn.pelco.com/sites/default/files/docs/PelcoSDK_C5617M-G.pdf · The Pelco SDK provides the following functionality: • Video rendering • Device

PROGRAMMING

Pelco SDK 3.3.1 ProgrammingGuide

C5617M-G (10 / 2013)

2 C5617M-G (10 / 2013)

Table of Contents

Chapter 1: Introduction............................................................................................ 7

Getting Started with the Pelco SDK........................................................................................... 7Installing the Pelco SDK............................................................................................................. 9General Requirements.............................................................................................................. 10System Environment Settings for the Pelco SDK.....................................................................11Including Required SDK Components For Your Application.................................................... 11Setting Up Sample Projects......................................................................................................12

Registering the ActiveX Control..................................................................................... 12Adding References to Managed Libraries for C#...........................................................12

Chapter 2: Device Caching Using Object Model................................................. 16

Overview....................................................................................................................................16Initializing a Pelco SDK Application..........................................................................................16Device Caching......................................................................................................................... 19Samples.....................................................................................................................................20

Chapter 3: Integrating Pelco Edge Systems and Devices Using ObjectModel.................................................................................................................... 24

Overview....................................................................................................................................24Adding a Pelco Edge System To a System Collection.............................................................24Removing a Pelco Edge System From a System Collection....................................................24Adding a Pelco Edge Device To a Device Collection...............................................................24Removing a Pelco Edge Device From a Device Collection......................................................25

Chapter 4: Network Displays Using Object Model.............................................. 27

Overview....................................................................................................................................27Using a Network Display...........................................................................................................27

Chapter 5: Displaying and Controlling Streams Using Object Model................29

Overview....................................................................................................................................29Samples.....................................................................................................................................29Initializing a Stream Object.......................................................................................................29Working With Stream Configurations........................................................................................31Constructing a New Stream Configuration............................................................................... 32Changing a Stream Configuration............................................................................................ 33Playing Back Recorded Video.................................................................................................. 33Playing a Stream Forward........................................................................................................ 34Playing a Stream in Reverse....................................................................................................35Pausing a Stream..................................................................................................................... 36Resuming Playback of a Paused Stream.................................................................................36Switching From Playback to Live..............................................................................................36Stepping Through a Video Stream........................................................................................... 36

C5617M-G (10 / 2013) 3

Taking a Snapshot.................................................................................................................... 37Setting the Stream Volume.......................................................................................................37Getting the Stream State.......................................................................................................... 37Getting the Stream Mode..........................................................................................................37

Chapter 6: Displaying and Controlling Streams Using PelcoAPIViewer........... 39

Overview....................................................................................................................................39Initializing the Pelco API Viewer (C++).....................................................................................39Initializing the Pelco API Viewer (C#).......................................................................................40

Using the PelcoAPIViewer Component..........................................................................40Using the PelcoAPIMPFViewerControl Component.......................................................41

Setting Size and Position of Video Display Area......................................................................42Querying an RTP Stream......................................................................................................... 42Opening, Playing, and Displaying a Live or Playback RTP Stream......................................... 44Opening, Playing, and Displaying an RTSP Stream................................................................ 46Forward Playback of RTP and RTSP Streams........................................................................ 46Reverse Playback of RTP and RTSP Streams........................................................................ 47Fast Forward / Reverse Playback of RTP and RTSP Streams................................................ 47Pausing RTP and RTSP Playback Streams.............................................................................48Frame Forward Playback of the RTP Stream.......................................................................... 48Frame Reverse Playback of the RTP Stream.......................................................................... 48Resuming the RTP or RTSP Stream from a Paused State......................................................49Stopping the RTP and RTSP Stream.......................................................................................49Start Manual Recording of RTP Stream...................................................................................49Stop Manual Recording of RTP Stream................................................................................... 50Setting Audio Volume of a Live or Playback RTP stream........................................................50Displaying Analytic Events for an RTP Stream........................................................................ 50Displaying Motion Events for an RTP Stream..........................................................................51Displaying a Timestamp Overlay for RTP and RTSP Streams................................................ 51Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams..........................52Pan, Tilt, Zoom (PTZ) Control for RTP Stream Using PelcoAPIViewer....................................52

Chapter 7: Pan, Tilt, Zoom (PTZ) Control.............................................................53

Overview....................................................................................................................................53Initializing the PTZ Control Wrapper.........................................................................................53Continuous Panning.................................................................................................................. 55Continuous Tilting......................................................................................................................55Continuous Diagonal Movement............................................................................................... 56Stopping Continuous Movement............................................................................................... 57Enabling Continuous Pan/Tilt/Move and Zoom APIs by UDP Instead of TCP..........................57Panning to a Specific Position..................................................................................................57Tilting to a Specific Position..................................................................................................... 58Moving to a Specific Position................................................................................................... 58Moving to a Position Relative to the Current Location............................................................. 59Getting the Camera’s Current Position.....................................................................................59Managing the Magnification (Zoom) Value...............................................................................59Managing the Focus Value.......................................................................................................60Iris Control................................................................................................................................. 61Scripting.....................................................................................................................................62Creating a Preset...................................................................................................................... 62Updating an Existing Preset..................................................................................................... 63Creating a Pattern.....................................................................................................................63Going to an Existing Preset......................................................................................................64

4 C5617M-G (10 / 2013)

Removing an Existing Preset....................................................................................................64Updating an Existing Pattern.................................................................................................... 64Executing an Existing Pattern...................................................................................................64Stopping a Pattern Currently Being Executed..........................................................................65

Chapter 8: Events and Alarms.............................................................................. 66

Overview....................................................................................................................................66Where Does the Pelco SDK Fit?................................................................................... 66Event Arbiter Library...................................................................................................... 66Event Manager............................................................................................................... 67

Event Arbiter Library Compared to Event Manager................................................................. 68Creating an Event Agent.......................................................................................................... 68Returning the Event Subscription URL.....................................................................................72Initializing the Event Arbiter Library.......................................................................................... 72

Initializing the Event Arbiter Library for C++.................................................................. 72Initializing the Event Arbiter Library for C#.................................................................... 73

Initializing the Event Manager...................................................................................................74Device or Service Specific Subscriptions................................................................................. 75

Using the Event Arbiter Library to Subscribe Using the Device’s IP Address................ 75Using the Event Arbiter Library to Subscribe Using the Event Subscription URL.......... 75Using the Event Arbiter Library to Subscribe to All Instances of a Service....................76Using the Event Arbiter Library to Subscribe to a Device's Web Service...................... 77Using the Event Arbiter Library to Unsubscribe from a Service.....................................77

Mass Subscriptions by Category.............................................................................................. 78Using the Event Manager to Subscribe to All Services................................................. 78Using the Event Manager to Unsubscribe from All Services......................................... 79

Handling Incoming Events........................................................................................................ 79Polling Events............................................................................................................................82

Chapter 9: Extracting Audio and Video Metadata............................................... 83

Extracting Audio and Video Metadata...................................................................................... 83Motion Detection Metadata....................................................................................................... 83Pelco Analytics Drawing Primitives...........................................................................................84Timestamps............................................................................................................................... 84Getting Started.......................................................................................................................... 85Initializing the Metadata Parser Class...................................................................................... 85Creating a Metadata Renderer Class....................................................................................... 85Retrieving the Current Timestamp Metadata............................................................................86Motion Detection Metadata....................................................................................................... 87

Retrieving Motion Detection Metadata........................................................................... 87Rendering Motion Detection Metadata...........................................................................87

Drawing Metadata..................................................................................................................... 88Retrieving Drawing Metadata......................................................................................... 88Rendering Drawing Metadata.........................................................................................88

Chapter 10: Exporting Video................................................................................. 90

Overview....................................................................................................................................90Where Does the Pelco SDK Fit?................................................................................... 90

Custom Application Development............................................................................................. 90Getting Started.......................................................................................................................... 91Initializing the Exporter..............................................................................................................91

C5617M-G (10 / 2013) 5

Setting Up Overlay Data on Video to Be Exported.................................................................. 92OverlayData Parameters................................................................................................ 93Resetting Overlay Data.................................................................................................. 96

Exporting Video......................................................................................................................... 96Exporting a Single Video Clip........................................................................................ 96Exporting Video Using a Playlist (PPX)......................................................................... 97Stitching Multiple Clips into a Single Video Export........................................................ 99

Polling a Video Export............................................................................................................ 101Stopping a Video Export.........................................................................................................102Exporting A JPEG Snapshot...................................................................................................102

Chapter 11: Web Service Proxies....................................................................... 103

Web Service Proxies...............................................................................................................103General Usage........................................................................................................................ 103

Chapter 12: Discovery..........................................................................................105

Device and Service Discovery Overview................................................................................105Initializing the Pelco SDK System Manager Wrapper............................................................ 106Automatically Determining the System Manager’s IP Address and Port Number...................107Logging In and Logging Out................................................................................................... 107Querying Available Devices from the System Manager......................................................... 108

Retrieving the System Manager’s Time Zone..............................................................109Retrieving the Network Time Server Address..............................................................109Retrieving a Web Service’s ID..................................................................................... 110Retrieving a Specific Web Service’s Control URL....................................................... 111Retrieving the NVR Associated with the Device.......................................................... 111Retrieving the Device’s Friendly Name........................................................................112Retrieving the Device’s Device Description File (DDF) URL....................................... 113Retrieving All Web Services Available on a Device.....................................................113

Retrieving Device Attributes....................................................................................................114Retrieving a System Manager’s Attribute.....................................................................115Retrieving a Web Service’s Attribute........................................................................... 116

Creating an IDeviceStorage Class..........................................................................................117

Appendix A: Logging............................................................................................119

Appendix B: Product Compatibility.................................................................... 120

Appendix C: Endura............................................................................................. 122

Appendix D: General Event Messages............................................................... 125

Appendix E: Hardware Diagnostics Event Messages....................................... 127

ConfigurationButton (20180)................................................................................................... 127DriverFailure (20150).............................................................................................................. 128

6 C5617M-G (10 / 2013)

Fans (20020)........................................................................................................................... 128HardDrives (20060)................................................................................................................. 130ImproperShutdown (20070).....................................................................................................132LinkSpeed (20200).................................................................................................................. 133PowerSupply (20120)..............................................................................................................134UPS (20170)............................................................................................................................134

Appendix F: Software Diagnostics Event Messages........................................ 136

DataLoss 20040...................................................................................................................... 136InputStreams 20160................................................................................................................ 136PacketLoss 20080...................................................................................................................138SEBs 20210............................................................................................................................ 139StorageFull 20190................................................................................................................... 140StorageTime 20130.................................................................................................................141Temperature 20140.................................................................................................................142

Appendix G: Video Streaming and Exporting Performance............................. 144

Glossary..............................................................................................................A.............................................................................................................................................. 147B.............................................................................................................................................. 147C.............................................................................................................................................. 147D.............................................................................................................................................. 148E.............................................................................................................................................. 148F...............................................................................................................................................149G.............................................................................................................................................. 149H.............................................................................................................................................. 149I................................................................................................................................................149M..............................................................................................................................................150N.............................................................................................................................................. 150P.............................................................................................................................................. 150R.............................................................................................................................................. 151S.............................................................................................................................................. 151T...............................................................................................................................................152U.............................................................................................................................................. 152V.............................................................................................................................................. 152W............................................................................................................................................. 152

C5617M-G (10 / 2013) 7

Introduction

GETTING STARTED WITH THE PELCO SDK

The Pelco SDK enables third parties to use Pelco products, as well as use non-Pelco products andsoftware. The Pelco SDK uses methods in the Pelco API.

The following diagram shows how the SDK interacts with the API.

The API is an open, public interface that helps third party developers to take advantage of the powerof Pelco products. The API is both flexible and powerful, but it can also potentially overwhelm someusers. Of course, developers can directly use the Pelco API. However, Pelco has found that manycustomers enjoy the ease of using the SDK.

NOTE: For more information about the Pelco API, refer to http://pdn.pelco.com/content/introduction-pelco-api.

The Pelco SDK provides 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 metadata parsing• Object model

Pelco SDK Components

The following table shows the major Pelco SDK components.

SDK Component1 Features / Functionality

System Manager Wrapper Device discovery

Service discovery

Viewer Display and control MPEG-4 and H.264 streamsfrom Pelco cameras and DVRs / NVRs / NSMs.

http://pdn.pelco.com/content/introduction-pelco-api

http://pdn.pelco.com/content/introduction-pelco-api

8 C5617M-G (10 / 2013)

SDK Component1 Features / Functionality

Control Pan/Tilt/Zoom on Pelco PTZ-enabledcameras.

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 aparticular web service

Cancel an active event subscription

Event Manager

Easy to use event subscription, that focuses onsubscribing to categories of events instead ofweb service specific events.

NOTE:

Event Manager requires an Endura SystemManager.

Metadata Parser Parses Pelco Video Elementary Stream (VES)metadata: Timestamp, Motion Detection, VideoAnalytics Primitives

Render primitives and other data to video frame

Exporter Export video streams into a variety of popularvideo formats: AVI, MP4, 3GP, or PEF

Overlay data on exported video

Object Model The object model uses objects to communicatewith networked video management systemsand devices. The object model operates inconjunction with device caching, which discoversnetworked devices and stores the device liston the local computer on which the software isrunning.

The Pelco SDK contains sample projects, as shown in the following table.

Code Sample Default Location3

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

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

C5617M-G (10 / 2013) 9

Code Sample Default Location3

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

Get Devices Sample C:\Program Files\Pelco\API\CPP\GetDevices

C:\Program Files\Pelco\API\DotNet\GetDevices

View Video Sample C:\Program Files\Pelco\API\DotNet\ViewVideo

The sample projects described in this document assume that the default target installation directorywas chosen during installation.

INSTALLING THE PELCO SDKTo install the Pelco SDK, perform the following steps:

1. Uninstall any SDK version 1.x, 2.x or 3.x prior to installing Pelco SDK 3.1.

NOTE: If versions prior to Pelco SDK 3.1 are left installed, they might affect the usability. Somesamples might not build out-of-the-box or might not run at all. A clean install is recommended. Ifthe problem continues, PATH and other env vars should be corrected. Try the following:

• Uninstall other Pelco software such as Workstation, Endura Utilities, or Digital Sentry• Delete \Program Files\Pelco\• Remove all Pelco-related env vars

2. Download the Pelco SDK from the Pelco Developer Network (PDN) at http://pdn.pelco.com. ThePelco SDK is in the Pelco SDK Related Downloads subsection inside the Downloads section. ThePelco SDK has two separate downloads: One for Visual Studio 2010 (download Pelco SDK vc10),and one for Visual Studio 2008 (download Pelco SDK vc9). Select the appropriate download foryour version of Visual Studio.

3. After downloading the Pelco SDK, double-click the Pelco SDK installer executable. Follow theprompts on the screen to perform the installation.

4. After installation, restart the system. This ensures that the environment variables are correctly set.

Assuming the default installation path was chosen, the folders shown in the following table arecreated.

http://pdn.pelco.com

10 C5617M-G (10 / 2013)

File Folder Path Description

C:\Program Files\Pelco\API\Include\C++\PelcoAPI 4

Header files for all of the Pelco SDK relatedclasses can be found here.

C:\Program Files\Pelco\API\Include\C++\PelcoSDK 4

Header files for all of the Object Model relatedclasses can be found here.

C:\Program Files\Pelco\API\Libs\Release 4

Pelco SDK release module libraries can be foundwithin the Release directory.

C:\Program Files\Pelco\API\Libs\Debug 4

Pelco SDK debug module libraries can be foundwithin the Debug directory.

C:\Program Files\Pelco\API\Libs\Release\Plugins 4

Pelco SDK release plugins can be found withinthe Plugins directory.

C:\Program Files\Pelco\API\SampleCode 4

Contains all the sample projects related to PelcoSDK components.

C:\Program Files\Pelco\API\Logging 4 Contains an application calledLoggingSetup.exe which allows you to write alog file for debugging purposes. You can manageother logging related information by runningLoggingSetup.exe.

C:\Program Files\Pelco\API\Documentation 4

Contains documentation for Pelco SDKcomponents.

GENERAL REQUIREMENTS

Hardware Requirements

The minimum hardware requirements for the client machine are as follows:

• CPU: Intel 2.4 GHz Core 2 Duo (or higher)• Memory: 2GB• GPU: DirectX® 9-compatible; must be a dedicated graphics card with at least 128 MB of memory,

and use an AGP bus or a PCI Express bus• Hard disk: 1GB 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 ofcompatible Pelco hardware can be found in the appendix.

Software Requirements

The software requirements for the client machine are as follows:

• ONE of the following operating systems:

• Microsoft® Windows Server® 2003 32-bit• Microsoft Windows Server 2003 64-bit• Microsoft Windows Server 2008 32-bit• Microsoft Windows Server 2008 64-bit• Microsoft Windows Server 2012 64-bit

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

C5617M-G (10 / 2013) 11

• Microsoft Windows® XP 32-bit• Microsoft Windows XP 64-bit• Microsoft Windows Vista® 32-bit• Microsoft Windows Vista 64-bit• Microsoft Windows 7 32-bit• Microsoft Windows 7 64-bit• Microsoft Windows 8 32-bit• Microsoft Windows 8 64-bit

NOTE: Pelco does not support using the SDK in 64-bit mode applications. Applications must be builtusing 32-bit mode, and will still run on 64-bit operating systems.

• The latest version of DirectX 9.0c must be installed even if DirectX 10 or 11 is already installed aspart of Windows Vista or higher (refer to http://www.microsoft.com/en-us/download/details.aspx?id=8109)

• ONE of the following combinations of Visual Studio® and Microsoft.NET Framework:

• Visual Studio 2008 and Microsoft.NET Framework 3.5• Visual Studio 2010 and Microsoft.NET Framework 4.0

NOTE: Improper use of audio/visual recording equipment could subject you to civil and criminalpenalties. Applicable laws regarding the use of such capabilities vary between jurisdictions and canrequire, among other things, express written consent from the recorded subjects. You are solelyresponsible for insuring strict compliance with such laws and for strict adherence to any/all rights ofprivacy and personalty.

SYSTEM ENVIRONMENT SETTINGS FOR THE PELCO SDK

The Pelco SDK installer adds the following environment variables to the client machine:

EVEREST_BIN Location of the Pelco SDK binaries. By default, this is set to C:\ProgramFiles\Pelco\API\Libs.

EVEREST_ROOT Location of the Pelco SDK 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\Debugfolder.

NOTE: To build Pelco SDK applications in release mode, you must change the PATH variable topoint to the Release directory (for example, C:\Program Files\Pelco\API\Libs\Release).If any of the paths have been changed from the defaults, you must remove the path when the PelcoSDK is uninstalled.

INCLUDING REQUIRED SDK COMPONENTS FOR YOUR APPLICATION

When distributing your Pelco SDK application, you must ensure that the required Pelco SDKcomponent re-distributables are installed on the target client machine. As is typical with other vendorre-distributables, a user interface is not be presented to the user. The re-distributable itself can becalled directly by any custom installer you write for your applications.

Once the re-distributable installation is finished, your custom installer can verify the status of theinstallation and determine whether a restart of the client machine is required.

The client machines must have DirectX 9.0c installed, plus Visual C++ 2008 Runtime and .NETFramework 3.5, or Visual C++ 2010 Runtime and .NET Framework 4.0, depending on yourrequirements.

As with the complete Pelco SDK, download individual Pelco SDK components and Pelco SDK re-distributables from the Pelco Developer Network (PDN) at http://pdn.pelco.com. Once finished

http://www.microsoft.com/en-us/download/details.aspx?id=8109

http://www.microsoft.com/en-us/download/details.aspx?id=8109


12 C5617M-G (10 / 2013)

downloading, double-click the Pelco SDK installer to begin installation. Follow the on-screen promptsto complete the installation.

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

SETTING UP SAMPLE PROJECTS

This section describes how to set up the sample Pelco SDK projects.

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 isNOT intended for immediate production use.

The sample projects are located in the following default folder:

• On 32-bit computers: C:\Program Files\Pelco\API\SampleCode• On 64-bit computers: C:\Program Files (x86)\Pelco\API\SampleCode

NOTE:

On 64-bit computers, set Platform target to x86 before building the project as shown below.

REGISTERING THE ACTIVEX CONTROL

By default, on 32-bit systems the installer registers the Active X Component (OCX) in the C:\Program Files\Pelco\API\Libs\Debug directory. On 64-bit systems, the directory is C:\Program Files (x86)\Pelco\API\Libs\Debug. To ensure that the OCX registration issuccessful, 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, openthe command line and navigate to the Pelco SDK library release directory, which on 32-bit systems isby default: C:\Program Files\Pelco\API\Libs\Release. On 64-bit systems, the directory isC:\Program Files (x86)\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 registerthe PelcoAPICOMViewer.ocx file: Regsvr32 PelcoAPICOMViewer.ocx

ADDING REFERENCES TO MANAGED LIBRARIES FOR C#

After you have registered the Pelco API COM Viewer ActiveX control, open the sample project youwant to build in Visual Studio (for example, open the Pelco API Viewer Sample C# project).

The next step is to add the references to the Pelco managed library DLLs to the project.

Within Visual Studio’s Solution Explorer window, expand the References section.

Make a note of which of the following Pelco library references are present:

• ManagedEnduraExport(9)• ManagedEventArbiter• ManagedEventManager• ManagedPelcoAPICommon• ManagedPTZControlWrapperNet• ManagedSystemManagerWrapper• Pelco.SDK


C5617M-G (10 / 2013) 13

• PelcoAPIMPFViewer

You will need the list of references shortly. Each Pelco reference might have a yellow exclamationmark (!) next to it. For the Pelco API Viewer Sample C# project, the references needed areManagedPelcoAPICommon and PelcoAPIMPFViewer.

Delete the existing Pelco references by right-clicking each Pelco reference and selecting Remove.For the Pelco API Viewer Sample C# project, remove the references to ManagedPelcoAPICommonand PelcoAPIMPFViewer.

From the File menu, select Save All.

From the Build menu, select Clean Solution.

Right-click References and select Add Reference.

Click the Browse tab. Navigate to the correct Pelco library folder. Assuming you used the defaultinstallation path, the folder containing the debug libraries on 32-bit computers is C:\Program Files\Pelco\API\Libs\Debug. On 64-bit computers, the folder is C:\Program Files (x86)\Pelco\API\Libs\Debug.

NOTE: If you are building an application for release, then you use the release libraries in the Pelco\API\Libs\Release folder.

14 C5617M-G (10 / 2013)

Find the project library files that you made a note of earlier, and control-click each of the files. Forexample, the Pelco API Viewer Sample C# project requires the ManagedPelcoAPICommon.dll andPelcoAPIMPFViewer.dll files. Click OK to add the files.

On a 64-bit computer, set Platform target to x86.

C5617M-G (10 / 2013) 15

NOTE: Pelco does not support using the SDK in 64-bit mode applications. Applications must be builtin 32-bit mode, and will still run on 64-bit operating systems.

You can now build and then run the sample project.

NOTE: For projects that require the PelcoAPICOMViewer.ocx control, you might need to cleanand rebuild the project several times before the OCX control will work. This is a Visual Studio / OCXlimitation.

NOTE: For C++ projects, be sure to set the character set to Use Multi-Byte Character Set underthe project properties. Click the project, then select Properties > Configuration Properties >General. You will then see Character Set. Set it to Use Multi-Byte Character Set.

16 C5617M-G (10 / 2013)

Device Caching Using Object Model

OVERVIEW

Pelco SDK 3.0 introduced an object model, which simplifies development of applications that use theSDK. Future versions of the SDK will gradually phase out previous SDK components and replacethem with objects. The object model features the following:

• Uses objects to communicate with networked video management systems and devices• Consists of a group of classes for representing systems, devices connected to those systems,

device properties, and other items

Component Libraries

The following component libraries contain the functionality for the object model:

• PelcoSDK.dll, which is used for C++• Pelco.SDK.dll, which is used for any .Net language

Public Classes

The following table shows the public classes used in the object model.

Table 1: Object Model Public Classes

Class Description

System A system for storing video

SystemCollection A collection of systems

Device A device connected to a system

DeviceCollection A collection of devices

Property A device property

PropertyCollection A collection of properties

Camera A camera for recording a stream

Display A window on a display device within which astream can be viewed

NetworkDisplay A display device located on a network withinwhich camera output can be viewed

Channel One of several smaller areas on a display

Channel Collection All channels on a particular network display

Stream An audio visual stream

Event An unmanaged event

Events A collection of unmanaged events

Exception An exception

INITIALIZING A PELCO SDK APPLICATION

This section describes how to initialize applications that use the Pelco SDK.

You must initialize Pelco software prior to using it. When you are done using the software, you mustshut it down.

C5617M-G (10 / 2013) 17

The functions for starting up and shutting down an SDK application are as follows:

C#/.Net

Pelco.SDK.Application.Startup();Pelco.SDK.Application.Shutdown();

C++

PelcoSDK::Startup();PelcoSDK::Shutdown();

You must call the Startup function prior to any other calls to the API, and the Shutdown functionfollowing the last call to the API.

Additionally, the Pelco SDK uses the Microsoft Component Object Model (COM) library. If you arecreating a Pelco SDK application without using a framework such as MFC, ATL, or .Net, you mustmanually initialize each thread to use the COM library prior to calling any Pelco functions.

Threads that use COM or Pelco SDK functions must call CoInitializeEx() usingCOINIT_MULTITHREADED. Call CoUnitialize() on completion of the thread to properly shutdown COM.

NOTE: You must call CoInitializeEx() prior to using Startup(), and CoUnitialize() afterShutdown().

NOTE: While you might need to call CoInitializeEx() and CoUnitialize() for each thread,you only need to call Startup() and Shutdown() once per process. You must also always callStartup() and Shutdown() for every application.

NOTE: CoinitializeEx() and CoUnitialize() are only required if you are not using aframework such as MFC. Startup() and Shutdown() are required for all Pelco SDK applications.

A C++ example of starting and shutting down the API, along with initializing and unitializing COM, isshown below:

int main(){ // Initialize COM, if required. // Always use COINIT_MULTITHREADED for the Pelco SDK HRESULT hr = ::CoInitializeEx(NULL, COINIT_MULTITHREADED); if (SUCCEEDED(hr)) { // Startup the PelcoSDK PelcoSDK::Startup();

// Call Pelco SDK or COM functions here

...

// Shutdown the PelcoSDK PelcoSDK::Shutdown();

// Balance CoInitializeEx call with CoUninitialize ::CoUninitialize(); } return 0;}

18 C5617M-G (10 / 2013)

The following example shows how to initialize the SDK from a C#/.Net application:

namespace ViewVideo{ static class Program { [STAThread] static void Main() { try { Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); Pelco.SDK.Application.Startup(); Application.Run(new LoginForm()); } catch(Exception ex) { MessageBox.Show(ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error); } finally { Pelco.SDK.Application.Shutdown(); } } }}

You can also embed these calls in a class that automatically shuts down COM and the API, as shownin the example below:

// Example CoInitializeEx class.class _CoInit{public: _CoInit() : _hr(NOERROR) { // Initialize COM, if required. // Always use COINIT_MULTITHREADED for the Pelco SDK _hr = ::CoInitializeEx(NULL, COINIT_MULTITHREADED); if (SUCCEEDED(_hr)) { // Call PelcoSDK Startup() try { PelcoSDK::Startup(); } catch (PelcoSDK::Exception& /*ex*/) { // Cannot continue ::CoUninitialize(); _hr = E_FAIL; } } }

// Destructor for the class calls CoUnitialize virtual ~_CoInit() { if (SUCCEEDED(_hr)) { // Call PelcoSDK Shutdown()

C5617M-G (10 / 2013) 19

try { PelcoSDK::Shutdown(); } catch (PelcoSDK::Exception&) { /* Add any logging software here */ } // Unitialize COM, if required. ::CoUninitialize(); } _hr = E_FAIL; }private: HRESULT _hr;};

// To have your software operate with the Pelco SDK, create an // instance of _CoInit in main() (and in any other threads // using the SDK) prior to making any SDK calls.void main(){ _CoInit init;

// Call Pelco SDK or other COM functions here.

... }

For more information on CoInitiaizeEx() and CoUnitialize(), refer to the MicrosoftDeveloper Network (MSDN).

DEVICE CACHING

The Device Cache is a feature of the Pelco SDK, where a cache of Device Objects is created fordevices that are connected to the system running the Pelco SDK. The caching of device informationresults in faster response times and reduced network traffic.

The device information is stored in a database on the local computer. The first attempt to connectto a new Pelco system retrieves all of the device information and device parameters, and storesthe information in the database. Future attempts to retrieve the same information is obtained fromthe database. A continuously running background task ensures the device information is the latestversion. The minimum device cache database refresh interval is five minutes.

The directory where the device cache database is stored depends on the operating system used, asdescribed in the following table.

Table 2: Database Location

Operating System Directory

• Windows XP• Windows Server 2003• Windows Server 2008

C:\Documents and Settings\All Users\Application Data\Pelco\SDK

• Windows Vista• Windows 7• Windows 8• Windows Server 2012

C:\ProgramData\Pelco\SDK

http://msdn.microsoft.com

http://msdn.microsoft.com

20 C5617M-G (10 / 2013)

SAMPLES

Complete C# and C++ sample programs are supplied with the Pelco SDK.

• On 32-bit computers, the samples are in the directory C:\Program Files\Pelco\API\SampleCode

• On 64-bit computers, the samples are in the directory C:\Program Files (x86)\Pelco\API\SampleCode

The samples are contained in the subdirectories specified in the following table.

Table 3: Sample Locations

Directory Description

SampleCode\CPP\GetDevices C++ sample that shows how to retrieve the list ofconnected devices.

SampleCode\DotNet\GetDevices C# sample that shows how to retrieve the list ofconnected devices.

When running the samples, the default user name is admin. The default password is also admin.

Display the List of Connected Devices

The following sample shows how to display the list of connected devices:

int _tmain(int argc, _TCHAR* argv[]){ try { // Create a system object PelcoSDK::System system("admin:admin@pelcosystem://10.220.196.187:60001?alias=Sample"); // Create a device collection object and populate it with the devices from the system object PelcoSDK::DeviceCollection deviceCollection(system.GetDeviceCollection()); // Loop over the device collection object and display each device name printf("\n\n> DEVICES =================================\n"); for (deviceCollection.Reset(); deviceCollection.MoveNext(); ) { // Retrieve the current device object PelcoSDK::Device device(deviceCollection.Current()); // Display the device name printf("\tDevice Name: %s\n", device.GetModelName()); } // Display the number of devices printf("=========================================\n"); printf("Total Devices: %d", deviceCollection.GetCount()); } catch (PelcoSDK::Exception ex) { printf("An error occurred\nError: %s", ex.Message().c_str()); } return 0;}

C5617M-G (10 / 2013) 21

The following sections describe the sample details.

Connecting to a System

The following line connects to the system:

PelcoSDK::System system("admin:admin@pelcosystem://10.220.196.187:60001?alias=Sample");

The string passed to the constructor is a URL scheme. The scheme consists of four parts, which aredescribed in the following table.

Table 4: URL Scheme Components

Component Description Example

Credentials User name and password. Ifthe user name and passwordare not provided, the systemobject is read-only, which willprevent retrieval of a devicecollection and access to adevice object through theGetDevice() method. Basicproperties such as the displayname, IP address, port, alias,and system refresh time can stillbe retrieved. Any attempt to callGetDeviceCollection(),GetDevice(),SetRefreshTime(),SetAlias(), or Remove()will throw an exceptionwith an error code ofPelcoSDK::NotAuthenticated.

admin:admin

System Provider System provider identifier. Foran Endura system, the identifieris "pelcosystem".

pelcosystem

System Address IP address and port of thesystem to access. In thesample, a "direct discovery"operation is performed, whereboth the IP address and port arespecified. An "autodiscovery"operation can be performedby omitting the IP addressand port. Pelco SDK 3.1 onlysupports autodiscovery ofEndura systems.

10.220.196.187:60001

Parameter Optional parameter. Pelco SDK3.1 only supports the aliasparameter. This parameterallows the developer to assigna key to the system, whichenables easy retrieval at afuture point. The alias can be

alias=Sample

22 C5617M-G (10 / 2013)

Component Description Example

set to any unique value for aparticular system.

A system object can be created without first retrieving a system collection object. This provides aconvenient way to add or get a system object.

When the system object is created, a new entry in the Pelco device cache is created. The cachecontains details for the objects contained within the cache. There is a slight delay while the cacheentry is populated. The next time the application containing the system object creation statementis started, the SDK will retrieve the system information from the cache and make the informationimmediately available.

Retrieving a Device Collection

The following line creates a device collection object and populates the object with the retrieveddevices:

PelcoSDK::DeviceCollection deviceCollection(system.GetDeviceCollection());

The GetDeviceCollection() method of the system object returns the collection of devicesretrieved from the system object.

Displaying Device Information

The following sample uses a loop to access the devices in the device collection object, and displayseach device name:

// Loop over the device collection object and display each device name printf("\n\n> DEVICES =================================\n");for (deviceCollection.Reset(); deviceCollection.MoveNext(); ){ // Retrieve the current device object PelcoSDK::Device device(deviceCollection.Current()); // Display the device name printf("\tDevice Name: %s\n", device.GetModelName());}

In the sample, deviceCollection.Current() returns an object of type PelcoSDK::Device().The sample then displays the name of the device using device.GetModelName().

As can be seen in the sample, the SDK contains methods for iterating over collection objects. Atypical use of the iteration methods is to display a list of systems and devices.

The iteration methods are shown in the following table.

Table 5: Iteration Methods

Method Description

Reset() Moves back to the start of the collection.

MoveNext() Moves to the next item in the collection. Thismethod must be called before Current().Returns true or false (true means the end of theitems has not been reached, false means theend has been reached).

Current() Retrieves the current item in the collection.

C5617M-G (10 / 2013) 23

The SDK also contains methods for directly accessing a collection. The methods are shown in thefollowing table.

Table 6: Methods

Method Description

GetItem(index) Retrieves the item at the specified index.

GetItemByKey(key) Retrieves the item with the specified key. For adevice, the key is the device UUID. For a system,the preferred key is the system alias.

NOTE: Another SDK method is GetVersion(), which returns the device version. The deviceis accessed directly to retrieve the version, and the retrieved value is not cached. Avoid callingGetVersion() in a loop because of the delay while a response is sent from the device.

24 C5617M-G (10 / 2013)

Integrating Pelco Edge Systems and Devices Using Object Model

OVERVIEW

Pelco Edge Devices are

• A device on a network where no System Manager is present• Sarix 1.8.2 (or later) cameras that use camera-level authentication• Devices on an Endura network that bypass the System Manager

Pelco Edge Systems are containers for Pelco Edge Devices and support the ability to create distinctcollections of Pelco devices without requiring a Pelco System Manager. This section describes how touse Pelco Edge Systems and Devices with the Pelco SDK object model.

ADDING A PELCO EDGE SYSTEM TO A SYSTEM COLLECTION

Adding a Pelco Edge system to a SystemCollection works the same way as creating a PelcoSystemsystem. You must gather the proper information for the Edge system and call the appropriate methodto add it.

1. Use the Pelco Edge Device URL. This indicates which internal provider to use for systemmanagement and caching. The format is

pelcoedgedevices://

2. Determine aliases. This allows the user to create 1…n distinct Pelco Edge Devices systems. Theformat is

?alias=Name

3. Use a System construction method to construct the edge system. You can use one of twoequivalent methods:

• System system(“pelcoedgedevices://?alias=Mine”);• System system = SystemCollection.Add( “pelcoedgedevices://?

alias=Mine”);

REMOVING A PELCO EDGE SYSTEM FROM A SYSTEM COLLECTION

You can remove a Pelco Edge System from a System Collection using the System.Remove() method.

1. Retrieve the system you want to remove. In this example, remove the first system in theSystemCollection.

System sys = systemCollection.GetItem(0);

2. Remove the system:

sys.Remove();

NOTE: Removal of a System Object through the System.Remove() method will not remove theobject immediately. The object is removed after all references to the System Object have beenreleased.

ADDING A PELCO EDGE DEVICE TO A DEVICE COLLECTION

Use the DeviceCollection Add method to add Pelco Edge devices. Pelco Edge Devices are userdirected discovery only, which is functionally opposite of Pelco System based discovery.

1. Determine the IP address and, optionally, the port. The format is

pelcoedgedevices://IPAddress:Port

2. Provide an optional user name and password for those devices that require authentication. Theformat is

username:password

C5617M-G (10 / 2013) 25

Once the data for the devices are determined, you can call the appropriate System functionand DeviceCollection Add functions to add the device to the device collection, as shown in thefollowing example.

System system(“pelcoedgedevices://?alias=Mine”); DeviceCollection dc = system.DeviceCollection; DeviceCollection devicesAdded = dc.Add(“admin:admin@pelcoedgedevices://12.34.56.99”);

NOTE: If the device you are trying to add already exists in the collection, the Pelco SDK throwsa "Device already exists" exception. If the SDK cannot contact the device you specify, the SDKthrows "Device not found". If the SDK is able to find the device but it is not supported, the SDKthrows "Device unrecognized".

NOTE: Multiple logical devices can exist at the same IP address and port. For example,a multichannel encoder can have multiple cameras at the same IP address and port. TheDeviceCollection Add method can add all of them. Once you have added one or more devices,you iterate through the returned DeviceCollection to find the specific device you want. Thesedevices are in the system's DeviceCollection, in memory and on disk.

NOTE: Pelco Edge Devices have some limitations compared to PelcoSystem devices. With PelcoEdge Devices, you cannot stream video from a camera to a NetworkDisplay; you can only streamvideo to a local Display attached to a local PC. Additinally, Pelco Edge Devices can only streamlive video, and not playback.

NOTE: The Pelco SDK only supports Sarix cameras as edge devices, not including IL 10cameras.

REMOVING A PELCO EDGE DEVICE FROM A DEVICE COLLECTION

The devices within a device collection can be removed using the Remove() method. The Remove()method takes a Device object as a parameter.

1. Retrieve the device collection with the device you want to remove. Loop through the devices withina device collection to find the device in question.

// Iterate through the device collectionfor (deviceCollection.Reset(); deviceCollection.MoveNext(); ) {

2. Retrieve the current device within the device collection.

// Retrieve a device from the device collectionPelcoSDK::Device device(deviceCollection.Current());

3. Determine if this is the device to remove. In this example, the Device method GetModelName()determines which device to remove. Consult the Object Model Reference Manual for othermethods available for a device. For this example, delete any camera with the model name"DeleteMe".

// Check if this device has the appropriate characteristic for deletionif (device.GetModelName() == "DeleteMe")

4. Use the DeviceCollection Remove() method to remove the device.

// Remove the device.

26 C5617M-G (10 / 2013)

deviceCollection.Remove(device);}

Piecing the above software sections together produces the following:

// Iterate through the device collectionfor (deviceCollection.Reset(); deviceCollection.MoveNext(); ) {

// Retrieve a device from the device collection PelcoSDK::Device device(deviceCollection.Current());

// Check if this device has the appropriate characteristic for deletion if (device.GetModelName() == "DeleteMe")

// Remove the device. deviceCollection.Remove(device);}

NOTE: The Remove() method will also remove any devices associated with the removed device.

C5617M-G (10 / 2013) 27

Network Displays Using Object Model

OVERVIEW

A Network Display is a device on a network that can display video. A "Network Display" is differentfrom a "Display" in that the Network Display does not have to be a local device, but can be locatedanywhere on a network.

On Endura Systems, Network Displays are Monitors. The SDK uses the term Network Display to referto an Endura Monitor device.

USING A NETWORK DISPLAY

To use a Network Display, you initialize a Camera Object and bind it to a Channel Object on theNetwork Display.

Using the object model, it takes a combination of these objects to start the flow of video to theNetwork Display. The process is as follows

1. Find the Camera Object that needs to be displayed.

// Get a Camera Object from the DeviceCollection by its UUIDPelcoSDK::Camera cam = deviceColl.GetItemByKey(camUUID);

2. Create a Network Display Object to view the Camera.

A Network Display Object represents a device on a network which can contain channels that candisplay video data.

// Create a Network Display ObjectPelcoSDK::NetworkDisplay* pNetworkDisplay = NULL;// Retrieve the device collection.PelcoSDK::DeviceCollection deviceCollection = system->GetDeviceCollection();deviceCollection.Reset();// Retrieve the first network display foundwhile (deviceCollection.MoveNext()){ try { PelcoSDK::Device device(deviceCollection.Current());// Check if there is a network display. If not, create one. if (NETWORK_DISPLAY == device.GetDeviceType()) { pNetworkDisplay = new PelcoSDK::NetworkDisplay(device); break; } } catch (PelcoSDK::Exception x1) { REPORT_FAIL("NetworkDisplaySample failed to get Device\n"); }}

3. Retrieve a channel from the Network Display's channel collection. Bind the camera to the channelto view it. With the Camera, Network Display, and Channel Objects created, all the pieces required

28 C5617M-G (10 / 2013)

to display the Camera on a Network Display are present. The following example shows how toretrieve a channel and bind a camera to it.

// Check if there is a Network Display from step 2if (pNetworkDisplay){ try { PelcoSDK::ChannelCollection channelCollection = pNetworkDisplay->GetChannelCollection();// Get the first Channel. PelcoSDK::Channel channel = channelCollection.GetItem(0); // Display the camera. channel.Show(cam); } catch (PelcoSDK::Exception x1) { REPORT_FAIL("NetworkDisplaySample failed to get ChannelCollection or Channel\n"); }// Delete the Network Display object when it is no longer needed. delete pNetworkDisplay; pNetworkDisplay = NULL; }}

Network Display Object A Network Display Object is a window on a device on a network.

Channel A Channel is a portion of a Network Display object on whichvideo from a Camera Object can be displayed.

Camera Object A Camera Object represents an individual camera device. It isderived from the Device class.

NOTE: It is possible to get and set a camera number for the camera. It is important to note that aPelco system allows multiple cameras to have the same camera number. Therefore, a camera'snumber might not be unique.

C5617M-G (10 / 2013) 29

Displaying and Controlling Streams Using Object Model

OVERVIEW

A security operator must be able to view images that the system IP cameras are capturing. This isthe most important thing in any security imaging system. Therefore, displaying a video stream andcontrolling its playback are the first things to be made operational.

The Pelco SDK includes support for streaming of live and recorded video using the Object Modeldescribed in the section Object Model. Among the objects that the SDK supports are Display,Camera, and Stream. These objects display video streams from cameras to the local video displayand hide the complexity seen in the PelcoAPIViewer. Live and playback streams are treated as asingle entity, and the operator does not have to manage separate live and playback video streaminstances, but only needs to manage a single instance of a Stream Object.

There are three different streaming/system combinations available. They are described in the tablebelow:

System Supported Stream Type

SM5000, DX4700/DX4800HD, Digital Sentry PelcoAPI streams only. PelcoAPI streamssupport only MPEG-4 and H.264 type streams.

SM5200 PelcoAPI and MJPEG streams. For PelcoAPItype systems, the SDK defaults to PelcoAPIstreams as well as PelcoAPI Device collection.`Streaming type for this system is configurable.

Pelco Aggregation MJPEG streams only. This feature supports theability to aggregate multiple systems internally,presenting them as a unified system.

SAMPLES

Complete C# and C++ sample programs are supplied with the Pelco SDK.

• On 32-bit computers, the samples are in the directory C:\Program Files\Pelco\API\SampleCode

• On 64-bit computers, the samples are in the directory C:\Program Files (x86)\Pelco\API\SampleCode

The samples are contained in the subdirectories specified in the following table.

Table 7: Sample Location

Directory Description

SampleCode\DotNet\ViewVideo C# sample that shows how to display and controlvideo streams.

INITIALIZING A STREAM OBJECT

Initializing a Stream Object requires getting a Camera Object from the Device Collection. A newStream Object is constructed after a Camera Object is acquired. The Stream Object is able toinitialize itself using the given Camera Object.

Using the object model, it takes a combination of objects to start the flow of video to the display. Theprocess is as follows:

30 C5617M-G (10 / 2013)

1. Find the Camera Object that needs to be displayed.

// Get a Camera Object from the DeviceCollection by its UUIDPelco.SDK.Camera cam = deviceColl.GetItemByKey(camUUID);

2. Create a Stream Object after a Camera is acquired.

// Create a Stream instance from a camera Pelco.SDK.Stream stream = new Pelco.SDK.Stream(cam);

3. Create a Display Object to view the Stream.

A Display Object represents an area of application. The SDK uses a Windows HWND as thedisplay area.

// Create a Display Object using the Handle to a predefined "videoPanel."Pelco.SDK.Display disp = new Pelco.SDK.Display((IntPtr)videoPanel.Handle);

4. Bind the Stream to the Display Object so it can be viewed.

With the Camera, Stream and Display Objects created, all the pieces required to display theStream are present. Class member variables must be declared for _stream and _display toproceed with creating a stream instance and display the stream. The following example program:

• Creates a new Stream Object• Creates a new Display Object that binds the videoPanel's Handle to the display• Calls Play on the Stream (kFWD_1X in the call means to play live forward at standard speed)• Displays video on the user interface

private void CreateStreamAndPlay(Camera camera){ try { //Create a Stream instance from a Camera _stream = new Pelco.SDK.Stream(camera); // Create a new Display Object _display = new Pelco.SDK.Display((IntPtr)videoPanel.Handle); //Configure _display to Show _stream _display.Show(_stream); // Start playing the stream forward at 1X _stream.Play(Pelco.SDK.kFWD_1X); } catch (Pelco.SDK.Exception ex) { System.Diagnostics.Debug.WriteLine(ex.Message); }}

Display Object A Display Object is a window on a local monitor used to view thestreams; the Display Object is created using a WIN32 HWND.

Camera Object A Camera Object represents an individual camera device. It isderived from the Device class. The CreateStream method isused for getting the Stream Object for a particular camera.

NOTE: It is possible to get and set a camera number for the camera. It is important to note that aPelco system allows multiple cameras to have the same camera number. Therefore, a camera'snumber might not be unique.

C5617M-G (10 / 2013) 31

WORKING WITH STREAM CONFIGURATIONS

Use the StreamConfiguration Object to change how a Stream Object behaves. You can requestStreamConfiguration information from a Stream Object, or create a new StreamConfiguration Object,or modify an existing one.

The following table describes the StreamConfiguration Object's fields:

Table 8: Forward stream speed constants

Field Possible Values Notes

StreamProtocol C++ constants:

• kSTREAM_PROTOCOL_AUTO• kSTREAM_PROTOCOL_RTP• kSTREAM_PROTOCOL_RTSP• kSTREAM_PROTOCOL_HTTP

.Net constants:

• StreamProtocolAuto• StreamProcotolRtp• StreamProtocolRtsp• StreamProtocolHttp

The C++ default iskSTREAM_PROTOCOL_RTP. The .Netdefault is StreamProtocolRTP.

When asking the Stream for itsStreamConfiguration, this value will varydepending on the value of VideoFormat:

1. kSTREAM_FORMAT_MPEG4_H264will result in a value ofkSTREAM_PROTOCOL_RTP.

2. kSTREAM_FORMAT_MJPEG will result ina value of kSTREAM_PROTOCOL_HTTP.

DeliveryMode C++ constants:

• kDELIVER_AUTO• kDELIVER_UNICAST• kDELIVER_MULTICAST

.Net constants:

• DeliverAuto• DeliverUnicast• DeliverMulticast

The C++ default is kDELIVER_AUTO.The .Net default is DeliverAuto.

When asking the Stream for itsStreamConfiguration, this value usually isk_DELIVER_MULTICAST.

Setting this value to k_DELIVER_AUTOallows the system to pick the mostappropriate delivery mode.

This value is of use to streamswith a StreamProtocol value ofkSTREAM_PROTOCOL_RTP orkSTREAM_PROTOCOL_RTSP. It is ignoredfor k_STREAM_PROTOCOL_HTTP.

StreamAudio True to include audio (if available),False to not include audio.

Default is true. Not all streams includeaudio.

VideoFormat C++ constants:

• kSTREAM_FORMAT_AUTO• kSTREAM_FORMAT_MJPEG• kSTREAM_FORMAT_MPEG4_H264

.Net constants:

• StreamFormatAuto• StreamFormatMJPEG• StreamFormatMPEG4h264

The C++ default iskSTREAM_FORMAT_AUTO, and the .Netdefault is StreamFormatAuto.

Different systems support different videoformats:

1. SM5000,DX4700/DX4800HD, andDigital Sentry systems only support kSTREAM_FORMAT_MPEG4_H264.

2. SM5200 systems support bothkSTREAM_FORMAT_MPEG4_H264and kSTREAM_FORMAT_MJPEG.kSTREAM_FORMAT_MPEG4_H264

32 C5617M-G (10 / 2013)

Field Possible Values Notes

is the default value. VideoFormat isconfigurable.

3. Pelco Aggregations systems onlysupport kSTREAM_FORMAT_MJPEG.

When you set VideoFormat tokSTREAM_FORMAT_AUTO, the systempicks the type of format it prefers, withkSTREAM_FORMAT_MPEG4_H264 being thedefault.

FrameRate Video frame delivery rate. The default is kDEFAULT_FRAME_RATE(1.0f)

The FrameRate can be a value between1.0f and 30.0f. SM5000, DX4700/4800HD,Digital Sentry and SM5200 ignore thisvalue if their VideoFormat is set tokSTREAM_FORMAT_MPEG4_H264.

NOTE: When configuring a stream, the following rules are observed:

• VideoFormat takes precedence over any other configuration, followed by FrameRate.• If VideoFormat is MJPEG, the StreamProtocol is HTTP.• If VideoFormat is MPEG4/H264, the StreamProtocol is RTP.• If VideoFormat is MPEG4/H264, the software ignores the FrameRate.• If VideoFormat is MJPEG, the software ignores audio and delivery mode.

CONSTRUCTING A NEW STREAM CONFIGURATION

In this example, the software connects to an SM5200 system. By default, a SM5200 system StreamObject uses StreamFormatMPEG4h264. To display the stream as MJPEG, create a new instanceof StreamConfiguration and change the VideoFormat field. This change causes the object to becomeproperly configured internally for MJPEG automatically.

1. Retrieve a camera, and create a Stream from the camera.

// Retrieve the camera.Pelco.SDK.Camera camera = GetCameraByModel("IX10DN");// Retrieve the display.Pelco.SDK.Display display = new Pelco.SDK.Display((MSSys.IntPtr)videoPanel.Handle);// Retrieve the stream.Pelco.SDK.Stream stream = new Pelco.SDK.Stream(camera);

2. Create a new StreamConfiguration Object and change the configuration to MJPEG.

// Create a new StreamConfiguration object.StreamConfiguration sc = new StreamConfiguration();// Set VideoFormat of the new configuration to be MJPEG.sc.videoFormat = StreamVideoFormat.StreamFormatMJPEG;// Set the camera stream to the new configuration.stream.StreamConfig = sc;

C5617M-G (10 / 2013) 33

3. Bind the stream to the display and play it.

// Use Show to bind the stream. display.Show(stream);// Play the stream.stream.Play(kFWD_1X);

CHANGING A STREAM CONFIGURATION

To change a current Stream's StreamConfiguration, retrieve and change the StreamConfig property.

1. Retrieve a system, look up a camera, and create a Stream from the camera.

// Retrieve a system.System system = new System("admin:admin@pelcosystem://10.11.12.13");// Get a camera through whatever means available.Camera camera = GetCamera(system);// Create the stream from the camera.Stream stream = new Pelco.SDK.Stream(camera);

2. Get the current stream configuration and change it as necessary.

StreamConfiguration streamConfig = stream.StreamConfig;// If the video format is not already MJPEG, set it to be MJPEG in the Stream instance.if (streamVideoFormat.StreamFormatMJPEG != streamConfig.videoFormat){ streamConfig.videoFormat = StreamVideoFormat.StreamFormatMJPEG; stream.StreamConfig = streamConfig;}

3. Use the stream as you would any other Stream object.

// Play the stream stream.Play(1.0f);

NOTE: There are three possible video format types, as shown below:

public enum class StreamVideoFormat{ StreamFormatAuto = 0, // choose default for system StreamFormatMJPEG = 1, // Motion JPEG StreamFormatMPEG4h264 = 2, // MPEG4 or H264, Pelco API based stream.};

PLAYING BACK RECORDED VIDEO

This section describes how a Stream Object is called for playback and how a specific date or time canbe specified for the start date/time of the stream. Recorded video can be played back in the forwarddirection or in reverse by using either a positive or negative speed constant respectively. Refer tothe sections Play a Stream Forward and Play a Stream in Reverse for predefined speed constantdefinitions.

34 C5617M-G (10 / 2013)

1. After initializing a Stream Object, call the Stream Play method to playback recorded video. In thisexample, the playback is requested in reverse direction using a negative speed value. The speedconstant kREV_2X specifies reverse direction at two times standard speed.

// Start playing the stream reverse at 2x standard speed._stream.Play(Pelco.SDK.kREV_2X);

If the camera associated with the stream has an associated recorder (NVR/NSM) with recordedvideo, the stream will start playing in reverse at two times normal speed. If the associated recorderdoes not contain recorded video, there will be no playback stream. This will cause an exception oftype Pelco.SDK.Exception() to occur providing the following error code and message:

• Error code: NoRecordingFound• Error message: "No recording found on NVR or failed to connect"

The error will occur when the Play method is called. Following the error, the next call of the Playmethod will jump the stream to the dateTime that was previously set by Seek(dateTime).

2. Playback of a stream can be jumped to a specific date, or time, by calling the method Seek with aSystem.DateTime. The following example creates a dateTime that is 24-hours in the past and callsSeek on the Stream Object.

// Seek the stream to yesterdayDateTime yesterday = dateTime.UtcNow.AddDays(-1);_stream.Seek(yesterday);

The stream is automatically put into a paused state following the _stream.Seek call.

NOTE: The stream can restart by calling Play with a desired direction and speed, for example,kFWD_1X or kREV_1X for forward or reverse respectively, at standard speed (1X). If the'DateTime yesterday' location does not contain recorded video, there will be no playback stream.This will cause an exception as explained in the previous step.

PLAYING A STREAM FORWARD

A Stream Object can be played forward or in reverse. This section describes how to play it forward.

Use the method Play with a positive value to play a Stream Object forward. Positive value speedconstants contain kFWD indicating forward direction.

// Play the stream forward at 1x (standard speed)_stream.Play(Pelco.SDK.kFWD_1X);

The following example plays the stream forward at 60x the standard speed.

// Play the stream forward at 60x standard speed_stream.Play(Pelco.SDK.kFWD_60X);

There are predefined speed value constants for typical use described in the following table. Theiruse is demonstrated in the above examples.

Table 9: Forward stream speed constants

Speed constant Value Resultant speed (forwarddirection)

kFWD_QUARTER 0.25 0.25x standard speed

kFWD_HALF 0.50 0.50x standard speed

C5617M-G (10 / 2013) 35

Speed constant Value Resultant speed (forwarddirection)

kFWD_1X 1.0 1x standard speed = standardspeed

kFWD_2X 2.0 2x standard speed







PLAYING A STREAM IN REVERSE

A Stream Object can be played forward or in reverse. This section describes how to play it in reverse.

Use the method Play with a negative value to play a Stream Object in reverse. Negative valuespeed constants contain kREV indicating reverse direction.

// Play the stream in reverse at 2x (two times standard speed)_stream.Play(Pelco.SDK.kREV_2X);

The following code plays the stream in reverse at 16x the standard speed.

// Play the stream in reverse at 16x_stream.Play(Pelco.SDK.kREV_16X);

There are predefined speed value constants for typical use described in the following table. Theiruse is demonstrated in the above examples. Note that a negative value results in reverse streamdirection.

Table 10: Reverse stream speed constants

Speed constant Value Resultant speed (reversedirection)

kREV_QUARTER -0.25 0.25x standard speed

kREV_HALF -0.50 0.50x standard speed

kREV_1X -1.0 1x standard speed = standardspeed

kREV_2X -2.0 2x standard speed







36 C5617M-G (10 / 2013)

PAUSING A STREAM

This section describes how to pause a stream.

Use the Pause method to pause a stream.

// Pause the stream_stream.Pause();

NOTE: When a stream is paused, it will switch to playback automatically. CallingPlay(Pelco.SDK.kFWD_1X) will continue playing the playback stream forward at standard speed.If the stream was paused in reverse direction playback, calling Play(Pelco.SDK.kREV_1X) willcontinue playing the playback stream in reverse at standard speed.

RESUMING PLAYBACK OF A PAUSED STREAM

This section describes how to resume playback of a paused stream.

Use the Play method to resume playback of a stream.

// Play the stream forward at 1x standard speed_stream.Play(Pelco.SDK.kFWD_1X); // Play the stream in reverse at 2x standard speed_stream.Play(Pelco.SDK.kREV_2X);

NOTE: Playback of a stream can be in reverse using _stream.Play(Pelco.SDK.kREV_2X) fortwo times standard speed. Speed constants containing kFWD play the stream forward whereasspeed constants containing kREV play the stream in reverse. Refer to the sections Play a StreamForward and Play a Stream in Reverse for forward and reverse speed constant definitions.

SWITCHING FROM PLAYBACK TO LIVE

When a Stream is in playback mode, either by calling Seek to a time in the past or by calling thePause method, the Stream can be returned to live mode by calling the GotoLive method.

Use the GotoLive method to return to live mode.

// Return the stream to live mode_stream.GotoLive();

STEPPING THROUGH A VIDEO STREAM

Step through the video stream one frame at a time by calling the FrameForward or FrameReversemethod.

1. To step forward one frame:

// Step forward one frame_stream.FrameForward();

2. To step back one frame:

// Step back one frame_stream.FrameReverse();

C5617M-G (10 / 2013) 37

TAKING A SNAPSHOT

This section describes how to capture a snapshot of a single frame of video.

Use the Snapshot method to take a snapshot of a single frame of video.

// Create a snapshot of a single frame of video_stream.Snapshot(fileName);

NOTE: The Snapshot method call requires a fully qualified path and file name for saving thesnapshot.

SETTING THE STREAM VOLUME

This section describes how to set the volume of a stream.

Use the SetVolume method to provide a volume level.

// Set the audio volume of a stream; in this case, it is set to 10._stream.SetVolume(10);

NOTE: The valid levels for volume are "0" to "100"; the higher the number, the higher the volume.

Table 11: Stream volume level values

Value Description

0 Mute

1-100 Low volume (1); high volume (100); any level inbetween

GETTING THE STREAM STATE

This section describes how to identify the current state of a stream.

Knowing the current state of a stream before performing an action can be helpful. Use thefollowing call to identify the current stream state.

// Get the state of the streamPelcoSDK::STREAM_STATE GetState()

The stream state value returned can be "0", "1", "2" or "3." These values are defined in thefollowing table.

Table 12: Stream state values

Value Stream state

0 Stopped

1 Forward

2 Reverse

3 Paused

GETTING THE STREAM MODE

Stream Mode returns a value that identifies whether the stream is in live mode or playback mode.

38 C5617M-G (10 / 2013)

Knowing the current mode of a stream before performing an action can be helpful. Use thefollowing call to identify the current stream mode.

// Get the mode of the streamPelcoSDK::STREAM_STATE GetMode()

The stream state value returned can be "0", "1", "2" or "3." These values are defined in thefollowing table.

Table 13: Stream mode values

Value Stream mode

0 Unknown

1 Live; the live stream is active and displayed

2 Playback Seek; all streams (live and playback)are paused, the Seek() method was invokedand when Play() is called, the stream will be inplayback mode

3 Playback; the playback stream is active anddisplayed

C5617M-G (10 / 2013) 39

Displaying and Controlling Streams Using PelcoAPIViewer

OVERVIEW

The most important thing in any security imaging system, is for the security operator to view whatimages the IP cameras are capturing. Consequently displaying a video stream and controlling itsplayback is most likely what you will need to get working first.

This section contains sample C# and C++ that illustrates how to display and control video streams.Complete C# and C++ sample programs are contained in the following subdirectory where the PelcoSDK is installed: C:\Program Files\Pelco\API\SampleCode\PelcoAPIViewerSample

Where Does the Pelco SDK Fit?

To display and control video streams, use the Pelco API Viewer. The Pelco API Viewer is an easy touse Windows based 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 partyapplications. This player can be configured to work in both RTP and RTSP mode. In RTP mode, theplayer 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 supportedby 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 configurationfrom 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, whichresides in the 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

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

The plug-in directory contains components that are key to the SDK’s encoding, decoding, andtranscoding capabilities. Without a proper reference, key features of the Pelco SDK could notfunction properly. Please note that the plug-in directory is dependent on where you installed thePelco SDK.

40 C5617M-G (10 / 2013)

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

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

3. If required, set the authentication credentials to log into the camera.

The following example verifies if authentication is enabled for the camera, and, if so, sets the username to "admin" and the password to "admin_password".

// Set example parameters#define CAMERA_IP_ADDRESS "10.220.196.179"#define PORT_NUMBER 80#define CAMERA_NUMBER 1

// Check if authentication is enabledif (_pViewer.IsAuthenticationEnabled(CAMERA_IP_ADDRESS, CAMERA_PORT, CAMERA_NUMBER)){ // Set the user name to "admin", the password to "admin_password", and use basic authentication PelcoAPI::AuthenticationCredentials authentication("admin", "admin_password", PelcoAPI::AuthenticationCredentials::BASIC); _pViewer.SetAuthenticationCredentials(&authentication);}

NOTE: To manage the camera authentication and the users, use the Pelco Web interface.

4. 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 check box inthe project settings to view 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 tocontrol the video stream programmatically. Both approaches are described below.

USING THE PELCOAPIVIEWER COMPONENT

To use the more programmable PelcoAPIViewer library, complete the following steps.

1. 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);


C5617M-G (10 / 2013) 41


// Set example parametersconst String CAMERA_IP_ADDRESS = "10.220.196.179";const int PORT_NUMBER = 80;const int CAMERA_NUMBER = 1;

// Check if authentication is enabledif (_pViewer.IsAuthenticationEnabled(CAMERA_IP_ADDRESS, CAMERA_PORT, CAMERA_NUMBER)){ // Set the user name to "admin", the password to "admin_password", and use basic authentication AuthenticationCredentialsNet tmpAuthentication = new AuthenticationCredentialsNet("admin", "admin_password", PelcoAPI.AuthenticationSchemeTypeNet.Basic); _pViewer.SetAuthenticationCredentials(tmpAuthentication);}


USING THE PELCOAPIMPFVIEWERCONTROL COMPONENT

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

NOTE: Example source code can be found in PelcoAPIViewerForm.designer.cs constructor, whichresides in the PelcoAPIViewerSample sample project.

1. Declare the Pelco API MPF Viewer instance.

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:\Program Files\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 could notfunction properly. Please note that the plug-in directory is dependent on where you installed thePelco SDK.

private void BrowseForPluginDir(object sender, EventArgs e){ try { this._pOpenFolder.ShowDialog(this); this._txtFolder.Text = _pOpenFolder.SelectedPath + "\\"; } catch(Exception /*ex*/){}}



// Set example parametersconst String CAMERA_IP_ADDRESS = "10.220.196.179";

42 C5617M-G (10 / 2013)

const int PORT_NUMBER = 80;const int CAMERA_NUMBER = 1;

// Check if authentication is enabledif (_pViewer.IsAuthenticationEnabled(CAMERA_IP_ADDRESS, CAMERA_PORT, CAMERA_NUMBER)){ // Set the user name to "admin", the password to "admin_password", and use basic authentication AuthenticationCredentialsNet tmpAuthentication = new AuthenticationCredentialsNet("admin", "admin_password", PelcoAPI.AuthenticationSchemeTypeNet.Basic); _pViewer.SetAuthenticationCredentials(tmpAuthentication);}


4. Save the stream settings.

private void SaveStreamSettings(object sender, EventArgs e){ 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 withmargins does not automatically center it. You need to set the size and position of the video displayrectangle so that its width and height are 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

C5617M-G (10 / 2013) 43

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

For example:

_pViewer.VideoQuery("NOW", "INFINITE", "10.220.196.169", "49153", "1", "4","uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", False, NULL);

NOTE: Another example usage of this function can be found in the main.cpp file's main function,which belongs to the PelcoAPIViewer sample project SampleConsole9.

The following list shows the parameters:

szStartTime Required. The start time within the stream to start play back.For play back of a recorded RTP stream, the start time must bespecified in UTC using the following time format: YYYY-MM-DDTHH:MM:SS. For play back of a live RTP stream, set the time tothe string "NOW".

szEndTime Required. The end time within the stream to end play back. For playback of a recorded RTP stream, the end time must be specified inUTC using the following time format: YYYY-MM-DDTHH:MM:SS.For play back of a live RTP stream, set the time to the string"INFINITE".

szIpAddress Required. The IP address of the video stream source device forNSM, NVR, or EE500. For a live RTP stream, this is the IP addressof the camera. For play back of a recording, this is the IP address ofNSM/NVR.

szPort Required. The port number of the video stream source devicefor NSM, NVR, or EE500. For a live RTP stream, this is the portnumber of the camera. For play back of a recording, this is the portnumber of NSM/NVR.

szNVRServiceId The NVR ID. Optional for a live RTP stream; required formanual recording of a live RTP stream, and for a play backof a RTP stream. For example, if an end point URL ends with“VideoOutput-1”, the service ID must be set to 1.

szCameraServiceId The last number of the web service endpoint URL of a camera. Forexample, if an endpoint URL ends with “VideoOutput-4”, 4 is theservice ID.

szCameraUuid The IP camera’s UPnP Unique Device Name (UDN). For example,"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15".

NOTE: The IP camera’s UDN is required if you want to start manualrecording of a live stream. Otherwise, this parameter is optional.

bLowBandwidth Sets the stream bandwidth from the camera to low. The cameramust be configured to have the secondary low bandwidth streamenabled. For backwards compatibility, this parameter is set toFALSE by default.

NOTE: This parameter is only valid for live streams.

streamInfoNet Streaming data, which is to be filled in. This value can be passedback to a live or a play back call to StartStream for RTP only. Forbackwards compatibility, this parameter is set to NULL by default.

44 C5617M-G (10 / 2013)

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, whichbelongs to the PelcoAPIViewer sample project SampleConsole9. When in debug mode, if the videoplayback is paused during program execution, the RTCP messages are displayed in the consolewindow. The messages provide information about the RTCP packets.

Before being able to control a video stream, you must first open the stream, and display it on aWindow 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 followingparameters:

szStartTime Required. The start time within the stream to start play back.For play back of a recorded RTP stream, the start time must bespecified in UTC using the following time format: YYYY-MM-DDTHH:MM:SS. For play back of a live RTP stream, set the timeto the string "NOW".

szEndTime Required. The end time within the stream to end play back.For play back of a recorded RTP stream, the end time must bespecified in UTC using the following time format: YYYY-MM-DDTHH:MM:SS. For play back of a live RTP stream, set the timeto the string "INFINITE".

szIpAddress Required. The IP address of the video stream source devicefor NSM, NVR, or EE500. For a live RTP stream, this is the IPaddress of the camera. For play back of a recording, this is theIP address of NSM/NVR.

szPort Required. The port number of the video stream source devicefor NSM, NVR, or EE500. For a live RTP stream, this is the portnumber of the camera. For play back of a recording, this is theport number of NSM/NVR.

szServiceId The last number of the web service endpoint URL. For example,when an endpoint URL ends with “VideoOutput-4”, 4 is theservice ID.

szTransport The video stream’s transport (RTP) URL (optional for a live RTPstream, because the camera starts a MULTICAST stream ifno value is supplied. Required for playback.) The IP addressmust be the IPv4 address of the machine on which the code isrunning, for the network through which it will connect to the videosource. The port number must be an even number, and must notbe in use.

Example:rtp://ip_of_local_machine:open_port_even

NOTE: When one RTP unicast stream is already playing, andanother is started, be sure to set an RTP port that is at leastfour higher than the previous stream. The port that is two higherthan the previous port might already be in use by the previousstream’s audio channel.

szCamUuid The IP camera’s UPnP Unique Device Name (UDN). Forexample, "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15".

C5617M-G (10 / 2013) 45

NOTE: The IP camera’s UDN is required if you want to startmanual recording of a live stream. Otherwise, this parameter isoptional.

szNvrId The NVR ID. Optional for a live RTP stream; required formanual recording of a live RTP stream, and for a play back ofa RTP stream. For example, when an end point URL ends with“VideoOutput-1”, the service ID must be set to 1.

ITimeStampDelegate Signals if you want the timestamp returned by the API. If notimestamp is required, do not supply a value for this parameter.

bVideoOnly Stream video without audio. By default, this parameter is set toFALSE for backwards compatibility.

bLowBandwidth Sets the stream bandwidth from the camera to low. The cameramust be configured to have the secondary low bandwidth streamenabled. For backwards compatibility, this parameter is set toFALSE by default.

NOTE: This parameter is only valid for live streams.

streamInfoNet Streaming data, which is to be filled in. This value can be passedback to a live or a play back call to StartStream for RTP only.For backwards compatibility, this parameter is set to NULL bydefault.

For a live RTP stream:

MyAppNamespace::TimeStamp _pDelegate;const char* pszSesId = NULL;//... Other logic ...pszSesId = _pViewer.StartStream("NOW", "INFINITE","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.

46 C5617M-G (10 / 2013)

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

OPENING, PLAYING, AND DISPLAYING AN RTSP STREAM

NOTE: The related source code for this entry can be found in main.cpp’s main function, whichbelongs to the PelcoAPIViewer sample project SampleConsole9.

1. Initialize the Pelco API Viewer.

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

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

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 theITimeStampDelegate interface, or NULL if you don’t want toreceive timestamps as the video plays. (Optional)

MyAppNamespace::TimeStamp _pDelegate;const char* pszSesId = NULL;//... Other logic for example, 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 beused 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, Playing, andDisplaying an RTSP Stream entry.

To perform a forward or reverse playback of a currently running video stream, call the Pelco APIViewer instance’s PlayForward or PlayReverse method passing in the following parameters:

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

A float value representing the desired playback speed. Validpossible playback speeds can range from 0-300, with zero

C5617M-G (10 / 2013) 47

representing a paused state and one representing regularplayback speed. (Also, one 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 Viewerinstance’s PlayReverse method; passing in the following parameters:


A float value representing the desired playback speed. Validpossible playback speeds can range from 0-300, with "0"representing a paused state and "1" representing regularplayback speed.

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 fastreverse playback of a currently running video stream (using FrameReverse, which reversesby a single i-frame that might include multiple p-frames), call the Pelco API Viewer instance’sPlayForward or PlayReverse method (as appropriate), passing in the following parameters:


A float value representing the desired playback speed. Validpossible playback speeds can range from -300 to 300, withspeed higher than one (regular playback speed). Slow motionis supported where the speed is set at half-speed (for example,-0.5 or 0.5).

Currently for RTP, PlayReverse only plays backward, and PlayForward only plays forward,regardless of whether the speed parameter is negative or positive. Therefore, call PlayForwardfor fast forward, and call PlayReverse for fast reverse.

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

48 C5617M-G (10 / 2013)

//... 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 could produce an unpredictable result.

This entry assumes that you have already completed the steps outlined in the Opening, Playing, andDisplaying an RTSP Stream entry.

To pause currently running video stream, call the Pelco API Viewer instance’s Pause method;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.Pause(pszSesId) !=0 ){//... Handle error ...}

FRAME FORWARD PLAYBACK OF THE RTP STREAM

A frame forward operation advances playback of a currently paused video stream by a single frame.

To perform this operation, call the Pelco API Viewer instance’s FrameForward method, passingin the following parameter:

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

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 i-frame, whichcan include multiple p-frames.

To perform this operation, call the Pelco API Viewer instance’s FrameReverse method; passingin the following parameter:

C5617M-G (10 / 2013) 49

The target video stream’s session ID. A successful call to theStartStream 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 target video 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, andDisplaying the Stream entry.

To perform a stop playback of a currently running video stream, call the Pelco API Viewerinstance’s StopStream method; 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 ...}

START MANUAL RECORDING OF RTP STREAM

Manual recording can only be done on a live RTP stream.

NOTE: The related source code for this entry can be found in the main.cpp file’s main function,which belongs to the PelcoAPIViewer sample project SampleConsole9.

To start manual recording of the RTP stream, call the Pelco API Viewer instance’sStartManualRecording method, passing in the following parameters:

pszSesId The target video stream's session ID.

cameraId The last number of the Web service endpoint URL of the camera.For example, if an endpoint URL ends with “VideoOutput-4”, theID number is 4.

50 C5617M-G (10 / 2013)

nvrIp Required. The IP address of the source of the video stream forNSM, NVR, or EE500. For live RTP, this is the IP address of thecamera. For playback, this is the IP address of the NSM/NVR.

nvrPort Required. The IP address and port number of the source of thevideo stream for NSM, NVR, or EE500. For a live RTP stream,this is the port number of the camera. For playback of a recordedstream, this is the port number of the NSM/NVR (required).

nvrId The NVR ID. For example, if an endpoint URL ends with“VideoOutput-1”, the service ID is 1.

// Start a stream and obtain the session ID pszSesId...

// Start manual recording, passing in the session ID pszSesIdif (_pViewer.StartManualRecording(pszSesId, "4", "10.220.196.169", "49153", "1")) { // ... Handle error ...}

STOP MANUAL RECORDING OF RTP STREAM

Manual recording can only be done on a live RTP stream.

NOTE: The related source code for this entry can be found in the main.cpp file’s main function,which belongs to the PelcoAPIViewer sample project SampleConsole9.

To stop manual recording of the RTP stream, call the Pelco API Viewer instance’sStopManualRecording method, passing in the following parameters:

pszSesId The target video stream's session ID.

// Stop manual recording, passing in the session ID pszSesId_pViewer.StopManualRecording(pszSesId);

SETTING AUDIO VOLUME OF A LIVE OR PLAYBACK RTP STREAM

Audio volume of a playback stream can be controlled using the SetAudioVolume method, bypassing in the video stream’s session ID and an integer volume level, where the range is zero to100, with zero 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 STREAM

To display analytic events for the currently playing video stream, call theDisplayAnalyticEvents method, passing in the target video stream’s session ID and thebEnable set to true.

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

C5617M-G (10 / 2013) 51

//... Handle error ...}

DISPLAYING MOTION EVENTS FOR AN RTP STREAM

To display motion events for the currently playing video stream, call the DisplayMotionEventsmethod, 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 theDisplayTimestampOverlay method, passing in the target video stream's session ID, bEnableset to true, and an instance of ViewerOverlayInfo struct.

If the struct (the 3rd parameter) is set to null, the default style overlay appears. The default stylewould 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

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

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;

52 C5617M-G (10 / 2013)

Boolean bSuccess = _rtpViewer.DisplayTimestampOverlay(_rtpSessionId, true, overlay);

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

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’sTakeSnapShot method; passing in the target video stream’s session ID, and the desired resultingfilename 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 moreinformation, refer to Pan, Tilt, Zoom (PTZ) Control.

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

C5617M-G (10 / 2013) 53

Pan, 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 isNOT intended for immediate production use without modification.

WARNING

The content below assumes that the default target installation directory was chosen duringinstallation.

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, youwill probably want to start controlling your camera’s viewing position: up and down and left and right,as well as magnification (zoom), focus, and camera iris.

This section contains sample C# and C++ that illustrates how to display and control video streams.Complete C# and C++ sample programs are contained in the following subdirectory where the PelcoSDK is installed: Pelco\API\SampleCode\PTZControlWrapperSample

The StopContinuous method is available to stop the camera from continually moving, and theStop() call is available to stop Lens control (zoom, iris, and focus) actions. To stop continuouspositioning calls, pass in a zero value. For example, after executing ContinuousMove, callContinuousMove(0, 0) to stop moving.


To move your IP camera’s current view, you need to start using the Pelco SDK’s PTZ ControlWrapper. The PTZ Control Wrapper is an easy to use tool for controlling various PTZ and lens relatedfunctionality. 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 sectioncovers the PTZ Control Wrapper. This sample project exhibits PTZ Control Wrapper functionality.

NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of themethods 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++) orProgram.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper sample project.

NOTE: In release mode, select the Enable unmanaged code debugging check box in the projectsettings to view console output.

To create an instance of the managed PTZ Control Wrapper, use the following parameters:

Your IP camera’s current IP address

Your IP camera’s port number

Your IP camera’s service ID (usually one unless this numberrepresents a channel in a multichannel encoder)


54 C5617M-G (10 / 2013)

C++ Example

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

Verify that authentication is enabled for the camera, and if so, set the authentication credentials. Forexample:

// Check if authentication is enabledif (ptzControlWrapper.IsAuthenticationEnabled()){ // Set the user name to "admin", the password to "admin_user", and use basic authentication AuthenticationCredentials credentials("admin", "admin_password", PelcoAPI::AuthenticationCredentials::BASIC); ptzControlWrapper.SetAuthenticationCredentials(&credentials);}


After you are finished with the camera operations, 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);

Verify that authentication is enabled for the camera, and if so, set the authentication credentials. Forexample:

// Set example parameters#define CAMERA_IP_ADDRESS "10.220.196.179"#define PORT_NUMBER 80#define CAMERA_NUMBER 1

// Check if authentication is enabledif (managedPTZControl.IsAuthenticationEnabled(CAMERA_IP_ADDRESS, CAMERA_PORT, CAMERA_NUMBER)){ // Set the user name to "admin", the password to "admin_password", and use basic authentication PelcoAPI::AuthenticationCredentials authentication("admin", "admin_password", PelcoAPI::AuthenticationCredentials::BASIC); managedPTZControl.SetAuthenticationCredentials(&authentication);}

After you are finished with the camera operations, stop all PTZ Control Wrapper actions:

Boolean bSuccess = managedPTZControl.Stop();

C5617M-G (10 / 2013) 55

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 APIreference documentation.

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

//panning leftBoolean bSuccess = managedPTZControl.ContinuousPan(-10000);//panning rightBoolean bSuccess = managedPTZControl.ContinuousPan(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 zero to the ContinuousPan method as shown inthe following example.

bool bSuccess = ptzControlWrapper.ContinuousPan(0);

Boolean bSuccess = managedPTZControl.ContinuousPan(0);

CONTINUOUS TILTING

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 C++ sampleproject.


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



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


56 C5617M-G (10 / 2013)

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.

For more details on the ContinuousTilt method, please refer to the PTZ Control Wrapper APIreference documentation.

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

//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 to Continuous Stop for details), or pass zero to the ContinuousTilt method as shown inthe following example.

bool bSuccess = ptzControlWrapper.ContinuousTilt(0);

Boolean bSuccess = managedPTZControl.ContinuousTilt(0);

CONTINUOUS DIAGONAL MOVEMENT

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 C++ sampleproject.


This entry covers the portion of the sample project that deals with continuously moving the camera ina diagonal manner.



2. Call the ContinuousMove method.

The first parameter represents both speed and direction on the X plane. Use a negative integerto pan left and a positive integer to pan right. The second parameter represents both speed anddirection on the Y plane. Use a negative integer to tilt down and a positive integer to tilt up. Formore details on the ContinuousMove method, pplease refer to the PTZ Control Wrapper APIreference documentation.

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

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





C5617M-G (10 / 2013) 57

//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 asshown in the following example.

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

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

STOPPING CONTINUOUS MOVEMENT

To stop the camera from continually moving, call the StopContinuous method.

bool bSuccess = ptzControlWrapper.StopContinuous();

Boolean bSuccess = managedPTZControl.StopContinuous();

ENABLING CONTINUOUS PAN/TILT/MOVE AND ZOOM APIS BY UDP INSTEAD OF TCP

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 using UDP.

bool bSuccess = ptzControlWrapper.SetLowLatencyMode(true);

Boolean bSuccess = managedPTZControl.SetLowLatencyMode(true);

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

PANNING TO A SPECIFIC POSITION



This entry covers the portion of the sample project that deals with moving the camera to a specificpoint 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 therotational 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 APIreference documentation.



58 C5617M-G (10 / 2013)

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

bool bSuccess = ptzControlWrapper.AbsolutePan(36000);

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 therotational 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 referencedocumentation.

Generally, the tilting range is limited to 0 to -90 degrees (0 to -9000 centidegrees). This limit mightdiffer, depending on the type of camera used.

bool bSuccess = ptzControlWrapper.AbsoluteTilt(-9000);

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 therotational X and Y planes.

• 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.



C5617M-G (10 / 2013) 59

Refer to your camera model’s specifications for tilt position limits. For more details on theAbsoluteMove method, please refer to the PTZ Control Wrapper API reference documentation.

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

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 planevalues that the camera should move from the current location.

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

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

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 currentposition expressed as a specific point in 3D space.



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

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

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

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

MANAGING THE MAGNIFICATION (ZOOM) VALUE






60 C5617M-G (10 / 2013)

This section describes how to change the camera’s current magnification level. Magnification refersto the camera’s zoom level, which in turn describes the focal length for which the camera's lens iscurrently set. Zoom level is expressed as 100 times the level of magnification that you want. Forexample, 1x magnification becomes 100, and 18x magnification becomes 1800.

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



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. Formore details on the AbsoluteZoom method, refer to the PTZ Control Wrapper API referencedocumentation.

bool bSuccess = ptzControlWrapper.AbsoluteZoom(150);

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 moredetails on the GetAbsoluteZoom method, refer to the PTZ Control Wrapper API referencedocumentation.

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

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

MANAGING THE FOCUS VALUE



NOTE: It is best practice to 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 theIP 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.

2 To start focusing nearer.





C5617M-G (10 / 2013) 61

If the request was successful, your camera’s focus should now be changing (unless you passeda 0). This will not stop until a SetFocus request is made with a different value, or if you call theStop method, which will stop movement or lens related action the camera is currently doing.

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

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 itautomatically. To enable this feature, call the AutoFocus method and pass a boolean value oftrue. To disable it, just pass a boolean value of false.

bool bSuccess = ptzControlWrapper.AutoFocus(true);

Boolean bSuccess = managedPTZControl.AutoFocus(true);

IRIS CONTROL



NOTE: It is best practice to let your IP camera manage its iris automatically.

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 Stopmethod, which will stop movement or lens related action the camera is currently doing.

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

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

62 C5617M-G (10 / 2013)

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

bool bSuccess = ptzControlWrapper.AutoIris(true)

Boolean bSuccess = managedPTZControl.AutoIris(true)

SCRIPTING

One of Pelco’s most powerful features enables users to manage and run scripts. Scripts allow you toextend the behavior of Pelco devices with little effort. Before learning how to use the SDK’s scriptingrelated features, it is important 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 settingssuch as auto iris and autofocus, collectively known as a bookmark. Users can save multiple presetsper camera. For example if you’re monitoring several specific points using the same camera, you canset one preset for each location that needs to be monitored; each with its own set of zoom, iris, andfocus values.

Presets that you create must be names, such as “PRESETX”, where the keyword PRESET must beused (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 cameraguarding a hallway with two entrances and a window. With patterns, you can set a bookmark forcamera behavior that changes the camera’s view from one of the three points of interest to anotherevery 15 seconds.

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 preconfigured patterns that cannot be created. You cannot create a Pattern bycombining existing Presets.

Like a preset, patterns are typically only relevant for IP cameras. The number of patterns that can berecorded and activated is dependent on the Pelco device. For example, the 16X and 18X models ofthe Spectra IV can store only a single pattern, while the 22X, 23X and 35X Spectra IV models canstore 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 amacro.

CREATING A PRESET



These steps will show you how to create a preset.


C5617M-G (10 / 2013) 63


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 anexisting one by that name.

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

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

UPDATING AN EXISTING PRESET

To update an existing preset, just following the steps outlined in Creating a Preset, ensuring thatyou 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.

Depending on whether the pattern already exists or not, it will either create a new one or modify anexisting one by that name.

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

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 witha certain zoom and focus level. After waiting for some predetermined time, you then move thecamera’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 didbefore.

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

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

64 C5617M-G (10 / 2013)

GOING TO AN EXISTING PRESET



To move the device to a specific preset state, call the PTZ Control Wrapper’s GotoPresetmethod, passing in the name of the preset.

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

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

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

REMOVING AN EXISTING PRESET



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

The preset will then be deleted.

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

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 name of the pattern to modify as the parameter for both theStartPatternRecording and EndPatternRecording methods.

EXECUTING AN EXISTING PATTERN



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

C5617M-G (10 / 2013) 65

The script will continue to run until stopped by the user using the HaltPattern method, detailedStopping a Pattern Currently Being Executed on page 65.

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

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 HaltPatternmethod, passing in the name of the script to stop.

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

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

66 C5617M-G (10 / 2013)

Events and Alarms

OVERVIEW

WARNING


WARNING

The content in this section assumes that the default target installation directory was chosen duringinstallation.


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 someparticular criteria is met. Specifically Pelco products, acting as event providers, send these eventsand alarms to their subscribers. Typically event providers are web services, while subscribers aresoftware clients. For example, if an IP camera’s MotionDetection service detected movement within aparticular region in the video frame, it can send an event to all of its subscribers such as a VMS.

This section contains sample C# and C++ that illustrates how to use events and alarms. CompleteC# and C++ sample programs are contained in the following subdirectory where the Pelco SDK isinstalled: Pelco\API\SampleCode\EventArbiterSample.

WHERE DOES THE PELCO SDK FIT?

The Pelco SDK provides you with two components for eventing: the Event Arbiter Library andthe 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 twocomponents. The Event Arbiter Library is the primary component for dealing with eventing. It is forusers looking for the most flexibility and control. Conversely, the Event Manager is a componentthat 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


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

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

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

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

C5617M-G (10 / 2013) 67

The Event Arbiter Library allows you to either subscribe directly to a device’s web service events orindirectly; allowing you to choose to subscribe to the particular web service from all devices providingthe service.

Once a subscription is established, the software client just has to wait for an event to fire. Theweb service will direct the event to your software client through the Pelco SDK. As for subscriptionrenewals, it should be noted that the Event Arbiter Library now also handles subscription renewalsautomatically. You will no longer have to worry about renewing an event subscription.

The Event Arbiter Library allows subscriptions to all available web services for all devices on a givennetwork that fall under a specific category. To subscribe, all you have to provide is the event category.The categories are as follows:

• Alarm Array Configuration events. These events are sent when a physical alarm input on a deviceis triggered.

• Diagnostic Reporting events. These events are sent when a hardware alarm on a device istriggered (for example, a temperature alarm, video loss alarm, and so on).

• Motion Detection events. These events are sent when a motion alarm is triggered.• Video Analytics events. These events are sent when a video analytic alarm is triggered.• Relay Array Configuration events. These are included for backward compatibility only, no events

are generated.

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 webservice active

Able to subscribe to all devices at once thatprovide a specific web service.

All event data is available and parsed.

System Manager available; EventArbiter webservice 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 simplifiesevent operations even further. It allows subscriptions to all available web services for all devices ona given network that fall under a specific category. To subscribe, all you have to provide is the eventcategory. The categories are as follows:

• Alarm Array Configuration events• Diagnostic Reporting events• Motion Detection events• Video Analytics events• Relay Array Configuration events (included for backward compatibility only, no events are

generated)

Environment Pelco SDK Consequence

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

System Manager available; EventArbiter webservice active

Able to subscribe to all available web servicesthat are under a specified category throughthe SM EventArbiter web service, in onesubscription.

68 C5617M-G (10 / 2013)

System Manager available; EventArbiter webservice NOT 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 EventManagerlibrary will automatically subscribe to eachindividual device's web service in the specifiedcategory, resulting in many subscriptions.

EVENT ARBITER LIBRARY COMPARED TO EVENT MANAGER

Event Arbiter Event Manager

Harder to use, but with more options andflexibility.

Easier to use, but not as flexible: the user onlyneeds to choose the category of events he isinterested in receiving.

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

Able to subscribe to a single device’s webservice using either an IP address or UDN.

Able to subscribe to all instances of a particularweb service. That is, a user can subscribe to allMotionDetection web services for all devices withjust one request.

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

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 EventManager.

2. Create the method that will handle the event. Associate that method with the Event Arbiter Libraryinstance’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 thesubscribed web service.

CREATING AN EVENT AGENT

NOTE: The related source code for this entry (for C++) can be found in the MyEventAgentheader file, which belongs to the Event Arbiter Library C++ sample project. The relatedsource code for this entry (for C#) can be found in the class MyEventAgentNet in theManagedEventArbiterSample.cs file, which belongs to the Event Arbiter Library C# sampleproject.

The main purpose of an EventAgent class is to deal with any incoming events that have beensubscribed to by the Event Arbiter.

NOTE: For complete details about the Event Arbiter, refer to the Pelco SDK Event Arbiter referencemanual.

To create your own EventAgent class, implement the NotifyEvent method in theIEventAgent interface. NotifyEvent includes parameters for the response and the event.

Details of implementation are left to the user. However in the MyEventAgent sample class, wedemonstrate basic functionality for accessing event related data.

#include "PelcoAPI/Trace.h"#include "PelcoAPI/EventArbiterDefs.h"

C5617M-G (10 / 2013) 69

#include "MyEventAgent.h"

//=======================================================// Constructor//=======================================================MyEventAgent::MyEventAgent() : m_nCounter(0){}

//=======================================================// Destructor//=======================================================MyEventAgent::~MyEventAgent(){}

//=======================================================// NotifyEvent//=======================================================void MyEventAgent::NotifyEvent(const char * szResponse, const Event * pEvent){ TRACE_INFO("Notify EVENT %d: \n", ++m_nCounter);

// Record the event UDN TRACE_INFO("\tUDN: %s\n", pEvent->m_strUdn.c_str());

// Record the event service identifier TRACE_INFO("\tService ID: %s\n", pEvent->m_strServiceId.c_str()); // Record the event time in UTC format TRACE_INFO("\tUTC Time: %s\n", pEvent->m_strUtcEventTime.c_str());

// Record the event type TRACE_INFO("\tType: %d\n", (int) pEvent->m_nType); // Record the event friendly name TRACE_INFO("\tFriendly Name: %s\n", pEvent->m_strDeviceFriendlyName.c_str());

// If the event is for the alarm array if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION) { // Record the event's associated camera UDN TRACE_INFO("\tAssociated Camera UDN: %s\n", pEvent->m_strAssociateCameraUdn.c_str()); for (size_t i = 0; i < pEvent ->m_alarmOrRelayInfo.size(); i++) { // Record the alarm identifier TRACE_INFO("\tAlarm ID: %d\n", pEvent->m_alarmOrRelayInfo[i]->m_nId); // Record the alarm severity TRACE_INFO("\t\tSeverity: %d\n", pEvent->m_alarmOrRelayInfo[i]->m_nSeverity); // Record whether the alarm was changed (m_bChanged is true or false, // depending on whether the event was changed) TRACE_INFO("\t\tChanged: %s\n", (pEvent->m_alarmOrRelayInfo[i]->m_bChanged ? "Yes" : "No")); // Record whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off)

70 C5617M-G (10 / 2013)

TRACE_INFO("\t\tState: %s\n", (pEvent->m_alarmOrRelayInfo[i]->m_bAlarmState ? "On" : "Off")); } } // If the event is for the relay array else if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_RELAY_ARRAY_CONFIGURATION) { for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size(); i++) { // Record the alarm identifier TRACE_INFO("\tRelay ID: %d\n", pEvent->m_alarmOrRelayInfo[i]->m_nId);

// Record whether the alarm was changed (m_bChanged is true or false, // depending on whether the event was changed) TRACE_INFO("\t\tChanged: %s\n", (pEvent->m_alarmOrRelayInfo[i]->m_bChanged ? "Yes" : "No"));

// Record whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off) TRACE_INFO("\t\tState: %s\n", (pEvent->m_alarmOrRelayInfo[i]->m_bAlarmState ? "On" : "Off")); } } // If the event is for motion detection else if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_MOTION_DETECTION) { // Record whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off) TRACE_INFO("\tAlarm State: %s\n", (pEvent->m_bAlarmState ? "On" : "Off")); } // If the event is for video analytics else if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_VIDEO_ANALYTICS) { // Record whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off) TRACE_INFO("\tAlarm State: %s\n", (pEvent->m_bAlarmState ? "On" : "Off"));

// Record the alarm severity TRACE_INFO("\tSeverity: %d\n", pEvent->m_nVideoAnalyticsSeverity); }

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

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

// Display the event UDN Console.Write("\tUDN: {0}\n", eventNet.m_sUdn);

C5617M-G (10 / 2013) 71

// Display the event service identifier Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId); // Display the event time in UTC format Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime); // Display the event type Console.Write("\tType: {0}\n", eventNet.m_nType); // Display the event friendly name Console.Write("\tFriendly Name: {0}\n", eventNet.m_sDeviceFriendlyName); // If the event is for the alarm array 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++) { // Display the alarm identifier Console.Write("\tAlarm ID: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nId); // Display the alarm severity Console.Write("\t\tSeverity: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nSeverity); // Display whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off) Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bAlarmState ? "On" : "Off")); } } // If the event is for the relay array else if (eventNet.m_nType == 2) { for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++) { // Display the alarm identifier Console.Write("\tAlarm ID: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nId); // Display whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off) Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bAlarmState ? "On" : "Off")); } } // If the event is for motion detection else if (eventNet.m_nType == 4) { // Display whether the alarm was on or off (m_bAlarmState is true or false, depending on // whether the alarm was on or off) Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" : "Off")); } // If the event is for video analytics else if (eventNet.m_nType == 8) { // Display whether the alarm was on or off (m_bAlarmState is true or false, depending on

72 C5617M-G (10 / 2013)

// whether the alarm was on or off) Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" : "Off")); // Display the alarm severity 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++ andC# 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, passingin the following:

login ID A result returned from a successful call to the UserLoginmethod.

target device’s UniqueDevice Name (UDN)

To retrieve a deviceUDN, cycle through the stored results of aGetDevices call within your IDeviceStorage class instance.For details, refer to Querying Available Devices from the SystemManager.

web service’s Service ID A URN value found in the web service’s corresponding WSDLfile.

attribute name ofSYS_UpnpEventSubUrl

pointer to the variable thatwill hold the result

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

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 mainfunction which belongs to the Event Arbiter Library sample project. This assumes that you havealready completed the steps outlined in Creating an Event Agent.



2. Declare the Event Arbiter Library instance. Set the Event Arbiter Library instance's networklocation and port number, using the System Manager’s IP address and port number.

C5617M-G (10 / 2013) 73

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

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 IPaddress and port number.

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#

NOTE: In release mode, you need to select the Enable unmanaged code debugging checkbox inthe project settings to view console output.

A System Manager Is Available on Your Network

NOTE: The related source code for this entry can be found inManagedEventArbiterSample.cs’s main function, which belongs to the Event Arbiter LibraryC# sample project. This assumes that you have already completed the steps outlined in Creating anEvent 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 Libraryinstance's network locationand port number

The client machine where it resides.

Your implemented EventAgent to register

The System Manager’s IPaddress and port number.

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

boolean True to force the EventArbiter library to use the SystemManager, false otherwise.

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

A System Manager Is Not Available on Your Network

74 C5617M-G (10 / 2013)







Use empty strings forparameters representingthe System Manager’s IPaddress and port number.

Set the last parameter tofalse.

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 mainfunction, which belongs to the Event Manager Library C++ sample project. The related source codefor this entry (for C#) can be found in 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 IPaddress and port number.

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

boolean True to stop the EventArbiter library from using the SystemManager. False to start the EventArbiter library using the SystemManager.

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

C5617M-G (10 / 2013) 75

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

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

DEVICE OR SERVICE SPECIFIC SUBSCRIPTIONS

This section describes the most common scenarios involving subscription to events from a specificweb service or device.

USING THE EVENT ARBITER LIBRARY TO SUBSCRIBE USING THE DEVICE’S IPADDRESS

NOTE: This entry is relevant for users who are not relying on either the System Manageror its EventArbiter service. The related source code for this entry can be found inEventArbiterSample.cpp’s main function (for C++) or ManagedEventArbiterSample.cs’smain 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 particularweb service using the device’s IP address. Having an event subscription simply tells a device thatyou would like to receive its event notifications. To request a event subscription, the following must bedone:

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 inC#), passing the event subscription URL.

For details, refer to Returning the Event Subscription URL. If the request was successful, themethod will return the event subscription's unique ID which will allow users to either renew orunsubscribe the event subscription. If unsuccessful, the method returns NULL.

NOTE: Pelco SDK now automatically handles subscription renewals.

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

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

USING THE EVENT ARBITER LIBRARY TO SUBSCRIBE USING THE EVENTSUBSCRIPTION URL

This topic describes how to use the Event Arbiter Library to subscribe to a specific device’s particularweb service using the Event Subscription URL.

NOTE: This entry is ONLY relevant for users who use an Endura network, specifically with anactive System Manager and an enabled EventArbiter service on the System Manager. The relatedsource code for this entry can be found in EventArbiterSample.cpp’s main function (for C++) orManagedEventArbiterSample.cs’s main function (for C#), which belongs to the Event ArbiterLibrary sample project.



2. Construct an event service ID.

76 C5617M-G (10 / 2013)

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

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

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

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

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


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

String strSid_1 = pEventArbiter.SubscribeEvents(strEventServiceId);

USING THE EVENT ARBITER LIBRARY TO SUBSCRIBE TO ALL INSTANCES OF ASERVICE


If you want to subscribe to all devices that provide a specific web service like MotionDetection (or anyother 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 webservice’s associated WSDL file (it should be near the top of the file).

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

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

3. Call the Event Arbiter wrapper instance's SubscribeToEvents method (SubscribeEvents inC#), passing the event URN.


C5617M-G (10 / 2013) 77


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

String strSid_2 = pEventArbiter.SubscribeEvents(strEventUrn);

USING THE EVENT ARBITER LIBRARY TO SUBSCRIBE TO A DEVICE'S WEB SERVICE

This topic describes how to use the Event Arbiter Library to subscribe to a specific device’s particularweb service using the Event Subscription URL.




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 WSDLfile. (For details on determining a web service’s ID, refer to Returning the Event Subscription URL.)

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

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

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



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

String strSid_1 = pEventArbiter.SubscribeEvents(strEventServiceId);

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 mainfunction (for C++) or ManagedEventArbiterSample.cs’s main function (for C#), which belongs tothe Event Arbiter Library sample project. This entry assumes that the user has already completed thesteps outlined in any of the Event Arbiter subscription-related entries.

To unsubscribe from an existing event subscription, call the Event Arbiter wrapper instance'sUnSubscribeToEvents method (UnsubscribeEvents in C#), passing the subscriptionidentifier.

78 C5617M-G (10 / 2013)

You should receive subscription IDs on successful calls to SubscribeToEvents. If the requestwas successful, the method will return one (for C++) or true (for C#). Otherwise it will return 0 (forC++) or false (for C#).

const char * szSid_1 = pEventArbiter->SubscribeToEvents("urn:schemas-pelco-com:service:MotionDetection:1");// ... misc logic ...pEventArbiter->UnSubscribeToEvents(strSid_1);

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

MASS SUBSCRIPTIONS BY CATEGORY

This sections explains how to subscribe to all events that fall under a 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 mainfunction (for C++) or ManagedEventManagerSample.cs’s main function (for C#), which belongs tothe Event Manager Library sample project. Also note that the Event Manager requires the presence ofa System Manager on the network.

The following steps will allow you to subscribe to all events that fall under one of several categoriesdefined 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 bythe Pelco SDK.

The Event Manager will now start ‘listening’ to events. Use one or more of the following options(you can add several of these values together to subscribe to more than one category of event at atime):

enum EventType{ EVENT_TYPE_UNKNOW = 0x00000000, EVENT_TYPE_ALARM_ARRAY_CONFIGURATION = 0x000000001, EVENT_TYPE_RELAY_ARRAY_CONFIGURATION = 0x00000002, EVENT_TYPE_MOTION_DETECTION = 0x00000004, EVENT_TYPE_VIDEO_ANALYTICS = 0x00000008, EVENT_TYPE_DIAGNOSTIC_REPORTING = 0x00000010, EVENT_TYPE_MASK = 0x0000001F};

enum REGISTER_EVENTS{ ALARM_ARRAY_CONFIGURATION = 0x00000001, RELAY_ARRAY_CONFIGURATION = 0x00000002, MOTION_DETECTION = 0x00000004, VIDEO_ANALYTICS = 0x00000008, DIAGNOSTIC_REPORTING = 0x00000010}

C5617M-G (10 / 2013) 79

Alarm Array Configuration Events that are related to the AlarmArrayConfiguration webservice, such as an alarm circuit connected to the camera hasbeen turned on or off.

Relay Array Configuration Events that are related to the RelayArrayConfiguration webservice. This web service generates no events. The functionalityis provided for backward compatibility only.

Motion Detection Events that are related to the MotionDetection web service, suchas 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 eventcategories, allowing you to subscribe to all of them at once.

NOTE: Always refer to the EventArbiterDefs header for the latest options. If the request wassuccessful, the method will return true; false otherwise.

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

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 mainfunction (for C++) or ManagedEventManagerSample.cs’s main function (for C#), which belongs tothe Event Manager Library sample project. Also note that the Event Manager requires the presence ofa System Manager on the network. This entry assumes that the user has already completed the stepsoutlined in the Event Manager subscription-related entry.

To unsubscribe from an existing event subscription for Event Manager, call the Event Managerinstance’s Stop method.

If successful it will return true, false otherwise. The following example unsubscribes from all activeevent subscriptions at once.

bool ret = pEventManager->Stop();

Boolean ret = pEventManager.Stop();

HANDLING INCOMING EVENTS

NOTE: The related source code for this entry can be found in MyEventAgent.cpp’s NotifyEventfunction (for C++), or the NotifyEvent function in the class MyEventAgentNet (for C#), whichbelongs to the Event Arbiter Library sample project. The availability of some data is dependent on theavailability of a System Manager on your network, that is, if a System Manager is not online, someevent data will be missing.

The Pelco SDK already parses event related data for you. All that is required is for you to figure outhow 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.

80 C5617M-G (10 / 2013)

This is where you will process any incoming event notifications. Events will be represented by theEvent struct as defined in the EventArbiterDefs header. (The raw event XML string data will beencapsulated 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

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

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 willprovide information on the camera it is associated with as well as general alarm data.

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 zero off one on pEvent->m_alarmOrRelayInfo[i]->m_bState; } }

if (eventNet.m_nType == 1) { Console.Write("\tAssociated Camera UDN: {0}\n", eventNet.m_sAssociateCameraUdn);

C5617M-G (10 / 2013) 81

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\tSeverity: {0}\n", eventNet.m_alarmOrRelayInfo[i].m_nSeverity); Console.Write("\t\tState: {0}\n", (eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off")); } }

The RelayArrayConfiguration web service does not generate events. The functionality isprovided for backwards compatibility only.

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; } }

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 themotion detection region is active or inactive.

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

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); }

82 C5617M-G (10 / 2013)

The szResponse parameter contains the raw event data in XML format. This is useful fordebugging, or XML data binding to your classes.

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

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 mainfunction (for C++) or ManagedEventArbiterSample.cs's Main function (for C#), which belongs tothe Event Arbiter Library sample project. The availability of some data is dependent on the availabilityof a System Manager on your network, that is, if a System Manager is not online, some event datawill 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.

pEventArbiter->RegisterEventAgent(NULL);

MyEventAgentNet pAgent = null;

2. To poll events one by one using Event Arbiter or Event Manager, call the Event Arbiter or EventManager instance'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))// ...

C5617M-G (10 / 2013) 83

Extracting Audio and Video Metadata

EXTRACTING AUDIO AND VIDEO METADATA

WARNING


WARNING



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

This section contains sample C# and C++ that illustrates how to use meta-data. Complete C# andC++ sample programs are contained in the following subdirectory where the Pelco SDK is installed:Pelco\API\SampleCode\MetaDataParserSample


The Meta-data Parser is a utility for parsing Pelco Video Elementary Stream (VES) meta-data fromPelco 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 theelementary stream.

MOTION DETECTION METADATA


84 C5617M-G (10 / 2013)

Motion detection involves computing the difference between two images. If the difference betweenthe compared images crosses a certain threshold value, motion is detected and the selected Alert istriggered.

The key to Pelco’s motion detection feature is the Region of Interest (ROI). The ROI denotes amotion detection region within a video frame. A motion detection region is essentially a grid of motiondetection 16x16 pixel cell blocks. These cells have sensitivity and movement threshold limits. Thesensitivity level dictates the amounts of movement that are registered within the ROI, while thethreshold dictates the amounts of blocks that are registered within the ROI before the selected alarmis triggered.

What motion detection metadata is available? Currently in terms of metadata, each video frame canonly hold a single ROI. Consequently, for each frame, the metadata describes the length and width ofthe 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 thePelco 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. TheMetadata 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).• 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).

C5617M-G (10 / 2013) 85

• tv_year -- The time interval in years since 1901.• 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 savingsoffset, the current timezone, and values in local time.

GETTING STARTED

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

Depending on whether you would like to use the release version of the Pelco SDK libraries or thedebug version, change the Working Directory value as appropriate. Assuming that you did not changethe default installation directory for the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Debug.

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

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

NOTE: The related source code for this entry can be found in main.cpp’s main function, whichbelongs to the Metadata Parser C++ sample project.

1. Create a MetaDataParser instance.

2. Call its SetData method, passing the buffer containing the data to analyze and the buffer lengthas 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,which belongs to the MetaDataParser C++ sample project. You are expected to implement the actuallogic.

86 C5617M-G (10 / 2013)

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 parameterv1, while the lower right corner is determined by the parameter v2. If the fill parameter is set totrue, the rectangle should be solid. 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 fillparameter is set to true, the polygon should be solid. Otherwise, it should only be an outline.

virtual void DrawPolygon(PelcoAPI::VECTOR *vectors, unsigned int count,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 predrawing 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 ProcessTimestampfunction, which belongs to the Metadata Parser C++ sample project.

1. Initialize the MetaDataParser.

For details, refer to Initializing the Metadata Parser Class.

C5617M-G (10 / 2013) 87

2. Verify whether the parser has found a timestamp by calling the HasTimeStamp method, which willreturn true if found, false otherwise.

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

3. If there is a timestamp, call the GetTimeStampAsString method, passing in a local timeBoolean parameter, which if true returns the timestamp in local time, while false returns theUTC 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 ProcessMotionDatafunction, which belongs to the Metadata Parser C++ sample project.

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 anew MotionData instance.

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 ProcessMotionDatafunction, which belongs to the Metadata Parser C++ sample project.

NOTE: This entry assumes that the user has already completed the steps outlined in Creating aMetadata Renderer Class.


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

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

88 C5617M-G (10 / 2013)

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

SampleMetaDataRenderer renderer;

4. Create a new COLOR struct, setting the desired alpha transparency and colors to display on thescreen. In this example, 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 ProcessDrawingDatafunction, which belongs to the Metadata Parser C++ sample project.


2. Determine if the parser has found drawing data by calling the HasDrawingData method, whichwill return true if found, false otherwise.

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

3. If drawing metadata is found, call the GetDrawingData method, pulling the result into aDrawingData 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 RenderDrawingDatafunction, which belongs to the Metadata Parser C++ sample project.

This entry assumes that the user has already completed the steps outlined in Creating a MetadataRenderer 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 iftrue, retrieve the drawing metadata by calling the GetDrawingData.

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

C5617M-G (10 / 2013) 89

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 thescreen. 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();

90 C5617M-G (10 / 2013)

Exporting Video

OVERVIEW

WARNING


NOTE: The content in this section assumes that the default target installation directory was chosenduring installation.


This section contains sample C# and C++ that illustrates how to perform exports. Complete C# and C++ sample programs are contained in the following subdirectory where the Pelco SDK is installed C:\Program Files\Pelco\API\SampleCode\ExporterSample

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

WHERE DOES THE PELCO SDK FIT?

The Exporter module is a Pelco API SDK component that can export playback video, and save itin either AVI, MP4, 3GP, or PEF format. It is multithreaded to help ensure good performance andto export as many streams as possible at any given time. Moreover, users will be able to export orplayback saved streams without having to initialize the stream. Consequently it provides the flexibilityto 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 affects performance andauthentication). 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 streamsto save them to a video file. The most common file format for such video files is AVI. However, AVI isonly a container format, not a compression format. From this point forward, there are two principallydifferent 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 beplayed 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 videostream coming from the camera is encoded using MPEG-4, the exported file will generally useMPEG-4 as well. No re-coding will be necessary unless you add overlays to the export. If the videostream coming from the camera is encoded using H.264, the exported file can use H.264 or MPEG-4,depending on the container format (3GP, AVI, MP4, PEF) and whether you add overlays to theexport. (There is relatively little difference in size between container formats and compressionformats.)

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

Native Video

For recording large amounts of video data, such as when building near line storage solutions, storagein the original (or native) format is essential as it preserves the bit rate. To play back these nativevideo files, a codec that supports the complete ISO MPEG-4 standard (or at least the ISO MPEG-4


C5617M-G (10 / 2013) 91

SP profile) must be installed in the end-user's media player. If a codec does not support the ISOMPEG-4 SP profile, the received video will not play back. Fortunately there are many complete ISOMPEG-4 codecs available; ranging from free, open source versions to highly optimized commercialversions

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, whichbelongs to the Export C++ sample project. The related source code for this entry (for C#) can befound in Program.cs’s Main function, 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 pluginsdirectory.

The plugin directory contains components that are key to theSDK’s encoding, decoding, and transcoding capabilities. Withouta proper reference, key features of the Pelco SDK could notfunction properly. Assuming that you didn’t change the defaulttarget installation directory, it can be found here: C:\ProgramFiles\Pelco\API\Libs\Debug\Plugins

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

The System Manager’s IPaddress.

For details on the importance of the System Manager for theExporter, refer to Video Exports in the Appendix.

The IP Address to use forreceiving incoming streams

The client machine using the Pelco SDK.

(Optional) The name of theuser that is performing theexport.

(Optional) The initial localport to use for the export.

NOTE: If you are running simultaneous exports, you mustprovide different port values.

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

The exporter will keep increasing port numbers starting with theinitial port number until the end port is reached.

PelcoAPI::EnduraExporter exporter;

92 C5617M-G (10 / 2013)

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

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

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

SETTING UP OVERLAY DATA ON VIDEO TO BE EXPORTED


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’sformat, 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 usermust 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 SingleVideo Export, the user must use an OverlayInfo/OverlayInfoNet instance for eachoverlay type wanted before starting the export.

exportInfo[i].overlayInfo = newPelcoAPI::OverlayInfo[overlayNum]; exportInfo[i].overlayInfo[0].type =PelcoAPI::OVERLAY_TYPE_TIMESTAMP;

C5617M-G (10 / 2013) 93

// 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 supportoverlays.)

timestamp The overlay displays a timestamp that provides the time in localtime.

cameraname The overlay displays a camera’s name. Typically the camera namedisplayed 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, simplystart assigning the desired values with it such the font to use, the color of the font, the location ofthe overlay, and so on.

The following is a list of other overlay settings (some can apply to certain overlay types as noted):

location The general screen location of the overlay. (Refer to theDataMixerPluginDefines header for the latest definition ofOverlayLocation.)

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 right 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.

94 C5617M-G (10 / 2013)

value The actual value to display. For picture overlays, this is the fullpath to the picture to display. While for cameraname overlays,this is the name of the camera. Finally for textstring overlays, thisis just the alphanumeric value to display on the overlay. (Thisdoes not apply to timestamp overlays.)

fontName This is the name of an available font to use for displayingoverlays. (This does not apply to picture overlays. )

fontSize This is the size of a font. (This does not apply to picture overlays.)

fontColor This is the color of a font. (This does not apply to pictureoverlays.)

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 pictureoverlays.)

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 ortwo 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 ortwo digits, for example, 12/8/01 or 2/23/01

mmddyy This 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

C5617M-G (10 / 2013) 95

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 twodigits, 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

dmyyyy This date format conforms to the following structure: d/m/yyyy(day/month/year), where both 'm' and 'd' could be either one ortwo 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 ortwo 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 ortwo 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 ortwo 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:seconds AM/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 beeither 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 oneor 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 or18:07:12

96 C5617M-G (10 / 2013)

hmstt This time format conforms to the following 12 hour structure:h:m:s tt (hours:minutes:seconds), where 'h', 'm', or 's' could beeither one or two digits, for example, 6:7:12 AM, 12:17:12 PM, or12:3:2 PM

tthms This time format conforms to the following 12 hour structure: tth:m:s (AM/PM hours:minutes:seconds), where 'h', 'm', or 's' couldbe 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: tthh:mm:ss (AM/PM hours:minutes:seconds), for example, AM06:07:12, PM 12:17:12, or PM 12:03:02

hms This time format conforms to the following 24 hour structure:H:m:s (hours:minutes:seconds), where 'h', 'm', or 's' could beeither 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.

bool bSuccess = exporter.ResetData();

Boolean bSuccess = pEnduraExporterNet.ResetData();

EXPORTING VIDEO

This section describes various video export methods and scenarios.

EXPORTING A SINGLE VIDEO CLIP


1. Determine the System Manager’s IP address.

Refer to Automatically Determining the System Manager’s IP Address and Port Number in theDevice and Service Discovery 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 followingparameters:

The path, including filename, of the resultingexported video.

The format changes based on the operating system, forexample, Windows® or Linux®.

The UUID of the camerafrom which to export video

C5617M-G (10 / 2013) 97

The desired resulting videoformat for the export

Refer to the EnduraExporterDefines header for the latestoptions.

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 therecorded video to export inUTC (GMT), not local time,using the format yyyy-mm-ddThh:mm:ss

The ending time of therecorded video to export inUTC (GMT), not local time,using the format yyyy-mm-ddThh:mm:ss

The videoOnly parameter Set to true to export only video, while setting this to false toinclude audio (if it is available). If you want audio to be included,it will be available in either PEF or AVI format.

The UUID of the stream toexport’s audio source, ifseparate from the videosource of the export

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");

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. Formore information, refer to Polling a Video Export.

EXPORTING VIDEO USING A PLAYLIST (PPX)

The playlist (PPX) format supports advanced playback features, including synchronized andsequential (stitched) playback.

For the following play-list example consider the following scenario; There is a system with ninecameras, named “camera_x”, where “x” is the spelling of a number from zero to eight. The files are to

98 C5617M-G (10 / 2013)

play in the following order. Camera_zero from 9:05-9:10, followed by camera_one and camera_threeplayed together in a 2x1 layout both from 9:11 to 9:15. Assume that the video from camera_one for9:13 has been deleted. Following this the cameras play as follows. Camera_four from 9:20 to 9:30,then camera_two, camera_six, and camera_seven from 9:30 to 9:45, assume that camera_two’svideo for 9:31-9:33 has been deleted, and that its video from 9:42 to 9:44 has been deleted. Finally,the last activity is to view camera_eight from 9:42 to 10:00. The following diagram illustrates the viewflow.





3. Call the PlaylistExportInfo method to set up the clip groups that will be played sequentiallyin the order provided.

PlaylistExportInfo contains the following parameters:

DeviceID The UUID of the camera from which to export video

AudioDeviceID The UUID of the stream to export’s audio source, if separatefrom the video source of the export.

StartTime The start time in UTC (GMT), not local time, using the formatyyyy-mm-ddthh:mm:ss

EndTime The end time in UTC (GMT), not local time, using the formatyyyy-mm-ddThh:mm:ss

VideoOnly A boolean indicating if the clip should be exported with videoonly. If false, audio will also be included.

ClipGroup An integer representing the sequential order to play video clips.Up to four clips can be in the same clip group which will play insync within the export player.

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;

ArrayList playlistExportInfo = new ArrayList( num_clips ); playlistExportInfo.Add( new PelcoAPI.PlaylistExportInfoNet( CAMERA_1,

C5617M-G (10 / 2013) 99

"", START_TIME_1, END_TIME_1, false, 1 ) );


exportFolder The path of the folder for exports. (The format changes based onoperating system.)

playlistName The name of the playlist. This should be a simple name with noextensions

playlistExportInfo An array of playlist information for export.

exportInfoCount The number of export info entries

bool bSuccess = exporter.StartExport("D:\\Video\\test123",“PlaylistName”, PlaylistExportInfo, exportInfoCount);

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, refer to 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 withPelco Export Player. Please use Exporting Video Using a Playlist (PPX).

NOTE: Enabling sequential stitching can 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.

• First initialize as many video clip export settings (ExportInfo) instances as you will need. Fordetails on how to set up one set of video clip export settings, refer toSetting Up Overlay Data onVideo to Be Exported .

• At this point determine if you want to associate any overlays to the video clips. If so, create andinitialize any overlays to associate with the video clip to export. In the example excerpt below, fourpreviously created OverlayInfo instances are associated 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 path, including filename, of the resultingexported video.

The format changes based on operating system, for example,Linux or Windows.

100 C5617M-G (10 / 2013)

The desired resulting videoformat for the export.

Refer to the EnduraExporterDefines header for the latestoptions.

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 ExportInfoinstances, containinginstances of OverlayInfo.

The number of ExportInfoinstances, one for each clipto stitch.

Below is a stitched video export 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 = 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 } }

C5617M-G (10 / 2013) 101

bool bSuccess = exporter.StartExport("D:\\Video\\test123.mp4", PelcoAPI::CODEC_ID_MPEG4, exportInfo, 2);

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, refer to Polling a Video Export.

POLLING A VIDEO EXPORT

To poll the status of the video export until it is finished, perform the following:

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); } } }

Int32 clipCounter = 0; while (clipCounter < num_clips) { Int32 status = 0; Int32 temp = 0; while (status < 100 && status != -1) { temp = pEnduraExporterNet.PollStatus(60);

102 C5617M-G (10 / 2013)

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 theStopExport method.

bool bSuccess = exporter.StopExport();

Boolean bSuccess = exporter.StopExport();

EXPORTING A JPEG SNAPSHOT

To create a JPEG snapshot, call the ExportSnapshot method, passing in a .jpeg or .jpg filename, camera uuid, and timestring (use NOW for a live snapshot).

The following is an example of a live snapshot.

bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "NOW");

Boolean bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "NOW");

The following is an example of a recorded snapshot.

bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "2011-11-07T19:30:00");

Boolean bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg", "uuid:00047D01-8994-5370-6563-747261495605", "2011-11-07T19:30:00");

C5617M-G (10 / 2013) 103

Web Service Proxies

WEB SERVICE PROXIES

WARNING


WARNING



Overview

PelcoGSoap is a static linked library generated by gSOAP tools, based on the WSDL files with minormodifications. The PelcoGSoap library provides an interface for SOAP clients to make SOAP calls toPelco 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, ifyou want to use the CameraConfiguration web service, you should include theCameraConfigurationProxy 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 pointURL, refer to Retrieving 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.


104 C5617M-G (10 / 2013)

6. Create a new web service action response instance. In the below example, the software createsan instance of CameraConfiguration’s ResetConfigurationResponse data type.

_CameraConfiguration__ResetConfigurationResponse * pResetConfigurationResponse = soap_new__CameraConfiguration__ResetConfigurationResponse(&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, passingin both the earlier created ResetConfiguration and ResetConfigurationResponseparameters. 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)

C5617M-G (10 / 2013) 105

Discovery

DEVICE AND SERVICE DISCOVERY OVERVIEW

WARNING

Any provided software sample is meant to be a reference implementation focused on educatingdevelopers about Pelco devices. Though there are exceptions, in general Pelco samples are NOTintended for immediate production use without modification.

WARNING



One of the most basic tasks is to programmatically determine what devices and services are availableon your network.

This section contains sample C# and C++ that illustrates how to discover devices and services.Complete C# and C++ sample programs are contained in the following subdirectory where the PelcoSDK is installed: Pelco\API\SampleCode\SystemManagerWrapperSample


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 conveniencefunctions 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 while reading this documentation.

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

Getting Started



106 C5617M-G (10 / 2013)

Change the Working Directory value as appropriate. Assuming that you did not change the defaultinstallation directory for the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Debug.

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

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 automaticallythrough the Pelco SDK as described in Automatically Determining the System Manager’s IPAddress 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

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 sampleproject.

Before performing any of the tasks associated with the System Manager Wrapper, you must initializean instance of it. Then you can use the instance to log in to the System Manager, since most SystemManager 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 Determiningthe System Manager’s IP Address and Port Number.

b) If you already know the System Manager’s IP address, enter it into the SetSMAddress methodas shown below.

PelcoAPI::SystemManagerWrapper sm; int nRet = sm.SetSMAddress((char *) sSMIPAddress);

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 Wrapperinstance’s UserLogin method, passing in the username and password.

int loginId = sm.UserLogin("brian", "pelco");

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 havefinished all System Manager related operations, log out by calling the System Manager Wrapperinstance’s UserLogout method, passing in your login ID as the parameter.

C5617M-G (10 / 2013) 107

For more details on authenticating to a Pelco system, refer to Logging In and Logging Out.

sysMgr.UserLogout(loginId);

sm.UserLogout(loginId);

AUTOMATICALLY DETERMINING THE SYSTEM MANAGER’S IP ADDRESS AND PORT

NUMBER


1. Initialize the System Manager Wrapper by calling its AutoDiscoverSM method to automaticallydetermine 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.

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

// ... 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 Wrapperinstance’s UserLogin method, passing in the username and password.

int loginId = sm.UserLogin("brian", "pelco");

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 ManagerWrapper’s methods.

108 C5617M-G (10 / 2013)

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 asthe parameter.

sysMgr.UserLogout(loginId);

QUERYING AVAILABLE DEVICES FROM THE SYSTEM MANAGER

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 sampleproject.

NOTE: Before proceeding with this entry, it is assumed that you have already completed the stepsoutlined in Creating an IDeviceStorage Class.

The first major task that you need to complete is to query all Pelco devices available on your network.Completing this enables you to access a device’s Unique Device Name (UDN) and many otherdevice-related attributes that are needed for other Pelco SDK related tasks.

1. Initialize the System Manager Wrapper. Refer to Initializing the System Manager Wrapper fordetails.

2. Make a call to the System Manager Wrapper's GetDevices method, passing in the followingparameters:

• Your login ID: This ID is returned after a successful login. Refer to Initializing the SystemManager Wrapper for details.

• The sequence number: This is used to filter results, only returning newly added or changeddevices. GetDevices calls return a new integer value once every few minutes duringsuccessive calls. New values are one larger than the one before, for example, when the 1st callreturns1, the subsequent call returns 2.

• The device type you would like to use to filter the results. Known device types include thefollowing:

• 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 itsproduct line.

• A pointer to your IDeviceStorage implementation.

int seqNum = 0;MyStorage storage; // ... You must define this class ...int loginId = sm.UserLogin("brian", "pelco");sm.GetDevices(loginId, &seqNum, "Camera", &storage);

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 theIDeviceStorage class instance. Refer to Creating an IDeviceStorage Class for further details.

C5617M-G (10 / 2013) 109

4. To query any changes with available devices from the System Manager, use the returnedsequence number value from your last call to the GetDevices method with your next call to thesame method.

This call returns Pelco devices that have changed or are new to the network. Every subsequentcall returns only new changes within your network.

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 ...sm.GetDevices(loginId, &seqNum, "Camera", &storage); // ... seqNum changes here to 2 ...

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 fordetails.)

2. Call the System Manager Wrapper’s GetSystemAttribute method, passing in the followingparameters:

Your login ID This ID is returned after a successful login. (Refer to Initializingthe System Manager Wrapper for details.)

SYS_CFG_TzInfo The time zone attribute’s ID.

sTimezoneInfo A pointer to your time zone variable.

PelcoAPI::xstring sTimezoneInfo;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo", &sTimezoneInfo);

int loginId = sm.UserLogin("brian", "pelco");String sTimeZone = "";Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo", ref sTimeZone);

RETRIEVING THE NETWORK TIME SERVER ADDRESS

110 C5617M-G (10 / 2013)


To your network’s network time server’s IP Address, do the following:




SYS_CFG_NtpAddr The network time server's attribute’s ID.

sNtpAddress A pointer to your NTP address variable.

PelcoAPI::xstring sNtpAddress; int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr", &sNtpAddress);

int loginId = sm.UserLogin("brian", "pelco");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 AvailableDevices from the System Manager, which provides you with UDNs for Pelco devices available onyour network.

To determine your web service's ID, do the following:


2. Call the System Manager Wrapper’s GetServiceID method, passing in the followingparameters:


The target device’s UniqueDevice Name (UDN) value


sServiceType The name of desired web service, such as VideoOutput.

sServiceId The pointer to the variable that will hold the result.

PelcoAPI::xstring sServiceId;int loginId = sm.UserLogin("brian", "pelco");

C5617M-G (10 / 2013) 111

bool bSuccess = sm.GetServiceID(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605","VideoOutput", &sServiceId);

RETRIEVING A SPECIFIC WEB SERVICE’S CONTROL URL



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 thefollowing parameters:




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 webservice control URL.

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

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



112 C5617M-G (10 / 2013)

To determine to which NVR or NSM your camera is connected to record, complete the followingsteps:


2. Call the System Manager Wrapper’s GetDeviceAttributeValue method, passing in thefollowing parameters:




SYS_NvrAssoc The NVR association attribute’s ID.

sNvr The pointer to the variable that will hold the result.

PelcoAPI::xstring sNvr;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc",&sNvr);

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 NAME



To determine a device’s friendly name, you can simply parse through the results of a GetDevicesmethod call, which includes both the device UDN and its accompanying attributes. Alternatively, youcan complete the following steps:






SYS_UpnpFriendlyName The attribute name.

C5617M-G (10 / 2013) 113

sFriendlyName The pointer to the variable that will hold the result.

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 asmanufacturer, model name, and so on, in XML format. To get the location of a specific device’s DDF,do the following:






SYS_UpnpDevDescUrl The attribute ID.

sDdfUrl The pointer to the variable that will hold the result.

PelcoAPI::xstring sDdfUrl;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpDevDescUrl", &sDdfUrl);

String sDdfUrl = “”;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:


114 C5617M-G (10 / 2013)

2. Call the System Manager Wrapper’s GetServiceInfoSync method, passing in the followingparameters:


The sequence number This has the same function as other Pelco query methods, inthat it can help limit the results to only new or changed items.This makes sense for querying devices on a network. However,a device’s available web services does not change very often,if ever, without a new firmware update. Therefore, this valueshould almost always be a 0.



storage The pointer to the variable that will hold the result.

int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm. GetServiceInfoSync(loginId, 0, "uuid:00047D01-4CA5-5370-6563-747261495605", storage);

int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm. GetServiceInfoSync(loginId, 0,"uuid:00047D01-4CA5-5370-6563-747261495605", storage);

RETRIEVING DEVICE ATTRIBUTES



Device attributes are values that describe the device in some way such as its model number or itsmodel name. The following are the most common device attributes:

SYS_UpnpPelcoDeviceUdn A Pelco device’s Unique Device Name (UDN); a special deviceidentifier for networks.

SYS_UpnpFriendlyName A more human readable version of the device’s name. A separateattribute, friendlyName, can be present. Users can customize thisattribute. When present, friendlyName should be used in place ofSYS_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_UpnpModelDescriptionA more detailed description of the device.

SYS_UpnpManufacturerUrl The device manufacturer’s website.

C5617M-G (10 / 2013) 115

SYS_UpnpModelName The device’s model name.

This outlines the steps needed to return a specific device attribute:






The name of the device attribute to query.

The pointer to the variable that will hold the result.

PelcoAPI::xstring sModelNumber;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpModelNumber", &sModelNumber);

String sModelNumber = "";int loginId = sm.UserLogin("brian", "pelco");Boolean bSuccess = sm.GetDeviceAttributeValue(loginId,"uuid:00047D01-4CA5-5370-6563-747261495605","SYS_UpnpModelNumber", ref sModelNumber);

RETRIEVING A SYSTEM MANAGER’S ATTRIBUTE


A System Manager’s attributes are similar to a generic Pelco device’s attributes, except in most casesa System Manager attribute is exclusive to Pelco System Managers. If you aren’t familiar with deviceattributes, System Manager attributes are simply values that describe the System Manager in someway such as its current time zone or its current security mode. The following are the more commonSystem Manager attributes:

SYS_CFG_NtpAddr This value is used to indicate the location at which the NTP server (ifany) 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 iscomma delimited (without whitespace). The following describeseach 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

116 C5617M-G (10 / 2013)

the time zone and nothing will have to be done to support daylightsavings. If the value is nonzero, the time zone does support daylightsavings time. In this case, if the value is negative, the time value isbeing used to indicate the time to turn off daylight savings time. Ifthe value is positive, the value is being used to indicate the time atwhich daylight savings time is to be turned on.

DST Offset This number is the number of minutes to adjust the time whendaylight savings time is in affect. The offset should be added to theGMT time after adding the GMT offset (refer to GMT Offset).

GMT Offset This value indicate the number of minutes to adjust the GMT time toget the local time (this is the minutes "west" of the GMT). To get thecurrent local time, simply subtract this number of minutes from thecurrent GMT time.

SYS_CFG_UPNP_RENEWAL The UPnP renewal value in seconds. The default setting is 1800seconds (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:




systemAttribute The name of the System Manager attribute. Parameter of typepointer to xstring, value SYS_CFG_TzInfo.

A pointer to the variable thatwill hold the result.

int iUpnpRenewal;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL", &iUpnpRenewal);

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




C5617M-G (10 / 2013) 117

2. Call the System Manager Wrapper’s GetDeviceServiceAttribute method, passing in thefollowing parameters:




The target web service’s ID Refer to Retrieving a Web Service’s ID for details.

The ID of the web serviceattribute

For example, SYS_UpnpControlUrl orSYS_UpnpEventSubUrl

A pointer to the variable that will store the result.

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

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 andMyStorage.cpp files (for C++) or DeviceInformation.cs file (for C#), which belongs to theSystem Manager Wrapper sample project.

What is the IDeviceStorageNet class? An IDeviceStorageNet is simply an interface thatparses XML responses from the System Manager and stores the resulting device data from the XMLresponse internally. Users need an implementation of this interface if they want to manage devicedata using the System Manager Wrapper.

1. Ensure that the IDeviceStorageNet class implements the following methods:

• virtual bool AddDevice(const char* sUDN, const char* sAttributes): Thismethod adds a new 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 existingdevice within IDeviceStorageNet.

• The device’s Unique Device Name (UDN)• virtual bool UpdateDevice(const char* sUDN, const char* sAttributes)

118 C5617M-G (10 / 2013)

The System Manager Wrapper will use these methods every time you call its GetDevicesmethod, which in turn will update your IDeviceStorage instance contents.

#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

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 ofIDeviceStorage called MyStorage.

MyStorage is a stub class. It does not implement anything that is essential for production usage,such as parsing the System Manager’s XML response data (attributes). Nor does it associate thedevice UDN/attribute XML pairs into any constructs. Those exercises are left to the user.

C5617M-G (10 / 2013) 119

LoggingLogging is specific to Endura, and is configurable.

1. To configure logging, run the LoggingSetup application in the C:\Program Files\Pelco\API\Logging folder.

2. Select the items that you want to log, as well as the folder where the logs should be stored and themax logfile size.

3. Click Set to save the settings.

NOTE: Logging should be run by an administrative account, because other users do not havewrite 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\Logging folder. Click the View Log File button.

NOTE: The maximum log size is 50MB. Any settings over that value will be reset back to thedefault 50MB restriction. Usually, logging should be off (no items checked) unless Pelco technicalsupport 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 notselected.

Info The next level of severity below Error.

Verbose Logs actions that occur often and should normally not be loggedbecause they fill up the logfile quickly.

120 C5617M-G (10 / 2013)

Product CompatibilityThe following table shows the compatibility of the Pelco SDK with Pelco products.

Product EventArbiter

EventManager

Exporter Meta-dataParser

Pelco APIViewer

PTZControlWrapper

SMWrapper

DX 4700HD /DX4800 HDVideoRecorders(functionalitywill onlywork withDX versionthatsupportsPelco API)

Yes Yes No No Yes Yes Yes

DSSRV(functionalitywill onlywork withDS versionthatsupportsPelco API)

Yes Yes No No Yes Yes Yes

DVR5100 Yes Yes Yes Yes Yes Y5 Yes

EnduraExpress

Yes Yes6 Yes6 Yes Yes No Yes6

IP110 Yes Yes6 No Yes Yes No Yes6

IP3701 Yes Yes6 No Yes Yes No Yes6

NET5301R Yes Yes6 No Yes Yes No Yes6

NET5402R-HD

Yes Yes6 No Yes Yes No Yes6

NET5301T Yes Yes6 No Yes Yes Yes5 Yes6

NET5308T Yes Yes6 No Yes Yes Yes5 Yes6

NET5301T-I

Yes Yes6 No Yes Yes Yes5 Yes6

NET5400T-I

Yes Yes6 No Yes Yes Yes5 Yes6

NSM5200 Yes Yes6 Yes6 Yes Yes No Yes6

Sarix Yes Yes6 No Yes Yes No Yes6

SpectraHD 720p

Yes Yes6 No Yes Yes Yes Yes6

5 Active only if the attached IP camera is PTZ capable.6 Active only if an active System Manager is available on the network. Endura Express contains a built-in System

Manager, and therefore no additional System Manager is required.

C5617M-G (10 / 2013) 121

SpectraHD 1080p


Spectra IVIP


SpectraMini


Esprit IP Yes Yes6 No Yes Yes Yes Yes6

SM5000 Yes Yes No Yes No No Yes

SM5200 Yes Yes No Yes No No Yes

122 C5617M-G (10 / 2013)

EnduraIn 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 theorigination, 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 ofEndura. It is responsible for the following:

• Managing devices such as cameras, decoders, and NVRs, including administering rights andprivileges

• 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 APIis 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 webservices. These web services adhere to the SOAP standard. (For more details on SOAP, please referto the following http://en.wikipedia.org/wiki/SOAP.) It is beyond the scope of this documentation tofully 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 informationon all Endura devices. How does the System Manager collect all of this information?

1. The System Manager constantly provides a broadcast of its location on the Endura Network. Oncea device comes on line, it will listen for this broadcast. When the new device finds the SM, it willthen register itself to the System Manager.


C5617M-G (10 / 2013) 123

2. At some point the System Manager will query the device’s available web services and itsattributes, using a variety of sources including the UPnP Device Description File (DDF). DDFs arefiles containing device attributes in XML format.

3. After the initial query, the System Manager will periodically update the device’s status. To beconsidered on line, 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 theSM 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 later versions of Endura network deployments, the first option is the default. Users can enablethe System Manager to act as an intermediary by enabling its EventArbiter web service (not tobe confused with the Event Arbiter Library). The EventArbiter web service is used for receivingGENA events from devices within an Endura network. The Event Arbiter provides two ways forsubscribing to events:

• Through control URLs• By subscribing to events with event URIs provided

Figure 1: Subscribing to Events through Control URLs

124 C5617M-G (10 / 2013)

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? TheSystem Manager can help manage all event related network traffic, ensuring that an Endura networknever gets overwhelmed by eventing network traffic.

Video Exports

Currently the Exporter library requires a System Manager to be present to function. How does itwork? The Exporter client sends its request for video clips to export with a timestamp range filter tothe System Manager; that is, it wants clips that fall within a starting date time and an ending datetime. The System Manager will then query all available NSMs for clips that meet both the startingtimestamp and the ending timestamp. Specifically, there can 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 conveniencemethods and utilities. It protects the user from all of the potentially overwhelming and complicateddetails of Endura SOAP web services. Of course users are still free to directly use Endura webservices. However Pelco has found that many of our customers enjoy the convenience and ease ofuse that the Pelco API SDK provides.

C5617M-G (10 / 2013) 125

General Event MessagesLoggableEvent

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 eventmessage descriptions below.

<complexType name="LoggableEventParameters"> <sequence> <element minOccurs="0" maxOccurs="unbounded" name="parameter" type="tns:LoggableEventParameter"/> </sequence></complexType>

parameter A LoggableEventParameter data type.

LoggableEventParameter

This represents an event-related parameter. For further details, refer to the event messagedescriptions 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"/>

126 C5617M-G (10 / 2013)

</sequence></complexType>

paramId The parameter's unique identifier.

name The parameter's name.

value The parameter's value.

type The parameter's type identifier.

C5617M-G (10 / 2013) 127

Hardware Diagnostics Event Messages

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 to394af82c-2b05-4df8-b2a6-2caed9ad4fae

objId The event's unique database identifier. The value must be 20180

current The current state of the button. Possible values are

1 for BUTTON_CONFIG The button is in "Configurationmode".

2 for BUTTON_REBOOT The button is in "Reboot system".

3 for BUTTON_RESET The button is in "Resetconfiguration".

4 for BUTTON_NORMAL The button currently does not havea state.

previous The previous state of the button. For possible values, refer tocurrent.

<pdDiagnostic> <objGuid>394af82c-2b05-4df8-b2a6-2caed9ad4fae</objGuid> <objId>20180</objId> <current>1</current> <previous>3</previous> </pdDiagnostic>

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>

128 C5617M-G (10 / 2013)

<parameters></parameters>

DRIVERFAILURE (20150)

A DriverFailure PdDiagnostic object is only sent when a device's driver fails, so aLoggableEvent object is used to set the correct major, minor, type, and reason. This is typicallyused for multichannel 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 to94b6d2d3-c68e-4b13-974a-08f69f50cb67


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



<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>5</type> <reason>1</reason> <parameters></parameters>

FANS (20020)

Any device with any fans having a changed state will have a LoggableEvent fired.

PdDiagnostic

C5617M-G (10 / 2013) 129


<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 to31e41907-53be-4f57-8ae2-a56c12d98d0e


states 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. FAN_OK -- The fan is operating normally.2. FAN_FAILED -- The fan has failed.3. 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.

prev The previous state identifier. This has the same possible values ascur.

<pdDiagnostic> <objGuid>31e41907-53be-4f57-8ae2-a56c12d98d0e</objGuid> <objId>20220</objId> <states> <state>

130 C5617M-G (10 / 2013)

<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 astate change. Set the 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>



states A HardDrivesStates data type.

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

C5617M-G (10 / 2013) 131


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. HDS_READY -- Indicates that the hard disk is currently in use.

NOTE: This could indicate a problem if the disk is known to becurrently NOT in use.

2. HDS_ONLINE -- Indicates that a disk is on line and currentlybeing used.

3. HDS_FAILED -- Indicates that a disk has failed.4. HDS_HOTSPARE -- Indicates that a disk is currently being used

as a 'hot spare' within the array.5. HDS_REBUILD -- Indicates that a disk is currently being rebuilt.6. HDS_NONE -- Indicates that there is currently no hard drive

connected, and there is room for a hard drive.7. HDS_UNKNOWN -- Indicates that the hard drive's state is

currently unknown. This typically means that the hard drive hasyet to register any state.


prev The previous state identifier. This has the same possible values ascur.

<pdDiagnostic> <objGuid>8dda89bd-3c2c-4a35-aad4-1256cb5e1d27</objGuid> <objId>20060</objId> <states> <state> <cur>1</cur> <prev>2</prev> </state> <state> <cur>1</cur> <prev>1</prev> </state> <state> <cur>1</cur> <prev>1</prev> </state> </states> </pdDiagnostic>


132 C5617M-G (10 / 2013)


<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 aLoggableEvent object can be 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 toa44945e0-fa54-4fb0-a614-2e71886c508f


mode The mode of the shutdown.

<pdDiagnostic> <objGuid>a44945e0-fa54-4fb0-a614-2e71886c508f</objGuid> <objId>20070</objId> <mode>4</mode> </pdDiagnostic>



<deviceUdn>uuid:AK-2</deviceUdn> <deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn> <serviceUrn></serviceUrn> <logId></logId> <major>7</major>

C5617M-G (10 / 2013) 133

<minor>0</minor> <type>4</type> <reason>4</reason> <parameters></parameters>

LINKSPEED (20200)

This event triggers when the link speed changes. When this occurs, set the correct major, minor,type, and reason for LoggableEvent. The current LinkSpeed is sent as a parameter with theLoggableEvent 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 tob9359885-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> <parameters> <param> <paramId>5</paramId> <name>CurrentLinkSpeed</name> <value>10</value> <type>1</type> </param>

134 C5617M-G (10 / 2013)

</parameters>

POWERSUPPLY (20120)

A PowerSupplyPdDiagnostic object is sent when a power supply encounters a problem so that aLoggableEvent 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 operatingproperly; not in an alarm state.

1 Problems with the power supply; inalarm state.

<pdDiagnostic> <objGuid>26f051aa-009b-4a5d-ab20-09b064a07a52</objGuid> <objId>20120</objId> <inAlarm></inAlarm> </pdDiagnostic>




UPS (20170)

This event triggers if a UPS either fails or runs out of power.

PdDiagnostic

C5617M-G (10 / 2013) 135


<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 bee746c2c8-0b97-402e-abc3-c784890c8d99


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>

136 C5617M-G (10 / 2013)

Software Diagnostics Event Messages

DATALOSS 20040

When this is triggered by a data loss, set the correct major, minor, type, reason for theLoggableEvent.

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 to94b6d2d3-c68e-4b13-974a-08f69f50cb67

objId The event's unique database identifier. The value must be: 20040

<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



INPUTSTREAMS 20160

For each stream entry that has its state changed from previous state, the software sends out aloggable 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"/>

C5617M-G (10 / 2013) 137




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

id The entry's unique identifier, for example: 2

138 C5617M-G (10 / 2013)

mediaType A media type identifier, for example: 0

hardwareId A hardware identifier, for example: hwidv1

stateCur The current state identifier. Possible values are

1. ISS_RECORDING -- Currently receiving a stream and it is beingrecorded.

2. ISS_RECORD_ERROR -- Currently receiving a stream, but it isunable to be recorded due to an error.

3. ISS_RECEIVING -- Currently receiving a stream.4. ISS_RECEIVE_ERROR -- Unable to receive a stream.5. ISS_MISSING -- Expecting a stream but there is no available

stream. In analog inputs, this means the device is unable todetect a connection.

6. ISS_UNKNOWN -- The state of the stream is currently unknown.This stream does not have an initial state registered.


statePrev The previous state identifier. Refer to stateCur for possible validvalues.

PACKETLOSS 20080

This event is fired when there is data loss during video data writing. Sets the appropriate major,minor, type, and reason 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 The event's Universally Unique Identifier. The value must be:ddfa09d6-64f1-4b39-a7e7-de0c5f7780cc


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>

C5617M-G (10 / 2013) 139

<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 SEBchanges. Set the state of 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


entries An SEBsEntries data type.

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>

140 C5617M-G (10 / 2013)

stateCur The current state identifier.

statePrev The previous state identifier. Refer to stateCur for valid possiblevalues.

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> <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, andreason is set in the Loggable event.

PdDiagnostic

This is the data that subscribers receive when the event triggers.

<complexType name="StorageFullPdDiagnostic"><sequence>

C5617M-G (10 / 2013) 141

<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


inAlarm This represents whether or not a device is in a problem state.Possible values are

• 0 -- Storage is not full, not in an alarm state.• 1 -- Storage is full, 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.

<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>13</type> <reason>0</reason>

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


142 C5617M-G (10 / 2013)

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° to 50° Celsius. This verifies if the current temperature is belowminimum or above maximum threshold, and then determines whether to send Loggable Events,with reason set to either LOW or HIGH accordingly.

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


C5617M-G (10 / 2013) 143

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>



<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>3</type> <reason>0</reason> <parameters> <param> <paramId>1</paramId> <name>CurrentTemperature</name> <value>5</value> <type>1</type> </param> </parameters>

144 C5617M-G (10 / 2013)

Video Streaming and Exporting PerformanceThis section shows the maximum number of supported streams for video streaming and videoexporting operations using the Pelco SDK.

Video streaming and exporting performance testing was conducted on two separate computers.

• One computer met the minimum hardware and network requirements shown in the EnduraNetworking Guide; this is called the 'minimum specification computer'.

• The second computer exceeded the requirements; this computer is called the 'high-end computer'.

Both sets of test results are presented in this section for comparison. Because there are manyhardware configurations, conclusions should not be drawn about the performance of any particularcomputer.

The following describes the specifications of both the minimum specification computer and the high-end computer that were subjected to the testing.

Table 14: Specifications of test computers

Minimum specificationcomputer

High-end computer

Operating System Windows Server 2008 R2 64-bit Windows XP SP3 32-bit

CPU 2.4 GHz Intel Core 2 Duo 2.8 GHz Intel Xeon (Quad Core)

RAM 2GB 3GB

HDD SATA HDD SATA HDD

Graphics card nVidia Quadro FX 550 PCIExpress-128 MB

nVidia Quadro FX 580 PCIExpress-512 MB

• Video streaming and video exporting are CPU intensive operations, and were tested using variousscenarios.

• Event monitoring and normal operations of the Pelco SDK are not CPU intensive and were notmeasured.

• For the results shown in the following tables, each computer used no more than 60% of theavailable CPU capacity. This allows for other processes executing concurrently during the testoperations.

• Additional processes, especially CPU and GPU intensive processes, can decrease theperformance of the Pelco SDK applications.

NOTE:

• The test video streams were 30 IPS.• Scene depicted is of medium complexity (the scene contained some motion).

Maximum Number of Concurrent Video Streams (Minimum SpecificationComputer)

The maximum number of concurrent video streams supported by a computer with the minimumspecifications are shown in the following table.

Stream Transport

Stream Type RTP Live RTP Playback RTSP Live RTSP Playback

MPEG-4, 1SIF(352x240)

10 10 11 4

C5617M-G (10 / 2013) 145

MPEG-4, 4SIF(704x480)

3 5 4 4

H.264, 1SIF(352x240)

4 10 8 4

H.264, 4SIF(704x480)

3 5 3 3

H.264, 720P(1280x720)

1 1 1 1

H.264, 1080P(1920x1080)

1 1 1 1

Maximum Number of Concurrent Video Streams (High-End Computer)

The maximum number of streams supported by a high-end computer that exceeds the minimumspecifications are shown in the following table.

Stream Transport

Stream Type RTP Live RTP Playback RTSP Live RTSP Playback

MPEG-4, 1SIF(352x240)

32 32 16 21

MPEG-4, 4SIF(704x480)

32 22 10 10

H.264, 1SIF(352x240)

32 20 12 12

H.264, 4SIF(704x480)

32 20 6 6

H.264, 720P(1280x720)

20 7 3 3

H.264, 1080P(1920x1080)

3 4 3 2

Maximum Number of Concurrent Export Streams

The exported video streams were 30 minutes in duration for single streams and 15 minutes for dual-stitched streams. The streams were PEF format, 30 IPS, and depicted a scene of medium complexity(contained some motion).

Maximum Number of Export Streams From a Minimum Specification Computer

The maximum number of concurrent export streams supported by a computer with the minimumspecifications are shown in the following table.

Export Type

Stream Type Single Export (nooverlays)

Single Export(overlays)

Two-Clip Export(stitched, overlays)

MPEG-4, 1SIF(352x240)

6 1 1

MPEG-4, 4SIF(704x480)

9 1 1

H.264, 1SIF (352x240) 5 1 1

146 C5617M-G (10 / 2013)

H.264, 4SIF (704x480) 6 1 1

H.264, 720P(1280x720)

8 1 1

H.264, 1080P(1920x1080)

10 1 1

Maximum Number of Export Streams From a High-End Computer

The maximum number of export streams supported by a high-end computer that exceeds theminimum specifications are shown in the following table.

Export Type

Stream Type Single Export (overlays) Two-Clip Export (stitched,overlays)

MPEG-4, 1SIF (352x240) 4 5

MPEG-4, 4SIF (704x480) 3 4

H.264, 1SIF (352x240) 4 2

H.264, 4SIF (704x480) 3 2

H.264, 720P (1280x720) 2 1

H.264, 1080P (1920x1080) 2 1

C5617M-G (10 / 2013) 147

Glossary

AActiveX® : ActiveX® ActiveX® is an integration platform that provides developers, users, and Webproducers a fast and easy way to create integrated programs and content for Microsoft based Internetand Intranet software. For more information, refer to http://support.microsoft.com/kb/154544

Advertisement (UPnP) : In a UPnP network, advertisement is the act of one device presenting itsservices for another device to use. In Endura, the UPnP advertisement startup and renew intervalsare 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 physicalalarm 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 securitystaff.

Alarm relay : The alarm relay is the relay used to output an alarm condition based on a specificsystem or event message criteria.

Autofocus : Autofocus is the ability of the lens to remain in focus during zoom-in, zoom-out, andmotion functions.

Bbit : Abbreviation for binary digit; the smallest unit of information a computer can use. A bit is eitherone or zero (a high or low voltage state).

bit rate : Bit rate is the number of bits that are transferred between devices in a specified amount oftime, typically one second.

Brightness : In NTSC and PAL video signals, the brightness information at any particular instantin a picture is conveyed by the corresponding instantaneous direct current level of active video.Brightness control should be adjusted so that the black picture content displays as true black on yourmonitor.

bps : Bits 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 deviceto every device on the network. When broadcasting, it is not possible to control or specify whichdevices 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 is large enough to hold one character (like an “A”) or an unsigned integer from0 to 255.

C

http://support.microsoft.com/kb/154544

148 C5617M-G (10 / 2013)

Camera group : In an Endura system, a camera group is a collection of cameras associated witheach other as part of the setup process. Camera groups can be used in filtering cameras displayed inthe Nav window, as well as those selected for schedules, scripts, or permissions.

Coaxitron :

Coaxitron is the Pelco protocol that uses “up-the-coax” technology. Commands to control pan/tiltdevices are transmitted during the vertical blanking interval of the video signal. Instead of separatewiring for control commands and video, Coaxitron uses the coaxial cable for both video and control.

Standard: This earlier technology uses 15 bits to send a command.

Extended: This later technology uses 32 bits to send a command.

codec : codec is an acronym for compression/decompression. This term is commonly used in thecontext of multimedia compression and decompression, such as video or audio.

Common Intermediate Format (CIF) :

A standard video and digital image size. Refer to SIF for NTSC resolutions.

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 darkestand the brightest parts of an image. Once brightness is set correctly, contrast should be set forcomfortable viewing brightness.

DD1 : D1 is a digital video format developed by Society of Motion Picture and Television Engineers(SMPTE). The D1 format resolution 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 digitalvideo streams back into analog output for viewing on an analog video monitor, S-video monitor, orVGA monitor.

Decoding : Decoding is the opposite of encoding: decompressing a compressed digital image andthen turning it back into an analog signal.

Device : A device is a piece of hardware (camera, alarm, DVR, NVR, storage expansion box) that ispart of a network.

Device ID : A device ID is a unique identifier for an individual device on a network.

EEncoder : In an Endura system, the encoder is a high-performance MPEG-4 device that takesanalog video signals through a standard BNC coaxial cable and digitizes, compresses, signs,and packetizes them for the network. It also provides an interface for relays, alarms, and audioconnections.

C5617M-G (10 / 2013) 149

Encoding : Encoding is the process of taking an analog signal and converting it to a digital format (Ato D conversion). Compression is applied at this point in the process.

FFirmware : Firmware is a software process that is embedded in a hardware platform that instructsthe hardware unit how to behave and what action to perform.

Focus : Focus means to adjust a lens to allow objects at various distances from the camera to besharply defined.

Frame rate : The frame rate is the number of frames or images that are captured, stored, projected,or displayed per second.

GGamma : Gamma is the correction of the linear response of a camera to compensate for thenonlinear response of a monitor’s phosphor screen. It is measured with the exponential value of thecurve describing the nonlinearity. A typical monochrome monitor gamma is 2.2, and a camera needsto be set to the inverse value of 2.2 (which is 0.45) for the overall system to respond linearly (that is,unity).

HH.264 : Developed by the ITU-T Video Coding Experts Group (VCEG), H.264 is a low-bit-ratecompressed video format standard.

Hue : Hue is one of the characteristics that distinguishes one color from another. Hue defines coloron the basis of its position in the spectrum, that is, whether red, blue, green or yellow, and so forth.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 at any particular point in the picture is conveyedby the corresponding instantaneous phase of the active video subcarrier.

II-frame : In a compressed digital image, I-frames (intraframes) are the frames that are compressedindependently of the other frames in the sequence.

IP : Internet Protocol. IP is the main method of transmitting data across the Internet.

IP address : (static and DHCP) The IP address identifies a particular computer on a network toother computers. An IP address is similar to your home address. In a neighborhood, each househas a unique address; on a network each computer must have a unique address. An IP addressis 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 staticaddress is assigned when someone physically connects to a computer and defines the IP addressfor that computer. A static address does not change unless someone physically changes it. A DHCP(Dynamic Host Configuration Protocol) address is assigned dynamically from a server that containsa pool of addresses. The server leases the computer one of the available addresses for a specifiedamount of time. Once the time has expired, the computer renews the lease or requests a new IPaddress.

IP camera : An IP camera is a digital video camera that outputs IP packets over Ethernet cabling. AnIP camera can use TCP protocol, as well as UDP or RTP.

150 C5617M-G (10 / 2013)

IP header : An IP packet can be divided into two main parts: the payload and the header. Theheader is the part of the packet that contains the routing information, and is is comprised of manyparts. The header contains all IP and MAC addressing information. The header is the only part of thepacket that a router examines when trying to determine where to send a packet.

Iris : The iris is a means of controlling the size of a lens aperture and therefore the amount of lightpassing through the lens.

Mmarshalling: Marshalling is synonymous with serialization.

MPEG-4 : Developed by Moving Picture Experts Group (MPEG), MPEG-4 expands the MPEG-1specification to support AV ‘objects’, 3D content, low bit-rate encoding, and Digital Right Management(DRM).

Multicast : A single device sends information across a network and that stream is received by alllistening 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 subnet mask of 255.255.0.0. Each multicast transmitting devicesends a data stream to an address from the above range. Any device on the network can then listenfor transmissions to that IP address and receive the stream. Multicast offers a reduction of bandwidthconsumption over the unicast and broadcast delivery methods. Multicast also offers control overwhich devices on a network can receive a multicast stream. In an Endura system, only Enduradevices can receive Endura multicast streams. Multicast traffic is not routable across the Internetwithout a specially reserved address or encapsulation.

Multicast server : A multicast server is any server that takes a unicast transmission on behalf of aclient and converts it to a multicast transmission on the network.

NNamespace : Namespace is an identifier that denotes a group of names. It is used to preventresource identifier conflicts.

Network Time Protocol (NTP) : NTP is a protocol designed to synchronize the clocks of computersover a network. On systems that have an NTP server, you can use the WS5050 to configure the NTPsettings (NTP server IP and renew interval). By default, time and date information is included withvideo streams and other device data. The software relies on the PC system clock for other neededtime information.

National Television System Committee (NTSC) : NTSC developed the U.S. color TVspecifications. It specifies 525 lines/screen. It also specifies 59.94 fields per second, although mostpeople refer to this frame rate as 30 frames per second. NTSC now describes the American systemof 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 andadvanced software for managing pooled storage of recorded video and audio streams.

PPhase Alternation by Line (PAL) : PAL is the European (50 Hz) color TV standard. It is used bymost countries outside the US. It specifies 625 lines/screen, and 25 frames per second.

C5617M-G (10 / 2013) 151

Parity : Parity is a method of checking the accuracy of data to identify whether the bits being movedarrived successfully. Parity bit checking can be based on odd or even bits. No parity means that aparity bit is not transmitted or checked.

P-frame : In a compressed digital image, a P-frame (predicted frame) is a frame calculated based onthe change from one frame to the next. An area of the display that does not change from one frame tothe next does not need to be contained in the P-frame. If an area of the display does not change butdoes move on the screen, only the vector describing this movement is contained in the P-frame. Thisallows a reduction in overall file size.

PIN : 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 seven bytes to send a command.

M Pelco protocol for communicating with M devices (KBD960/KBR960 keyboards, ALM2064 alarminterface units, and REL2064 relay interface units).

P Pelco protocol that uses a variable number of bytes to send a command. Eight bytes are used tosend commands to dome systems.

RRelay group : A relay group is a defined set of relays acting in a coordinated pattern.

Remote Procedure Calls (RPCs) : RPC is a protocol that allows software running on one host tocause other software to be run on another host.

Real-time Transport Protocol (RTP) : A protocol that uses a standardized packet format fordelivering data over networks.

Real Time Streaming Protocol (RTSP) : A protocol for streaming data, which allows clients toremotely control the server streaming the data.

SSaturation : Saturation is the intensity of the colors in the active picture: the amount by whichthe 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 white reduces saturation. In NTSC and PAL videosignals, the color saturation at any particular instant in the picture is conveyed by the correspondinginstantaneous 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 computersconnected to it through a network.

Service : Service is the ability of a device within the Endura system to perform such functions aspan/tilt/zoom, record video, and playback video. When a device comes online, these services areautomatically advertised to other devices on the network. For a user to access these services, theuser must be assigned a role with the proper permissions.

152 C5617M-G (10 / 2013)

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.Refer to CIF for PAL resolutions.

System Manager (SM) : A piece of software that authenticates devices on the Endura network. Thissoftware runs on an Endura DVR or NVR or as a standalone device.

TTCP/IP connection : Transmission Control Protocol/Internet Protocol. TCP/IP is the standardway of communicating over a network that ensures all devices on a network can communicate andinformation is passed without any errors.

UUDN: Universal Device Number.

UDP : User Data-gram Protocol is a connectionless protocol that, like TCP, runs on top of IPnetworks. Unlike TCP/IP, UDP/IP provides very few error recovery services, offering instead adirect way to send and receive data-grams over an IP network. It is used primarily for broadcastingmessages over a network.

UID : Universal Identification Number.

Unicast : The standard method to transport IP traffic. In a unicast transmission, information is sentfrom one computer directly to another computer on the network.

UPnP : UPnP is a family of networking protocols used to create a “hands off” network. In a UniversalPlug and Play network, objects are plugged into a network and automatically recognized andconfigured. All IP addresses in a UPnP network are assigned dynamically through DHCP. If DHCPbecomes unavailable in a UPnP network, devices will default to AutoIP. Endura devices use theUPnP process when plugged into an Endura network.

Uniform Resource Identifier (URI) : URI is used to identify a resource over a network.

Uniform Resource Name (URN) : A URN identifies, or more specifically, names a resource within anamespace.

VVarifocal :

Varifocal refers to a lens with a variable focal length. Varifocal lenses are low cost zoom lenses thatcan be adjusted (zoomed) over a range of focal lengths. These lenses are much lower in cost thannormal zoom lenses because they have fewer elements in them.

Disadvantage: Unlike a zoom lens, a varifocal lens does not maintain focus when zoomed. It ispractical only for use with cameras where the zoom is set once at installation.

Advantage: The installer can adjust a varifocal lens for optimum field of view without changing thelens.

W

C5617M-G (10 / 2013) 153

WSDL : Web Services Description Languages (WSDLs).

Pelco by Schneider Electric 3500 Pelco Way Clovis, California 93612-5699 United StatesUSA & Canada Tel (800) 289-9100 Fax (800) 289-9150

International Tel +1 (559) 292-1981 Fax +1 (559) 348-1120www.pelco.com www.pelco.com/community

For information about Pelco’s product warranty and thereto related information, refer to www.pelco.com/warranty.