Pelco SDK 2.0 Programmers Guide for C++

Pelco SDK 2.0 Programmers Guide for C++ Doc Rev 1.4.89

Pelco 3500 Pelco Way Clovis, CA 93612-5699 T 800-289-9100 F 925-468-1550 http://pelco.com

http://pelco.com

http://pelco.com

Table of Contents

Updates xii

Overview 1

Who is this for? 1

How is this document organized? 1

What is the rationale for the format of this document? 1

Introduction 1

What does the Pelco SDK contain? 1

General Requirements 2

Hardware 2

Software 3

Initial Installation 3

Distribution 4

Displaying and Controlling Video Streams 5

Overview 5

Where does the Pelco SDK fit? 5

Getting Started 6

Registering the ActiveX Control 6

Pelco

Pelco SDK i

Setting up the Working Directory 7

What’s Ahead 8

Initializing the Pelco API Viewer 8

Opening, Playing, and Displaying a Live RTP Stream 9

Opening, Playing, and Displaying a Playback RTP Stream 10

Opening, Playing, and Displaying an RTSP Stream 11

Forward Playback of the Stream 12

Reverse Playback of the Stream 13

Pausing the Playback Stream 13

Resuming a Stream from a Paused State 14

Stopping the Stream 14

Taking a Snapshot of the Current Video Frame 15

Panning and Tilting 16

Overview 16


Getting Started 17

Initializing the PTZ Control Wrapper 20

Continuous Panning 20

Continuous Tilting 21

Continuous Diagonal Movement 21

Panning to a Specific Position 22

Tilting to a Specific Position 22

Pelco

Pelco SDK ii

Moving to a Specific Position 23

Getting the Camera’s Current Position 23

Magnification (Zoom), Focus, and Iris Control 24

Overview 24


Getting Started 25

Managing the Magnification (Zoom) Value 28

Managing the Focus Value 28

Iris Control 29

Scripting 31

Overview 31

Preset 31

Pattern 32

Normal Script 32

Getting Started 32

Creating a Preset 34

Updating an Existing Preset 35

Creating a Pattern 35

Updating an Existing Pattern 36

Executing an Existing Script 36

Stopping a Script Currently Being Executed 36

Events and Alarms 37

Pelco

Pelco SDK iii

Overview 37


Event Arbiter Library 38

Event Manager 38

Event Arbiter Library vs Event Manager 39

Getting Started 39

What’s Ahead 41

Creating an Event Agent 42

Returning the Event Subscription URL 42

Initializing the Event Arbiter Library 43

Initializing the Event Manager 44

Device or Service Specific Subscriptions 44

Using the Event Arbiter Library to subscribe to a specific device’s particular web service using the

device’s IP address 45

Using the Event Arbiter Library to subscribe to a specific device’s particular web service using the

event subscription URL 45

Using the Event Arbiter Library to subscribe to all instances of a particular web service 46

Using the Event Arbiter Library to unsubscribe from a service 46

Mass Subscriptions by Category 47

Using the Event Manager to subscribe to all web services under specific category 47

Using the Event Manager to unsubscribe from all web services within a category 48

Handling Incoming Events 48

Extracting Audio & Video Meta-data 51

Pelco

Pelco SDK iv

Overview 51


Motion Detection Meta-data 52

Pelco Analytics Drawing Primitives 53

Timestamps 53

Getting Started 54

What’s Ahead 56

Initializing the MetaData Parser Class 57

Creating a Meta-data Renderer Class 57

Retrieving the Current Timestamp Meta-data 58

Motion Detection Meta-data 59

Retrieving 59

Rendering 59

Drawing Meta-data 60

Retrieving 60

Rendering 61

Exporting Video 63

Overview 63


Custom Application Development 64

Re-coding Video 64

Native Video 64

Pelco

Pelco SDK v

Getting Started 64

What’s Ahead 66

Initializing the Exporter 67

Setting Up a Single Video Clip to be Exported 67

Setting Up Overlay Data on Video to be Exported 68

Resetting Overlay Data 73

Stitching Multiple Clips into a Single Video Export 74

Exporting Video With Overlays 75

Exporting Video Without Overlays 77

Stopping a Video Export 78

Web Service Proxies 79

Overview 79

Getting Started 79

General Usage 79

Device & Service Discovery 82

Overview 82


Getting Started 83

What’s Ahead 85

Initializing the System Manager Wrapper 86

Automatically Determining the System Manager’s IP Address and Port Number 86

Logging in and Logging out 87

Pelco

Pelco SDK vi

Querying Available Devices from the System Manager 87

Querying Any Changes with Available Devices from the System Manager 88

Retrieving the SM’s Time Zone 89

Retrieving the Network Time Server Address 89

Retrieving a Web Service’s ID 90

Retrieving a Specific Web Service’s Control URL 91

Retrieving the NVR Associated with the Device 91

Retrieving the Device’s Friendly Name 92

Retrieving the Device’s Device Description File (DDF) URL 93

Retrieving All Web Services Available on a Device 93

Retrieving a Device’s Attribute 94

Retrieving a System Manager’s Attribute 95

Retrieving a Web Service’s Attribute 96

Creating a IDeviceStorage Class 97

Appendix: Product Compatibility 99

Appendix: Endura 1

Overview 1

System Manager (SM) 1

Endura Devices 1

Endura Events and Alarms 2

Video Exports 4

Where does the Pelco API SDK fit within Endura? 5

Pelco

Pelco SDK vii

Appendix: General Event Messages 6

LoggableEvent 6

LoggableEventParameters 6

LoggableEventParameter 7

Appendix: Hardware Diagnostics Event Messages 8

ConfigurationButton (20180) 8

LoggableEvent Object 9

DriverFailure (20150) 9

PdDiagnostic 9


Fans (20020) 10

PdDiagnostic 10

FanStates 11

FanState 11


HardDrives (20060) 13

PdDiagnostic 13

HardDrivesStates 13

HardDrivesState 13


ImproperShutdown (20070) 15

PdDiagnostic 15

Pelco

Pelco SDK viii


LinkSpeed (20200) 16

PdDiagnostic 16


PowerSupply (20120) 17

PdDiagnostic 18


UPS (20170) 19

PdDiagnostic 19


Appendix: Software Diagnostics Event Messages 21

DataLoss 20040 21

PdDiagnostic 21

LoggableEvent object 21

InputStreams 20160 22

InputStreamsEntries 23

InputStreamsEntry 23


PacketLoss 20080 25

PdDiagnostic 25


SEBs 20210 27

Pelco

Pelco SDK ix

PdDiagnostic 27

SEBsEntries 27

SEBsEntry 27


StorageFull 20190 29

PdDiagnostic 29


StorageTime 20130 30

PdDiagnostic 30


Temperature 20140 31

PdDiagnostic 32


Change History 34

Pelco

Pelco SDK x

WARNING: Please note that any provided sample code is meant to be a reference

implementation focused on educating developers about Pelco devices and Endura.

Though there are exceptions, in general Pelco sample code is NOT intended for

immediate production use without modification.

There are several reasons for this:

• By only including the minimum code, this helps our reader focus on the main concepts

for understanding our technology more easily, more quickly, and more effectively.

• Every situation is different, with different requirements and resources. Realistically we

are unable to account for every situation without making our samples more

complicated and less accessible.

Please also be aware that we utilize open source libraries with our samples, and ensure

that their licensing terms are compatible with your project. These open source libraries

may be subject to the GNU General Public License (GPL), GNU Library/Lesser General

Public License (LGPL) and different and/or additional copyright licenses, disclaimers, and

notices. Generally open source software licenses are compatible for most situations.

Please refer to the exact terms of the GPL and LGPL at either the provided third party

developer's website, the Free Software Foundation, or the Open Source Initiative

regarding your rights under said license(s).

Pelco

Pelco SDK xi

http://www.fsf.org/

http://www.fsf.org/

http://www.opensource.org/

http://www.opensource.org/

Updates

To check if this is the latest revision of the Pelco SDK 2.0 Programmers Guide for C++

documentation, please visit the following link: http://update.pelco.com/confluence/display/xdn/

Latest+PDF+Revision

Once there look for Pelco SDK Documentation, and the Pelco SDK 2.0 Programmers

Guide for C++ underneath it.

You may need to register for an account for the Pelco Developer Network (PDN) http://pdn.pelco.com, in order to view the page.

Pelco

Pelco SDK xii

http://update.pelco.com/confluence/display/xdn/Latest+PDF+Revision




http://pdn.pelco.com


Overview

Who is this for?This document is meant for C++ software developers who are looking to integrate 3rd party software with various Pelco

products, using the Pelco SDK.

How is this document organized?The documentation is organized by the most common tasks that software developers will encounter, when dealing with

Endura. It is recommended that developers read this documentation alongside the

referenced Pelco provided sample code. The Pelco SDK sample code can be found in the following

directory (assuming that you did not change the default installation location): C:\Program Files\Pelco\API\SampleCode

What is the rationale for the format of this document?Various studies have shown that a casual conversational tone, helps readers remember information. Consequently as

opposed to using the traditional formal writing tone, this documentation aims to help readers better retain SDK related

information with a casual writing style.

IntroductionThe Pelco SDK is a powerful software developer kit to help 3rd parties use Pelco products alongside non-Pelco products

and software. While Pelco APIs are both flexible and powerful, it can also potentially overwhelm some users; of course

developers are still free to directly use Pelco APIs as they wish. However Pelco has found that many of our customers

enjoy the convenience and ease of use that the Pelco SDK provides. The Pelco SDK provides programmers ease of use

with the following functionality:

• Video Rendering

• Device & service discovery

• User and role management

• Pan, tilt, and zoom (PTZ) control

• Eventing support

• Video export

• Audio & video meta-data parsing

What does the Pelco SDK contain?The Pelco SDK contains the following major components:

Pelco

Pelco SDK 1

SDK Component Features / Functionality

System Manager Wrapper Device discovery

Service discovery

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

and DVRs / NVRs / NSMs.

PTZ Control Wrapper Pan & tilt control

Zoom, iris, & and focus control

Basic script management

Event Arbiter Library Advanced event subscription management:

Subscribe to individual web service events

Subscribe to events from all instances of a particular web service

Cancel an active event subscription

Event Manager Easy to use event subscription, that focuses on subscribing to

categories of events instead of web service specific events.

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

Motion Detection, Video Analytics Primitives

Render primitives & other data to video frame

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

or PEF

Overlay data on exported video

Pelco GSOAP Provides pre-generated C++ Endura web service proxies

The Pelco SDK also contains sample projects for the following:

C++ Sample Default Location

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

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

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

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

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

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

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

General Requirements

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

the following:

Pelco

Pelco SDK 2

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

• Memory: 2 GB

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

• HD: 1 GB

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

hardware can be found in the Appendix.

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

• Pelco SDK: This software can be downloaded from the Pelco Developer Network (PDN) at http://pdn.pelco.com.

Look in the Pelco SDK Related Downloads sub-section, within the Downloads section; which can be accessed from

the left navigation menu.

• Visual Studio 2008

• Visual Studio 2008 SP1

• Visual C++ 2008 SP1 Redistributable Package

• Visual C++ 2008 SP1 Redistributable Package ATL Security Update

• .NET 3.5 (if using managed SDK modules)

• DirectX 9

Each specific component of the Pelco SDK may have additional requirements.

Initial InstallationDownload the Pelco SDK from the Pelco Developer Network (PDN) at http://pdn.pelco.com. It can be found in the Pelco

SDK Related Downloads sub-section inside the Downloads section. Once finished downloading, double click on the

Pelco SDK installer to begin installation. Simply follow the onscreen prompts to complete installation.

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

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

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

C:\Program Files\Pelco\API\Libs\release

Pelco SDK module libraries can be found within the above directory.

C:\Program Files\Pelco\API\SampleCode

This directory has all the sample code projects related to Pelco SDK components.

C:\Program Files\Pelco\API\WebServices

The WSDLs files for web services are in this directory. Please note that the XSDs are embedded within the WSDL files

themselves. Our WSDLs, along with the embedded XSDs, provide the definition for Pelco web services and related data

types. For details, please refer to the following links:

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

Pelco

Pelco SDK 3



http://update.pelco.com/confluence/display/xdn/Pelco+API+SDK+Related+Downloads








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

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

DistributionWhen distributing your application, which is reliant on the Pelco SDK, you must insure to that the required SDK

component redistributables are installed on the target client machine. As with other redistributables, a UI will not be

presented to the user, and the redistributable itself can be called by your custom installer. Once the redistributable is

finished, your custom installer can check the status of the install and whether or not it needs a reboot.

As with the full SDK, download individual Pelco SDK components and Pelco SDK redistributables from the Pelco

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

inside the Downloads section. Once finished downloading, double click on the Pelco SDK installer to begin installation.

Simply follow the onscreen prompts to complete installation.

Pelco

Pelco SDK 4







Displaying and Controlling Video Streams

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

educating developers about Pelco devices. Though there are exceptions, in general Pelco sam-

ple code is NOT intended for immediate production use without modification.

The content below assumes that the default target installation directory was chosen during in-

stallation.



Latest+PDF+Revision




For a list of the latest special issues and problems regarding the Pelco API Viewer, please visit:

http://update.pelco.com/confluence/display/xdn/PelcoAPIViewer+Issues

OverviewThe most important thing in any security imaging system, is for the security operator to see what images his IP cameras

are capturing. Consequently displaying a video stream and controlling its playback is most likely what you will need to get

working first.

Where does the Pelco SDK fit?To get this done, we need use the Pelco API Viewer. The Pelco API Viewer is an easy to use 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 party applications. This player can be configured to work in both RTP and

Pelco

Pelco SDK 5









RTSP mode. In RTP mode, the player uses one of several Pelco's APIs to initiate and control streams. While in RTSP

mode, the player expects to work with either devices, such as a Sarix IP camera, where RTSP is supported by default; or

software solutions like the RTSP Server.

Getting StartedNOTE: This entry assumes that users have already installed the Pelco SDK. Moreover, the Pelco API Viewer sample

project requires Microsoft’s DirectX 9, and a video card that supports DirectX 9.

To begin using the sample Pelco API Viewer COM sample project, locate it within your Pelco SDK Samples directory:


NOTE: Unlike some of the other Pelco SDK sample projects, the Pelco API Viewer sample is spread across more than a

one class. Consequently the format of this section may differ from usage sections. Moreover unlike the other Pelco SDK

components, there is more than one C++ sample project associated with the Pelco API Viewer. For the purpose of this

documentation, we will focus on the ActiveX COM based sample project.

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

Registering the ActiveX ControlBefore starting any of the tasks below, you will need to manually register the Pelco API Viewer ActiveX Component:

PelcoAPICOMViewer.ocx. To register the PelcoAPICOMViewer.ocx ActiveX Component, open the command line. Now

within the command line navigate to the Pelco SDK library directory, which is by default:

C:\Program Files\Pelco\API\Libs\release. Once within the folder, Microsoft Register Server (Regsvr32.exe) to register the

PelcoAPICOMViewer.ocx file: Regsvr32 PelcoAPICOMViewer.ocx

Pelco

Pelco SDK 6

Setting up the Working DirectoryNext you will need to set the sample project’s

working directory. Assuming that you have

already opened the sample project in MS

Visual Studio, right click on the project and

select the the Properties menu item.

Pelco

Pelco SDK 7

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

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

the Working Directory value as appropriate. Assuming that you did not change the default installation directory for the

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

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

What’s AheadThere are two major tasks for viewing a video stream using the Pelco API Viewer with the ActiveX COM:

• Opening, playing, displaying a stream

• Controlling the stream

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

Pelco

Pelco SDK 8

1. Declare the Pelco API Viewer instance.

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

to the PelcoAPICOMViewer sample project.

2. Then set the instance’s plugin directory. Assuming that you didn’t change the default target installation directory it

can be found here: C:\Program Files\Pelco\API\Libs\Release

The plugin directory contains components that are key to the SDK’s encoding, decoding,

and transcoding capabilities. Without a proper reference key features of the Pelco SDK may not function properly. Please note that the plugin directory’s is dependent on where you

installed the Pelco SDK. The related source code for this entry can be found in main.cpp’s

SetPluginDir method, which resides to the PelcoAPICOMViewer sample project.

3. Now 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.

Opening, Playing, and Displaying a Live RTP Stream

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

belongs to the PelcoAPICOMViewer sample project.

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

PelcoAPI::PelcoAPIViewer _pViewer;_pViewer = new PelcoAPI::PelcoAPIViewer();

_pViewer.SetPluginDirectory("C:\\ Program Files\\ Pelco\\PelcoAPIViewer\\API\\ Libs\\ Release");

HWND _hWndParent = NULL;

//... Logic to create a window and display it. Refer to _DbgCreateParentWindow ...

m_pViewer->SetWindowHandle((_hWnd ? _hWnd : this->m_hWnd));

Pelco

Pelco SDK 9

1. Initialize the Pelco API Viewer. (Please refer to the Initializing the Pelco API Viewer entry for details.)

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

• “NOW” for the starting time since this is a live stream

• “INFINITE” for the ending time since this is a live stream

• The IP address of the source of the video stream

• The port number of the source of the video stream

• The service ID

• The video stream’s transport (RTP) URL (optional)

• The IP camera’s UDN (optional)

• The NVR’s ID (optional)

• If given the NVR UDN, pass in a reference to this MFC COleControl sub-class, which in this case is

CPelcoAPICOMViewerCtrl

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

throughout for tasks related to the Pelco API Viewer.

Opening, Playing, and Displaying a Playback RTP Stream

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

belongs to the PelcoAPICOMViewer sample project.

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



• The starting time of the point within the stream being played

• The ending time of the point within the stream being played

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

Pelco

Pelco SDK 10

• The IP address of the source of the video stream

• The port number of the source of the video stream

• The service ID

• The video stream’s transport (RTP) URL (optional)

• The IP camera’s UDN (optional)

• The NVR’s ID (optional)

• If given the NVR UDN, pass in a reference to this MFC COleControl sub-class, which in this case is

CPelcoAPICOMViewerCtrl

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

throughout for tasks related to the Pelco API Viewer.

Opening, Playing, and Displaying an RTSP Stream

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

which belongs to the PelcoAPICOMViewer C++ sample project.



• 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 starting timestamp to begin playing from (Optional)


//... Other logic ...

pszSesId = _pViewer.StartStream("2010-08-08T18:02:00Z", "2010-08-08T18:28:00Z", "10.220.196.149", "49154", "1", "rtp://10.220.196.148:7162", "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", &_pDelegate);

Pelco

Pelco SDK 11

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

related to the Pelco API Viewer.

Forward Playback of the Stream

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

belongs to the PelcoAPICOMViewer C++ sample project.

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

and Displaying the Stream entry.

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

method; passing in the following parameters:

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

• A float value representing the desired playback speed. Valid possible playback speeds can range from: 0 - 300, with 0

representing a paused state.

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

result.


//... Other logic e.g. setting up windows, and so on ...

pszSesId = _pViewer.StartStream( "rtsp://10.220.196.169/?deviceid=uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", NULL, NULL, false, &_pDelegate);

const char* pszSesId = NULL;

//... Get pszSesId, the stream’s session ID, by starting a stream ...

if(_pViewer.PlayForward(pszSesId, 8.0) !=0 ){ //... Handle error ...}

Pelco

Pelco SDK 12

Reverse Playback of the Stream

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




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

method; passing in the following parameters:

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

• A float value representing the desired playback speed. Valid possible playback speeds can range from 0 - 300, with 0

representing a paused state.


result.

Pausing the Playback Stream

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

to the PelcoAPICOMViewer C++ sample project.




result.

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

stream’s session ID.



if(_pViewer.PlayReverse(pszSesId, 8.0) !=0 ){ //... Handle error ...}

Pelco

Pelco SDK 13

Resuming a Stream from a Paused State

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




To resume a paused playback stream, call the Pelco API Viewer instance’s Resume method; passing in the target video

stream’s session ID.

Stopping the Stream

The related source code for this entry can be found in main.cpp’s StopStream method, which

belongs to the Pelco API Viewer C++ sample project.

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

the Stream entry.



if(_pViewer.Pause(pszSesId) !=0 ){ //... Handle error ...}



if(_pViewer.Resume(pszSesId) !=0 ){ //... Handle error ...}

Pelco

Pelco SDK 14

To perform a stop playback of a currently running video stream, call the Pelco API Viewer instance’s StopStream method;

passing in the target video stream’s session ID.

Taking a Snapshot of the Current Video Frame

The related source code for this entry can be found in main.cpp’s TakeSnapShot method, which

belongs to the Pelco API Viewer C++ sample project.

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

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



if(_pViewer.StopStream(pszSesId) !=0 ){ //... Handle error ...}



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

Pelco

Pelco SDK 15

Panning and Tilting





stallation.



Latest+PDF+Revision




For a list of the latest special issues and problems regarding the PTZ Control Wrapper, please

visit: http://update.pelco.com/confluence/display/xdn/PTZ+Control+Wrapper+Issues

OverviewAfter you’ve found the IP camera on your network, and displayed its live stream on your display; you will probably want to

be able to start controlling your camera’s viewing position: up & down and left & right.

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

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

on panning and tilting the camera.

As in the previous section we’ll be examining the PTZ Control Wrapper sample project. This sample project exhibits PTZ

Control Wrapper functionality. This section is organized by the following entries:

Pelco

Pelco SDK 16









Getting StartedNOTE: This entry assumes that you’ve already installed the Pelco SDK and have already started to display their IP

camera’s live stream. If you haven’t been able to display your IP camera’s live stream yet, please refer to the Displaying

and Controlling Video Streams section for details.

To begin using the sample PTZ Control Wrapper sample project, locate it within your Pelco SDK Samples directory:



Pelco

Pelco SDK 17

Setting up the Working

Directory

Next you will need to set the sample

project’s working directory. Assuming that

you have already opened the sample

project in MS Visual Studio, right click on

the project and select the the Properties

menu item.

Pelco

Pelco SDK 18






Pelco

Pelco SDK 19

Initializing the PTZ Control Wrapper

The related source code for this entry can be found in main.ccp’s main function, which belongs

to the PTZ Control Wrapper C++ sample project.

To instantiate the managed PTZ Control Wrapper instance using the following parameters:

• your IP camera’s current IP address,

• your IP camera’s port number

• your IP camera’s unique camera ID

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

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. (Please refer to the Initializing the PTZ Control Wrapper entry for details.)

2. To pan your IP camera left, call the PTZ Control Wrapper instance’s ContinuousPan method; passing in a negative

rotational x parameter. To pan the IP camera right, call the same method but this time pass in a positive value for the

rotational x parameter. For more details on the ContinuousPan method, please refer to the PTZ Control Wrapper API

reference documentation.

3. Once you want to stop the camera from continually moving, call the Stop method.

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

bool bSuccess = ptzControlWrapper.Stop();

//panning left

bool bSuccess = ptzControlWrapper.ContinuousPan(-10);

//panning right

bool bSuccess = ptzControlWrapper.ContinuousPan(10);


Pelco

Pelco SDK 20

Continuous Tilting



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


2. To tilt the IP camera down, call the PTZ Control Wrapper instance’s ContinuousTilt method; passing in a negative

rotational y value for the second parameter. To tilt it up, call the same method but this time pass in a positive value

for the rotational y parameter. Disregard the last four parameters. For more details on the ContinuousTilt method,

please refer to the PTZ Control Wrapper API reference documentation.


Continuous Diagonal Movement



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


2. Now call the ContinuousMove method. The first parameter represents both speed and direction on the X plane. Use

a negative integer to pan left and a positive integer to pan right. The second parameter represents both speed and

direction on the Y plane. Use a negative integer to tilt down and a positive integer to tilt up. For more details on the

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

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

//tilting upbool bSuccess = ptzControlWrapper.ContinuousTilt(10);


Pelco

Pelco SDK 21


Panning to a Specific Position



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


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

Passing a negative value moves left, while passing a positive value moves right. For more details on the AbsolutePan

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

Tilting to a Specific Position





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

Passing a negative value moves left, while passing a positive value moves right. For more details on the AbsolutePan

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

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

//tilting upbool bSuccess = ptzControlWrapper.ContinuousMove(10, 10);


bool bSuccess = ptzControlWrapper.AbsolutePan(20);

bool bSuccess = ptzControlWrapper.AbsolutePan(20);

Pelco

Pelco SDK 22

Moving to a Specific Position





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

Passing a negative value moves down, while passing a positive value moves up. Please refer to your camera

model’s specifications for tilt position limits. For more details on the AbsoluteTilt method, please refer to the PTZ

Control Wrapper API reference documentation.

Getting the Camera’s Current Position





2. Call the PTZ Control Wrapper’s GetAbsolutePosition method. For more details on the GetAbsolutePosition method,

please refer to the PTZ Control Wrapper API reference documentation.

.

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

int positionX = 1500;int positionY = 1500;

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

Pelco

Pelco SDK 23

Magnification (Zoom), Focus, and Iris Control





stallation.



Latest+PDF+Revision






OverviewAfter you’ve found the IP camera on your network, and displayed its live stream on your display; you probably would like

to IP camera features like magnification (zoom), focus, and the IP camera’s iris.

Where does the Pelco SDK fit?Like panning and tilting in the previous section, the above functionality can be accessed using the PTZ Control Wrapper.

The PTZ Control Wrapper is a easy to use tool for controlling various PTZ and lens related functionality.

As in the previous section, we will be examining the PTZ Control Wrapper sample project, which demonstrates PTZ

Control Wrapper functionality.

Pelco

Pelco SDK 24









Getting StartedNOTE: This entry assumes that you’ve already installed the Pelco SDK and have already started to display their IP

camera’s live stream. If you haven’t been able to display your IP camera’s live stream yet, please refer to the Displaying

and Controlling Video Streams section for details.

To begin using the sample PTZ Control Wrapper sample project, locate it within your Pelco SDK Samples directory:



Pelco

Pelco SDK 25


Directory






menu item.

Pelco

Pelco SDK 26






Pelco

Pelco SDK 27

Managing the Magnification (Zoom) Value



This entry covers how to change the camera’s current magnification level, and set its magnification limits. Magnification

refers to the camera’s zoom level, which in term describes the camera’s lens‘ currently set focal length. Typically a focal

length of a 100 mm describes a zoom level.

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

1. Initialize the PTZ Control Wrapper. (Please refer to the Initializing the PTZ Control Wrapper entry in the Panning and

Tilting section for details.)

2. Call the PTZ Control Wrapper’s SetMag method passing in the desired zoom level. If the request was successful,

your camera’s magnification level should now be changed. For more details on the SetMag method, please refer to

the Appendix: PTZ Control Wrapper API section.

3. Simply call the GetMag method to return the camera’s current magnification setting. If the request was successful,

your camera’s magnification level should now be changed. For more details on the GetMag method, please refer to

the Appendix: PTZ Control Wrapper API section.

Managing the Focus Value



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

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



2. For a little background, the Focus method takes in only the following values:

• 0: To stop all focus related operations.

• 1: To start focusing nearer.

bool bSuccess = ptzControlWrapper.SetMag(150);

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

Pelco

Pelco SDK 28

• 2: To start focusing farther.

Call the Focus method passing in the desired focus command. If the request was successful, your camera’s focus

should now be changing (unless you passed a 0). This will not stop until either a new Focus request is made with

a different value, or if you call the Stop method; which will stop movement or lens related action the camera is

currently doing.

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

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

false.

Iris Control



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

This part of documentation goes over how to open and close your camera’s iris.



2. For a little background, the Iris method takes only following values:

• 0: To stop all iris related operations.

• 1: To start closing the iris.

• 2: To start opening the iris.

Call the Iris method passing in the desired iris command. If the request was successful, your camera’s iris should

now be changing (unless you passed a 0). This will not stop until either a new Iris request is made with a different

value, or if you call the Stop method; which will stop movement or lens related action the camera is currently

bool bSuccess = ptzControlWrapper.Focus(1);



bool bSuccess = ptzControlWrapper.AutoFocus(true);

Pelco

Pelco SDK 29

doing.

3. Alternatively the recommended way of controlling the iris is to let your IP camera manage it automatically. 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.Iris(1);

bool bSuccess = ptzControlWrapper.Iris(2);

bool bSuccess = ptzControlWrapper.AutoIris(true)

Pelco

Pelco SDK 30

Scripting





stallation.



Latest+PDF+Revision






OverviewOne of Pelco’s most powerful features comes from the ability for users being able to manage and run scripts. Scripts are

allow you to extend the behavior of Pelco devices with little effort. Before we show you how to use the SDK’s scripting

related features, it’s important to know about the different types of Pelco scripts:

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

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

monitoring several specific points using the same camera, you can set one preset for each location that needs to be

monitored; each with its own set of zoom, iris, and focus values.

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

Pelco

Pelco SDK 31









PatternA pattern is like a group of presets combined. Let’s see you control an IP PTZ camera guarding a hallway with two

entrances and a window. With patterns you can set a bookmark for camera behavior that changes the camera’s view

from one of the three points of interest every 15 seconds.

NOTE: You cannot create a Pattern by combining existing Presets.

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

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

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

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

Getting StartedTo begin using the sample PTZ Control Wrapper sample project, locate it within your Pelco SDK Samples directory:



Pelco

Pelco SDK 32


Directory






menu item.

Pelco

Pelco SDK 33






Creating a Preset



These steps will show you how to create a preset.



2. Now setup your Pelco IP camera with a combination of settings that you want to save i.e. the IP camera’s current

viewing position, iris setting, focus setting, zoom, and so on.

Pelco

Pelco SDK 34

3. Then call the BeginScript method, passing in the desired name of the pattern. When BeginScript is called, the Pelco

IP camera will begin ‘recording’ your actions.

4. Finally call the EndScript method, passing in the same pattern name as you did before.

Updating an Existing PresetTo update an existing preset, just following the steps outlined in the Creating a Preset entry; ensuring that you use the

name of the preset to modify as the parameter for both the BeginScript and EndScript methods.

Creating a Pattern



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



2. Now setup your Pelco IP camera with a combination of settings that you want to save i.e. the IP camera’s current

viewing position, iris setting, focus setting, zoom, and so on.

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

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

have three points of interest you would first go to the first point of interest with a certain zoom and focus level. After

waiting for a some predetermined time, you then move the camera’s view into the second point of interest which has

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

5. Finally call the EndScript method, passing in the same preset name as you did before.

bool bSuccess = ptzControlWrapper.BeginScript("ViewMainEntrance");

bool bSuccess = ptzControlWrapper.EndScript("ViewMainEntrance");

bool bSuccess = ptzControlWrapper.BeginScript("ViewAllEntrances");

bool bSuccess = ptzControlWrapper.EndScript("ViewAllEntrances");

Pelco

Pelco SDK 35

Updating an Existing PatternTo update an existing pattern, just following the steps outlined in the Creating a Pattern entry; ensuring that you use the

name of the pattern to modify as the parameter for both the BeginScript and EndScript methods.

Executing an Existing Script



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

script will continue to run until it either completes itself or is stopped prematurely by the user using the HaltScript

method, detailed below.

Stopping a Script Currently Being Executed



If you want to stop a script that is currently running, call the PTZ Control Wrapper’s HaltScript method, passing in the

name of the script to stop.

bool bSuccess = ptzControlWrapper.ExecuteScript("Poker");

bool bSuccess = ptzControlWrapper.HaltScript("Poker");

Pelco

Pelco SDK 36

Events and Alarms





stallation.



Latest+PDF+Revision




For a list of the latest special issues and problems regarding the Event Arbiter library, please visit:

http://update.pelco.com/confluence/display/xdn/Event+Arbiter+Library+Issues

For a list of the latest special issues and problems regarding the Event Manager, please visit:

http://update.pelco.com/confluence/display/xdn/Event+Manager+Issues

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

met. Specifically Pelco products, acting as event providers, send these events and alarms to their subscribers. Typically

event providers are web services, while subscribers are software clients. For example, if an IP camera’s MotionDetection

service detected movement within a particular region in the video frame, it can send an event to all of its subscribers

such as a VMS.

Pelco

Pelco SDK 37











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

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

However there are differences between the two components. The Event Arbiter Library is the primary component for

dealing with eventing. It is for users looking for the most flexibility and control. Conversely, the Event Manager is a

component that sits on top of the Event Arbiter Library. It’s main purpose is to provide users with ease of use in

exchange for decreased control.

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

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

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

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

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

event subscription.

Environment Pelco SDK Consequence

No System Manager Only direct device subscription available

Not all event data will be parsed by Pelco SDK

System Manager available; EventArbiter web service

active

Able to subscribe to all devices providing a specific web

service


NOT active

All event data is available and parsed

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

provides another abstraction on top of the Event Arbiter Library, and simplifies event operations even further. It allows

Pelco

Pelco SDK 38

subscriptions to all available web services for all devices on a given network 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

• Relay Array Configuration events

• Motion Detection events

• Video Analytics events

• Diagnostic Reporting events

Environment Pelco SDK Consequence

No System Manager N/A Can’t use Event Manager


active

Able to subscribe to all available web services that under under

a chosen category


NOT active

All event data is available and parsed

Event Arbiter Library vs Event Manager

Event Arbiter Event Manager

Harder to use, but with more options and flexibility Easier to use, but not as flexible: the user only needs to choose

the category of events he is interested in receiving.

Does not require a System Manager Requires a System Manager

Able to subscribe to a single device’s web service

using either an IP address or UDN

Able to subscribe to all instances of a particular web

service. i.e. A user can subscribe to all

MotionDetection web services for all devices with just

one request

For more Endura specific information, please refer to the Appendix.

Getting StartedNOTE: This entry assumes that users have already installed the Pelco SDK.

To begin using both the Event Arbiter Library & Event Manager sample projects, locate them within your Pelco SDK

Samples directory: C:\Program Files\Pelco\API\SampleCode


Pelco

Pelco SDK 39

Setting up the Working Directory

Next you will need to set the sample project’s

working directory, for both the Event Arbiter

Library sample project and the Event Manager

sample project. Assuming that you have already

opened the sample project in MS Visual Studio,

right click on the project and select the the

Properties menu item.

Pelco

Pelco SDK 40






What’s AheadThis is a high level overview of what steps are needed for handling events.

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

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

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

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

service.

Pelco

Pelco SDK 41

Creating an Event Agent

The related source code for this entry can be found in MyEventAgent header file, which

belongs to the Event Arbiter Library C++ sample project.

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

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

NotifyEvent includes parameters for the response and the event.

Details of implementation are left to the user. However in the MyEventAgent sample class, we demonstrate basic

functionality for accessing event related data.

Returning the Event Subscription URL


to the System Manager Wrapper C++ sample project.

NOTE: This entry assumes that the user has already completed the steps in the Retrieving a Web Service’s ID entry.

#ifndef MYEVENTAGENT_H#define MYEVENTAGENT_H

#include "PelcoAPI/IEventAgent.h"

using namespace PelcoAPI;

class MyEventAgent : public IEventAgent{public: STDCALL MyEventAgent();

virtual STDCALL ~MyEventAgent();

void STDCALL NotifyEvent(const char * szResponse, const Event * pEvent);

private: int m_nCounter;};

#endif

Pelco

Pelco SDK 42

The event subscription URL is what you would need to subscribe to a particular web service. This is also known as the

‘control point URL’ or ‘end point URL’.

1. Initialize the System Manager Wrapper. (Please refer to the Initializing the System Manager Wrapper entry for details.)

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

• Your login ID, a result returned from a successful call to the UserLogin method.

• The target device’s Unique Device Name (UDN) value: To retrieve a deviceUDN, just cycle through the stored

results of a GetDevices call within your IDeviceStorage class instance. For details, please refer to the Querying

Available Devices from the System Manager entry.

• The web service’s Service ID. It is a URN value found on the web service’s corresponding WSDL file.

• The attribute name of SYS_UpnpEventSubUrl

• The pointer to the variable that will hold the result

Initializing the Event Arbiter Library

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

which belongs to the Event Arbiter Library C++ sample project.

NOTE: This assumes that you have already completed the steps outlined in the Creating an Event Agent entry.


2. Next, declare the Event Arbiter Library instance.

3. Now set the Event Arbiter Library instance's network location and port number, using the System Manager’s IP

address and port number. (Please refer to the Automatically Determining the System Manager’s IP Address and Port

Number entry for more details.)

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

PelcoAPI::IEventArbiter * pEventArbiter = new PelcoAPI::EventArbiter();

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

Pelco

Pelco SDK 43

4. Register your Event Agent class with the Event Arbiter Library instance. For details on creating an Event Agent,

please refer to the Creating an Event Agent entry.

Initializing the Event Manager



Please also note that the Event Manager requires the presence of a System Manager on the

network.

NOTE: This assumes that you have already completed the steps outlined in the Creating an Event Agent entry in the

Appendix. These steps also require the existence of both an Event Arbiter on your network.


2. To initialize the Event Manager instance, set the Event Manager instance's network location, port number, and Event

Agent. Use the System Manager’s IP address and port number for the IP address and port number parameters.

(Please refer to the Automatically Determining the System Manager’s IP Address and Port Number entry for more

details.)

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

common scenarios.

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

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

"10.220.196.200", "9716", &agent);

Pelco

Pelco SDK 44

Using the Event Arbiter Library to subscribe to a specific device’s particular web service

using the device’s IP address

This entry is relevant for users who are not relying on either the System Manager or its

EventArbiter service.



Having an event subscription simply tells a device that you would like to receive its event notifications. To request a event

subscription, the following must be done:

1. Initialize the Event Arbiter Library. (Please refer to the Initializing the Event Arbiter Library entry for details.)

2. Now call the Event Arbiter wrapper instance's SubscribeToEvents method, passing the event subscription URL. (For

details, please refer to the Returning the Event Subscription URL entry above.) If the request was successful, the

method will return the event subscription's unique ID which will allow users to either renew or unsubscribe the event

subscription.

(Please note that the Pelco SDK now automatically handles subscription renewals.)

Using the Event Arbiter Library to subscribe to a specific device’s particular web service

using the event subscription URL

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

System Manager and an enabled EventArbiter service on the System Manager.




2. Then construct an event service ID. It consists of the device’s UDN and the web service’s URN, which is its

namespace on its WSDL file. (For details on determining a web service’s ID, please refer to the Returning the Event

Subscription URL entry.)

const char * szSid_1 = pEventArbiter->SubscribeToEvents("http://10.220.196.184:80/

event/AlarmArrayConfiguration-1");

std::string strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/urn:pelco-

com:serviceId:VideoAnalytics-1";

Pelco

Pelco SDK 45

3. Now call the Event Arbiter Library instance's SubscribeToEvents method, passing the event service ID. (Please note

that the API SDK automatically handles subscription renewals.) If the request was successful, the method will return

the event subscription's unique ID which will allow users to either renew or unsubscribe the event subscription.


Using the Event Arbiter Library to subscribe to all instances of a particular web service

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

System Manager and an enabled EventArbiter service on the System Manager.



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

that has events), do the following:


2. Then construct an event URN. It is essentially the SOAP web service URN. You can determine this URN value

looking at the web service’s associated WSDL file (it should be near the top of the file).

3. Now call the Event Arbiter wrapper instance's SubscribeToEvents method, passing the event URN. (Please note that

the API SDK automatically handles subscription renewals.) If the request was successful, the method will return the

event subscription's unique ID which will allow users to either renew or unsubscribe the event subscription.


Using the Event Arbiter Library to unsubscribe from a service



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

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

const char * szSid_1 = pEventArbiter->SubscribeToEvents("urn:schemas-pelco-

com:service:MotionDetection:1");

Pelco

Pelco SDK 46

NOTE: This entry assumes that the user has already completed the steps outline in any of the above Event Arbiter

subscription related entries.

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

method, passing the subscription identifier. (You receive subscription IDs on successful calls to SubscribeToEvents.) If the

request was successful, the method will return a 1. Otherwise it will return a 0.

Mass Subscriptions by CategoryIf you don’t really know what particular events or devices where you would like a subscription, then this section is for you.

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

Using the Event Manager to subscribe to all web services under specific category

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

function, which belongs to the Event Arbiter Library C++ sample project.

Please also note that the Event Manager can only subscribe to one category of events at any

one time, and that it requires the presence of a System Manager on the network.

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

SDK.

1. Initialize the Event Manager. (Please refer to the Initializing the Event Manager entry for details.)

2. Now call the Event Manager instance's Start method, passing the desired event type as defined the by Pelco SDK.

The Event Manager will not start ‘listening’ to event. Currently the following are valid options:

const char * szSid_1 = pEventArbiter->SubscribeToEvents(

"urn:schemas-pelco-com:service:MotionDetection:1");

// ... misc logic ...

pEventArbiter->UnSubscribeToEvents(strSid_1);

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

Pelco

Pelco SDK 47

Alarm Array Configuration: Events are that are related to the AlarmArrayConfiguration web service.

Relay Array Configuration: Events are that are related to the RelayArrayConfiguration web service.

Motion Detection: Events are that are related to the MotionDetection web service.

Video Analytics: Events are that are related to the VideoAnalytics web service

Diagnostic Reporting: Events are that are related to the DiagnosticReporting web service

Unknown: This is a system reserved value. Please disregard it.

Mask: This is a system reserved value. Please disregard it.

(Please always refer to the EventArbiterDefs header for the latest options.) If the request was successful, the method

will return true; false otherwise.


Using the Event Manager to unsubscribe from all web services within a category

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

function, which belongs to the Event Arbiter Library C++ sample project.

Please also note that the Event Manager requires the presence of a System Manager on the

network.

NOTE: This entry assumes that the user has already completed the steps outline in the Event Manager subscription

related entry.

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

successful it will return true, false otherwise.

Handling Incoming Events

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


NOTE: The availability of some data is dependent on the availability of a System Manager on your network. i.e. If a

System Manager is not online, then some event data will be missing.

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

provided Event struct.

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

bool ret = pEventManager->Stop();

Pelco

Pelco SDK 48

1. Define a class that implement the EventAgent interface. (For details please refer to the Creating an Event Agent

Class entry.)

2. Within your EventAgent implementation is the NotifyEvent method. This is where you will process any incoming

event notifications. Events will be represented by the Event struct as defined in the EventArbiterDefs header. (The

raw event XML string data will be encapsulated by the parameter.)

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

• device UDN, web service ID

• the timestamp in UTC

• the event type as defined by the Pelco SDK

• the device’s friendly name

If the incoming event is an alarm from the AlarmArrayConfiguration web service, it will provide information on the camera

it is associated with as well as general alarm data.

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

as the relay ID and whether or not it is enabled.

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

if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION){ //the camera associated to this event pEvent->m_strAssociateCameraUdn.c_str();

for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size(); i++) { //alarm ID pEvent->m_alarmOrRelayInfo[i]->m_nId; //alarm severity pEvent->m_alarmOrRelayInfo[i]->m_nSeverity; //the state of the alarm 0 off 1 on pEvent->m_alarmOrRelayInfo[i]->m_bState; }}

Pelco

Pelco SDK 49

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

active or inactive.

If the incoming event is from the VideoAnalytics web service, it will show whether or not it is active. If active, it will also

display the severity of the alarm.

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

to your classes.

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

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

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

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

Pelco

Pelco SDK 50

Extracting Audio & Video Meta-data





stallation.



Latest+PDF+Revision




For a list of the latest special issues and problems regarding the Meta-data Parser, please visit:

http://update.pelco.com/confluence/display/xdn/PTZ+Control+Wrapper+Issues

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

timestamps.

Where does the Pelco SDK fit?The Meta-data Parser is a utility for parsing Pelco Video Elementary Stream (VES) meta-data from Pelco streams. Pelco

VES frames contain the following meta-data:

• MotionDetection active areas

• timestamps

• Pelco Analytics drawing primitives

• RSA Signature and other information necessary to verify the frame

Pelco

Pelco SDK 51









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

stream.

Motion Detection Meta-data

Motion detection involves computing the difference between two images. If the difference between the compared images

crosses a certain threshold value then motion is detected and the selected Alert is triggered. The key to Pelco’s motion

detection feature is the Region of Interest (ROI). The ROI denotes a motion detection region within a video frame. A

motion detection region is essentially a grid of motion detection 16x16 pixel cell blocks. These cells have sensitivity and

movement threshold limits. The sensitivity level dictates the amounts of movement that are registered within the ROI,

while the threshold dictates the amounts of blocks that are registered within the ROI before the selected alarm is

triggered.

Pelco

Pelco SDK 52

What motion detection meta-data is available? Currently in terms of meta-data, each video frame can only hold a single

ROI. Consequently for each frame, the meta-data describes the length and width of the ROI, while also holding a Pelco

base64 bit mask for the state of the ROI.

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

appends an ‘=’ character at the end of the encoded value.

Pelco Analytics Drawing Primitives

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

basically contains information related to the points, lines, arcs

Timestamps

Timestamp meta-data is just the exact date and time when the video frame was captured. The Meta-data Parser Library

can return this data in a number of ways.

struct timeval

• tv_sec: The time interval in seconds since the epoch.

• tv_usec: The time interval in microseconds since the epoch.

struct tm

The timestamp represented as a struct tm.

typedef struct timeval {

long tv_sec;

long tv_usec;

} timeval;

Pelco

Pelco SDK 53

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

• tv_year: The time interval in years since 1900.

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

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

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

In addition to returning the data above, the Meta-data Parser Library also returns the daylight savings offset, the current

timezone, and values in local time.


To begin using the sample Meta-data Parser sample project, locate it within your Pelco SDK Samples directory:



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;

}

Pelco

Pelco SDK 54


Directory






menu item.

Pelco

Pelco SDK 55






What’s AheadThis is a high level overview of possible tasks related to meta-data.

1. Access the meta-data from the stream.

2. Render meta-data onto a video frame.

Pelco

Pelco SDK 56

Initializing the MetaData Parser Class


to the Meta-data Parser C++ sample project.

Create the MetaDataParser instance, and then call its SetData method, passing the buffer containing the data to analyze

and the buffer length as parameters.

Creating a Meta-data Renderer Class

The related source code for this entry can be found in SampleMetaDataRenderer.ccp’s main

function, which belongs to the MetaDataParser C++ sample project. Please note that you are expected to implement the actual logic.

This class is used for drawing onto video frames.

1. Implement the following required protected methods:

• DrawLine: This is meant to draw a line using two given points: 'v1' and 'v2'

• DrawRectangle: Add code to draw a rectangle whose upper-left corner is determined by the parameter v1, while

the lower-right corner is determined by the parameter v2. If 'fill' parameter is set to true, the rectangle should be

solid. Otherwise, it should just be the outline.

• DrawPolygon: Add code to draw a polygon with corners defined within the Vector array. If the 'fill' parameter is

set to true, the polygon should be solid. Otherwise, it should just be an outline.

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

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

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

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

Pelco

Pelco SDK 57

• RenderDrawingData:

2. Optionally implement the following protected methods:

• BeginDraw: Perform any pre-drawing work here.

• EndDraw: Perform any post-drawing work here.

• TransformVectorForDisplay: This should handle point translation and scaling.

Retrieving the Current Timestamp Meta-data



1. First initialize the MetaDataParser. For details refer to the Initializing the MetaData Parser Class entry in the Appendix.

2. Then check if the parser has found a timestamp by calling the HasTimeStamp method, which will return true if

found; false otherwise.

3. If there is a timestamp, call the GetTimeStampAsString method, passing in the following:

• A local time boolean parameter, where if true returns the timestamp in local time; while false returns the UTC value

• The desired format for the timestamp

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

virtual void BeginDraw() throw();

virtual void EndDraw() throw();

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

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

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

Pelco

Pelco SDK 58

Motion Detection Meta-data

Retrieving



1. First initialize the MetaDataParser. For details refer to the Initializing the MetaData Parser Class entry in the Appendix.

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

true if found; false otherwise.

3. If there is motion detection meta-data, call the GetMotionData method and pull the result into a new MotionData

instance.

4. Parse the resulting data from the MotionData instance.

Rendering



NOTE: This entry assumes that the user has already completed the steps outline in Creating a Meta-data Renderer Class

entry found in the Appendix.

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

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

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

Pelco

Pelco SDK 59

1. First initialize the MetaDataParser. For details refer to the Initializing the MetaData Parser Class entry.

2. Then check if the parser has found motion detection data by calling the HasMotionData method, and if true retrieve

the motion meta-data.

3. Once you grab the motion detection meta-data, declare your MetaDataRenderer class.

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

our colors are fully opaque with zero transparency: red, green, and blue.

5. Finally ender the motion meta-data onto the screen by calling the RenderMotionData method.

Drawing Meta-data

Retrieving




2. Then check if the parser has found motion detection data by calling the HasDrawingData method, which will return

true if found; false otherwise.

If there is motion detection meta-data, call the GetDrawingData method, pulling the result into a DrawingData

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

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

SampleMetaDataRenderer renderer;

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

renderer.RenderMotionData();

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

Pelco

Pelco SDK 60

instance.

3. Parse the resulting data, by iterating through the returned drawing primitives.

Rendering



NOTE: This entry assumes that the user has already completed the steps outline in Creating a Meta-data Renderer Class

entry.


2. Then check if the parser has found drawing detection data by calling the HasDrawingData method, and if true

retrieve the motion meta-data by calling the GetDrawingData.

3. Once you grab the drawing meta-data, declare your MetaDataRenderer class.

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

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

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

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

SampleMetaDataRenderer renderer;

Pelco

Pelco SDK 61

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

our colors are fully opaque with zero transparency: red, green, and blue.

5. Finally ender the drawing meta-data onto the screen by calling the RenderDrawingData method.

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

renderer.RenderDrawingData();

Pelco

Pelco SDK 62

Exporting Video





stallation.



Latest+PDF+Revision




For a list of the latest special issues and problems regarding the Exporter, please visit: http://

update.pelco.com/confluence/display/xdn/Exporter+Issues

OverviewAt 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 capture live or playback video; and save it in either AVI,

MP4, 3GP, or PEF format. It is multi-threaded to help ensure good performance and to capture as many streams

possible at any given time. Moreover, users will be able to capture live stream or playback saved streams without having

to initializing the stream. Consequently it provides the flexibility to specify the camera, the start time and an optional end

time value. This tool is also able to optionally embed meta-data (timestamp, and so on) into non PEF streams (this

requires transcoding which affects performance). When available, audio will be included in the export. It should be noted

that when audio is included, PEF is the only available export format.

Pelco

Pelco SDK 63







http://update.pelco.com/confluence/display/xdn/Exporter+Issues




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

video file. The most common file format for such video files is AVI. However, AVI is only a container format; not a

compression format. From this point forward, there are two principally different implementations for video storage: re-

coding and native.

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

the standard codecs provided with the Windows Media Player.

Pelco's own export software converts a native PEF file to an AVI file using this decoding and re-encoding technique. The

advantage is that the resulting file can be played back on almost any platform. The disadvantage is that the AVI file size

increases considerably over the PEF file size. However, since this makes video stream playback much easier for end-

users; it is a good approach for standard video export.

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

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

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

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

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

commercial versions


To begin using the sample Exporter sample project, locate it within your Pelco SDK Samples directory:



Pelco

Pelco SDK 64


Directory






menu item.

Pelco

Pelco SDK 65






What’s AheadThis is a high level overview of possible tasks related to meta-data.

1. Setup desired video clips to export.

• Configure desired parameters for each video clip to export

• If overlays are desired, setup overlays for each video clip

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

Pelco

Pelco SDK 66

Initializing the Exporter


to the Export C++ sample project.

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

• The location of the plugins directory. The plugin directory contains components that are key to the SDK’s encoding,

decoding, and transcoding capabilities. Without a proper reference key features of the Pelco SDK may not function

properly. Assuming that you didn’t change the default target installation directory it can be found here: C:\Program

Files\Pelco\API\Libs\Release

• The System Manager’s IP address. For details on the importance of the System Manager for the Exporter, please refer

to the Video Exports entry within the Appendix.

• The IP Address to use for receiving incoming stream(s) i.e. the client machine using the Pelco SDK.

Setting Up a Single Video Clip to be Exported



• First determine the source device for the video clip to export and use it’s UDN, which is in UUID format. In this case the

source device is a camera.

• Now determine the starting and ending times to use for filtering your video clip. For example, you have video from one

camera that spans from 12AM on September 7th to 11pm on September 10th. You limit the output of the export, to

only include footage that runs from 8AM on September 8th through 8pm on September 9th. (The example below has a

clip that ranges from 5:08AM to 5:09AM on August 16, 2009.)

• Then decide if you only want to include only video (then set to true), or if you also want to include audio. If you want

audio to be included, PEF is the only available export format.

• At this point determine if you want to associate any overlays to the video clip. Determine how many overlays you will

associate with the the clip to export. If so, create and initialize any overlays to associate with the video clip to export.

(For further details please refer to the Setting Up Overlay Data on Video to be Exported entry below.)

PelcoAPI::EnduraExporter exporter;exporter.Setup("C:\\ Program Files\\ Pelco\\PelcoAPIViewer\\API\\ Libs\\ Release", "10.80.139.68", "10.220.196.189");

Pelco

Pelco SDK 67

Setting Up Overlay Data on Video to be Exported



This entry assumes that you are already familiar with the content in the Setting Up a Single Video

Clip to be Exported entry above.

If you choose to embed overlays with your video export, regardless of input source

stream’s format, the resulting exported file will be in MPEG-4 format.

First decide on what type of overlay that you would like create. There are several types as defined in the

EnduraExporterDefines header file:

• timestamp: The overlay displays a timestamp.

• cameraname: The overlay displays a camera’s name. Typically the camera name displayed is the source of the video

stream.

• textstring: The overlay displays text.

• picture: The overlay displays a picture.

PelcoAPI::ExportInfo * exportInfo = new PelcoAPI::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;

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

Pelco

Pelco SDK 68

Now create a new instance of OverlayInfoNet and, based on the type of overlay you chose, simply start assigning the

desired values with it such the font to use, the color of the font, the location of the overlay, and so on. The following is a

list of other overlay settings (some may or may not apply to certain overlay types as noted):

• location: The general screen location of the overlay. (Please refer to the DataMixerPluginDefines header for the latest

definition of OverlayLocation.)

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

• value: The actual value to display. For picture overlays, this is the full path to the picture to display. While for

cameraname overlays, this is the name of the camera. Finally for textstring overlays, this is just the alphanumeric value

to display on the overlay. (This does not apply to timestamp overlays.)

• fontName: This is the name of an available font to use for displaying overlays. (This does not apply to picture

overlays.)

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

• fontColor: This is the color of a font. (This does not apply to picture overlays.)

• fontBgColor: This is the font’s color. (This does not apply to picture overlays.)

• pictureOpacity: The opacity of the overlay. This ranges from transparent (0% opacity) to solid (100% opacity). This is

only relevant for picture overlays.

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

Pelco

Pelco SDK 69

• dateFormat: This is only relevant to the timestamp overlay.

• mdyyy: This date format conforms to the following structure: m/d/yyyy (month/day/year), where both 'm' and 'd'

could be either one or two digits. e.g. 12/12/2001 or 2/3/2001

• mdyy: This date format conforms to the following structure: m/d/yy, (month/day/year) where both 'm' and 'd'

could be either one or two digits.e.g. 12/12/01 or 2/3/01

• mmddyy: This date format conforms to the following structure: mm/dd/yy. (month/day/year) e.g. 02/03/01

• mmddyyyy: This date format conforms to the following structure: mm/dd/yyyy (month/day/year) e.g. 02/03/2001

• yymmdd: This date format conforms to the following structure: yy/mm/dd (year/month/day) e.g. 01/02/03

• yyyymmdd: This date format conforms to the following structure: yyyy-mm-dd (year-month-day) e.g. 2001-02-03

• ddmmyy: This date format conforms to the following structure: dd-mm-yy (day-month-year) e.g. 02-03-01

• dmyy: This date format conforms to the following structure: d/m/yy, (day-month-year) where both 'm' and 'd'


• ddmmyy: This date format conforms to the following structure: dd/mm/yy (day/month/year) e.g. 03/02/2001 or

31/12/2001

• dmyyyy: This date format conforms to the following structure: d/m/yyyy, (day/month/year) where both 'm' and 'd'


• ddmmyyyy: This date format conforms to the following structure: dd/mm/yyyy (day/month/year) e.g. 21/03/2001

• yymd: This date format conforms to the following structure: yy/m/d, (year/month/day) where both 'm' and 'd'


• yyyymd: This date format conforms to the following structure: yyyy/m/d, (year/month/day) where both 'm' and

'd' could be either one or two digits. e.g. 1954/1/1 or 1973/12/1

• yyyymmdd: This date format conforms to the following structure: yyyy/mm/dd (year/month/day) e.g. 2001/02/03

• yyyymd: This date format conforms to the following structure: yyyy-m-d, (year/month/day) where both 'm' and 'd'

could be either one or two digits. e.g. 1954-1-1 or 1973-12-1

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

Pelco

Pelco SDK 70

• timeFormat: This is only relevant to the timestamp overlay.

• hhmmsstt: This time format conforms to the following 12 hour structure: hh:mm:ss tt (hours:minutes:seconds

AM/PM) e.g. 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 both 'h' could be either one or two digits. e.g. 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

both 'h' could be either one or two digits. e.g. 6:07:12 AM or 12:07:12 PM

• hhmmss: This time format conforms to the following 24 hour structure: hh:mm:ss (hours:minutes:seconds) e.g.

06:07:12 or 18:07:12

• hmstt: This time format conforms to the following 12 hour structure: h:m:s tt (hours:minutes:seconds), where

both 'h', 'm', or 's' could be either one or two digits. e.g. 6:7:12 AM, 12:17:12 PM, or 12:3:2 PM

• tthms: This time format conforms to the following 12 hour structure: tt h:m:s (AM/PM hours:minutes:seconds),

where both 'h', 'm', or 's' could be either one or two digits. e.g. AM 6:7:12, PM 12:17:12, or PM 12:3:2

• tthhmmss: This time format conforms to the following 12 hour structure: tt hh:mm:ss (AM/PM

hours:minutes:seconds), e.g. AM 06:7: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 both

'h', 'm', or 's' could be either one or two digits. e.g. 6:7:12, 12:17:12, or 12:3:2

Below is a timestamp overlay example:

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

exportInfo[i].overlayInfo[0].type = PelcoAPI::OVERLAY_TYPE_TIMESTAMP;exportInfo[i].overlayInfo[0].location = PelcoAPI::OVERLAY_LOCATION_BOTTOM_LEFT;exportInfo[i].overlayInfo[0].value = NULL;exportInfo[i].overlayInfo[0].fontName = "Arial";exportInfo[i].overlayInfo[0].fontSize = 10;exportInfo[i].overlayInfo[0].fontColor = 0xFF;exportInfo[i].overlayInfo[0].fontBgColor = 0x00;exportInfo[i].overlayInfo[0].pictureOpacity = 0;exportInfo[i].overlayInfo[0].dateFormat = PelcoAPI::DATE_FORMAT_MDYYYY;exportInfo[i].overlayInfo[0].timeFormat = PelcoAPI::TIME_FORMAT_HHMMSSTT;

Pelco

Pelco SDK 71

Below is a cameraname overlay example:

Below is a picture overlay example:

Below is a textstring overlay example:

Setting Up a Multiple Video Clips to be Exported



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 that you will need. (For details on how to set up

one set of video clip export settings, please refer to the Setting Up a Single Video Clip to be Exported entry above.)

exportInfo[i].overlayInfo[1].type = PelcoAPI::OVERLAY_TYPE_CAMERANAME;exportInfo[i].overlayInfo[1].location = PelcoAPI::OVERLAY_LOCATION_BOTTOM_RIGHT;exportInfo[i].overlayInfo[1].value = NULL;exportInfo[i].overlayInfo[1].fontName = "Arial";exportInfo[i].overlayInfo[1].fontSize = 12;exportInfo[i].overlayInfo[1].fontColor = 0xFF;exportInfo[i].overlayInfo[1].fontBgColor = 0x00;exportInfo[i].overlayInfo[1].pictureOpacity = 0;

exportInfo[i].overlayInfo[2].type = PelcoAPI::OVERLAY_TYPE_PICTURE;exportInfo[i].overlayInfo[2].location = PelcoAPI::OVERLAY_LOCATION_TOP_RIGHT;exportInfo[i].overlayInfo[2].value = "D:\\Everest\\Plugins\\pelco_se.bmp";exportInfo[i].overlayInfo[2].fontName = NULL;exportInfo[i].overlayInfo[2].fontSize = 14;exportInfo[i].overlayInfo[2].fontColor = 0xFF;exportInfo[i].overlayInfo[2].fontBgColor = 0x00;exportInfo[i].overlayInfo[2].pictureOpacity = 100;

exportInfo[i].overlayInfo[3].type = PelcoAPI::OVERLAY_TYPE_TEXTSTRING;exportInfo[i].overlayInfo[3].location = PelcoAPI::OVERLAY_LOCATION_TOP_LEFT;exportInfo[i].overlayInfo[3].fontName = "Arial";exportInfo[i].overlayInfo[3].fontSize = 16;exportInfo[i].overlayInfo[3].fontColor = 0xA0;exportInfo[i].overlayInfo[3].fontBgColor = 0x00;exportInfo[i].overlayInfo[3].pictureOpacity = 0;

Pelco

Pelco SDK 72

• At this point determine if you want to associate any overlays to the video clips. If so, create and initialize any overlays to

associate with the video clip to export. In the example excerpt below, we have associated four previously created

OverlayInfo instances with two ExportInfo instances. (For further details please refer to the Setting Up Overlay Data on

Video to be Exported entry above.)

The example below can be found within the sample project itself.

Resetting Overlay Data



To reset overlay data to default values for the video being exported; call the ResetData method.

int i = 0;int clipNum = 2;int overlayNum = 4; PelcoAPI::ExportInfo * exportInfo = new PelcoAPI::ExportInfo[clipNum];

exportInfo[0].sDeviceID = "uuid:00047D01-4CA5-5370-6563-747261495605";// configure other export settings for the 1st clip to export

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 }

exportInfo[0].overlayInfo[3].value = TEXTSTRING; exportInfo[1].overlayInfo[3].value = TEXTSTRING_1;}

Pelco

Pelco SDK 73

Stitching Multiple Clips into a Single Video Export



Please note that enabling sequential stitching may or may not be much slower than exporting a

single video clip, depending on whether any of the clips need to be transcoded.

1. Determine the System Manager’s IP address. (Please refer to the Automatically Determining the System Manager’s

IP Address and Port Number entry in the Device & Service Discovery section for details.)

2. Initialize the Exporter. (Please refer to the Initializing the Exporter entry for details.)

3. If you would like to overlay data onto the resulting export, do so now. (Please refer to the Setting Up Overlay Data on

Video to be Exported and Setting Up a Multiple Video Clips to be Exported entries for details.)

4. Begin the video export by calling the Exporter’s StartExport method, passing in the following parameters:

• The fullpath including filename of the resulting exported video. (The format changes based on operating system.)

• The desired resulting video format for the export. Please refer to the EnduraExporterDefines header for the latest

options.

• An array of the ExportInfo instances, containing instances of OverlayInfo.

• The number of ExportInfo instances, one for each clip to stitch.

• A true value for the sequential stitch parameter.

bool bSuccess = exporter.ResetData();

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

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

Pelco

Pelco SDK 74

5. Constantly poll the status of the video export, until it is finished.

Exporting Video With Overlays



If you choose to embed overlays with your video export, regardless of input source

stream’s format, the resulting exported file will be in MPEG-4 format.


IP Address and Port Number entry in the Device Discovery section for details.)


3. If you would like to overlay data onto the resulting export, do so now. (Please refer to the Overlaying Data on VIdeo

to be Exported entry for details.)



• The UUID of the stream to export’s source

int clipCounter = 0;

while (clipCounter < clipNum){ int temp = 0; status = 0; while (status < 100 && status != -1) { temp = exporter.PollStatus(); if (temp != status) { status = temp; }

#ifdef WIN32 Sleep(100);#endif } ++clipCounter;}

Pelco

Pelco SDK 75


options.

• An instance of the ExportInfo class, containing instances of OverlayInfo.

• The starting time of the recorded video to export.

• The ending time of the recorded video to export.



bool bSuccess = exporter.StartExport("D:\\Video\\test123.mp4", "uuid:691fd745-006c-4fc9-9262-23c13e977ce4", PelcoAPI::CODEC_ID_MPEG4, "2010-01-11T22:10:35", "2010-01-11T22:11:15", true);



Pelco

Pelco SDK 76

Exporting Video Without Overlays




IP Address and Port Number entry in the Device Discovery section for details.)




• The UUID of the stream to export’s source


options.

• The starting time of the recorded video to export.

• The ending time of the recorded video to export.

• The videoOnly parameter: set to true to export only video, while setting this to false to include audio (if it is

available). If you want audio to be included, PEF is the only available export format.

• The UUID of the stream to export’s audio source, if separate from the video source of the export.


bool bSuccess = exporter.StartExport("D:\\Video\\test123.mp4", "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");

Pelco

Pelco SDK 77


Stopping a Video Export



When you want to force a video export that is currently in progress to stop, just call the StopVideoExport method.



bool bSuccess = exporter.StopExport();

Pelco

Pelco SDK 78

Web Service Proxies





stallation.



Latest+PDF+Revision




OverviewPelcoGSoap is a static linked library generated by gSOAP tools, based on the WSDL files from with minor modifications.

The PelcoGSoap library provides an interface for SOAP clients to make SOAP calls to Pelco devices. It accounts for

most issues regarding making SOAP calls to Pelco devices.


General Usage

1. Include the stdsoap2 header, and the web service proxy header. For example if you want to utilize the

CameraConfiguration web service, you should include the CameraConfiguration header.

#include "PelcoAPI/stdsoap2.h"#include "PelcoAPI/CameraConfigurationProxy.h"

Pelco

Pelco SDK 79







http://www.cs.fsu.edu/%7Eengelen/soap.html

http://www.cs.fsu.edu/%7Eengelen/soap.html

http://en.wikipedia.org/wiki/SOAP


2. Declare your web service proxy. In this case, it will be CameraConfigurationProxy.

3. Set the SOAP header.

4. Set the web service’s control point URL. For details on the proper way to retrieve the control point URL, please refer

to the Retrieving a Specific Web Service’s Control URL entry in the Device & Service Discovery section.

5. Create a new web service action request instance. In the below example, we create an instance of

CameraConfiguration’s ResetConfiguration data type. This will hold your request parameters for the web service

action Stop.

6. Create a new web service action response instance. In the below example, we create an instance of

CameraConfiguration’s ResetConfigurationResponse data type. This will hold the web service’s response including

related values to your request.

CameraConfigurationProxy CameraConfiguration;

pSoap->header = (struct SOAP_ENV__Header *) soap_malloc(CameraConfiguration, sizeof(struct SOAP_ENV__Header));

CameraConfiguration.soap_endpoint = strEndPointURL.c_str();

_CameraConfiguration__ResetConfiguration * pResetConfiguration = soap_new__CameraConfiguration__ResetConfiguration(&CameraConfiguration, -1);

_CameraConfiguration__ResetConfigurationResponse * pResetConfigurationResponse = soap_new__CameraConfiguration__ResetConfigurationResponse( &CameraConfiguration, -1);

Pelco

Pelco SDK 80

7. Call the CameraConfiguration web service proxy ResetConfiguration action, passing in both the earlier created

ResetConfiguration and ResetConfigurationResponse parameters. Then determine if the operation was successful.

CameraConfiguration.ResetConfiguration(pResetConfiguration, pResetConfigurationResponse);

#include "PelcoAPI/stdsoap2.h"#include "PelcoAPI/LensControlProxy.h"

#include "GSOAPSample.h"

using namespace PelcoAPI;

void GSOAPSample::StopLens() throw(){ LensControlProxy LensControl; std::string cameraAddress = "10.18.129.231"; std::string cameraPort = "49152"; pSoap->header = (struct SOAP_ENV__Header *) soap_malloc(LensControl, sizeof(struct SOAP_ENV__Header)); std::string strEndPointURL = "http://" + cameraAddress + (cameraPort.empty() ? "" : ":" + cameraPort) + "/control/LensControl-1"; LensControl.soap_endpoint = strEndPointURL.c_str(); _LensControl__Stop * pStop = soap_new__LensControl__Stop(&LensControl, -1); _LensControl__StopResponse * pStopResponse = soap_new__LensControl__StopResponse(&LensControl, -1); if (LensControl.Stop(pStop, pStopResponse) != SOAP_OK) { //Handle error }}

Pelco

Pelco SDK 81

Device & Service Discovery





stallation.

To check if this is the latest revision of the Pelco SDK 2.0 for C++ documentation, please visit

the following link: http://update.pelco.com/confluence/display/xdn/Latest+PDF+Revision

Once there, look for Pelco SDK 2.0 Programmers Guide


OverviewOne of the most basic tasks is to programmatically determine what devices and services are available on your network.

Where does the Pelco SDK fit?The key to performing device and service discovery related tasks is the System Manager Wrapper. The System Manager

Wrapper is a component of the Pelco SDK. It provides users with convenience functions for device and service queries.

Pelco

Pelco SDK 82





The majority of the tasks covered in this section can be found in the the System Manager Wrapper C++ sample project.

We assume that you’ll be examining the sample project source code while reading this documentation, which is highly

recommended.

For more Endura specific information, please refer to the Appendix.

Getting StartedNOTE: This entry assumes that users have already installed the Pelco SDK and that you have a System Manager on

your network.

To begin using the sample System Manager Wrapper sample project, locate it within your Pelco SDK Samples directory:


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

Pelco

Pelco SDK 83

Setting up the Working Directory

Next you will need to set the sample project’s

working directory. Assuming that you have

already opened the sample project in MS Visual

Studio, right click on the project and select the

the Properties menu item.

Pelco

Pelco SDK 84






What’s AheadThe following set of tasks are essential for using the Pelco SDK:

• Determine the System Manager’s IP address and port number, either manually or automatically through the Pelco SDK

• Create a class that implements the IDeviceStorageNet interface.

• Querying all available Pelco devices on your network

Pelco

Pelco SDK 85

Initializing the System Manager Wrapper

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

System Manager Wrapper C++ sample project.

Before we can perform any of the tasks associated with the System Manager Wrapper, we need to initialize an instance

of it. Moreover once we’ve finished the initialization, we’ll need to use it to login to the System Manager, since most

System Manager Wrapper methods require a login ID.

1. Declare and initialize the System Manager Wrapper. There are currently two methods to accomplish this. For details

on the first way, please refer to the Automatically Determining the System Manager’s IP Address entry above. The

second way is when System Manager’s IP address is already known in advance. Simply enter it into the

SetSMAddress method.

2. Now login into the System Manager with the proper credentials, call the System Manager Wrapper instance’s

UserLogin method, passing in the username and password. If successful it should return an ID of your login session.

Keep this in mind as this login ID will be used often.

NOTE: Once you’ve logged into the System Manager, you will eventually have to log out, by calling the System

Manager Wrapper instance’s UserLogout method, passing in your login ID as the parameter. When you have

finished all System Manager related operations, please log out of the System Manager. For more details on

authenticating to a Pelco system, please refer to the Logging in and Logging out entry.

Automatically Determining the System Manager’s IP Address and Port

Number



PelcoAPI::SystemManagerWrapper sm;

int nRet = sm.SetSMAddress((char *) sSMIPAddress);

int loginId = sm.UserLogin("brian", "pelco");

sysMgr.UserLogout(loginId);

Pelco

Pelco SDK 86

Initialize the System Manager Wrapper by calling its AutoDiscoverSM method to automatically determine the System

Manager's IP address and port number. The 120 parameter represents the duration before a timeout.

To access the System Manager’s IP address and port number, call the GetSMAddress method.

Logging in and Logging out



There will be many cases where you will need to both login and log out of the System Manager. To login into the System

Manager with the proper credentials, call the System Manager Wrapper instance’s UserLogin method, passing in the

username and password. If successful it should return an ID of your login session. Keep this in mind as this login ID will

be used often for many of the System Manager Wrapper’s methods.

Once you’ve logged into the System Manager, you will eventually have to log out, by calling the System Manager

Wrapper instance’s UserLogout method, passing in your login ID as the parameter. When you have finished all System

Manager related operations, please log out of the System Manager.

Querying Available Devices from the System Manager



NOTE: Before proceeding with this entry, it is assumed that the user has already completed the steps outlined in

the Creating an IDeviceStorage class entry in the Appendix.

The first major task that you need to complete is to able to query all Pelco devices available on your network. Completing

this enables you to have access to a device’s Unique Device Name (UDN) and a host of other device related attributes

that are needed for other Pelco SDK related tasks.

1. To begin, initialize the System Manager Wrapper. (Please refer to the Initializing the System Manager Wrapper entry

for details.)

int nRet = sm.AutoDiscoverSM(120);

sm.GetSMAddress("10.220.196.187", 60001);

int loginId = sm.UserLogin("brian", "pelco");

sysMgr.UserLogout(loginId);

Pelco

Pelco SDK 87

2. Make a call to the System Manager Wrapper's GetDevices method, passing in the following parameters:

• Your login ID: This ID is returned after a successful login. (Please refer to the Initializing the System Manager

Wrapper entry for details.)

• The sequence number: this is used to filter results, only returning newly added or changed devices. GetDevices

calls will return a new integer value for each successive call. New values will be 1 larger than the one before it e.g.

if the 1st call returned 1, then the subsequent call will return a 2.

• The device type you would like to use to filter the results. Known device types include the following:

• Camera

• Encoder

• Decoder

• Monitor

• a NULL value (to not filter results by type of device)

This is not a definitive list of Pelco device types. This list will expand as Pelco expands

its product line.

• A pointer to your IDeviceStorage implementation

3. Perform the needed operations on the returned device data and store them into your IDeviceStorage class instance.

Refer to the in the Creating an IDeviceStorage class entry for further details.

Querying Any Changes with Available Devices from the System Manager



NOTE: This entry assumes that you have already completed the steps outlined in the Querying Available Devices From

the System Manager entry above.


2. Simply use the returned sequence number value from your last call to the GetDevices method, with your next call to

the same method.

int seqNum = 0;MyStorage storage; // ... You must define this class ...int loginId = sm.UserLogin("brian", "pelco");

sm.GetDevices(loginId, &seqNum, "Camera", &storage);

Pelco

Pelco SDK 88

This time it will only return Pelco devices that have either changed or are new to the network. Every subsequent call

will only any new changes within your network.

Retrieving the SM’s Time Zone



To determine your System Manager’s current time zone, do the following:


2. Call the System Manager Wrapper’s GetSystemAttribute method, passing in the following parameters:



• The time zone attribute’s ID: SYS_CFG_TzInfo

• A pointer to your time zone variable

Retrieving the Network Time Server Address



You need to determine your network’s network time server’s IP Address.



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

PelcoAPI::xstring sTimezoneInfo;int loginId = sm.UserLogin("brian", "pelco");

bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo", &sTimezoneInfo);

Pelco

Pelco SDK 89



• The attribute’s ID of SYS_CFG_NtpAddr

• A pointer to your time zone variable

Retrieving a Web Service’s ID




the System Manager entry, which provides you with UDNs for Pelco devices available on your network.


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






• The name of desired web service, which in this case is VideoOutput


PelcoAPI::xstring sNtpAddress;int loginId = sm.UserLogin("brian", "pelco");

bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr", &sNtpAddress);

PelcoAPI::xstring sServiceId;int loginId = sm.UserLogin("brian", "pelco");

bool bSuccess = sm.GetServiceID(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "VideoOutput", &sServiceId);

Pelco

Pelco SDK 90

Retrieving a Specific Web Service’s Control URL





This will show you how to get a web service’s control URL, which is essential for many Pelco related operations.


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

• You login ID: This ID is returned after a successful login. (Please refer to the Initializing the System Manager





• The target web service’s ID (Please refer to the Retrieving a Web Service’s ID entry for details.)

• The control URL attribute’s ID: SYS_UpnpControlUrl

• A pointer to the variable that will store the result of the web service control URL

Retrieving the NVR Associated with the Device





If you ever need to figure out which NVR your IP camera is linked to, complete the following steps:


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

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

Pelco

Pelco SDK 91






• The NVR association attribute’s ID: SYS_NvrAssoc


Retrieving the Device’s Friendly Name





There are two major ways for determining a device’s friendly name. The first is to simply parse through the results of a

GetDevices method call, which includes both the device UDN and its accompanying attributes. The second way is done

by following these steps:








• The attribute name of SYS_UpnpFriendlyName


PelcoAPI::xstring sNvr;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc", &sNvr);

Pelco

Pelco SDK 92

Retrieving the Device’s Device Description File (DDF) URL



What is DDF? The Device Descriptor File (DDF) is file containing device related data such as manufacturer, model name,

and so on, in XML format. To get the location of a specific device’s DDF, do the following:








• The attribute ID of SYS_UpnpDevDescUrl


Retrieving All Web Services Available on a Device



To show all available web services on a particular Pelco device, do the following steps:


PelcoAPI::xstring sFriendlyName;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpFriendlyName", &sFriendlyName);

PelcoAPI::xstring sFriendlyName;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpDevDescUrl", &sServiceId);

Pelco

Pelco SDK 93

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



• The sequence number: This has the same function as other Pelco query methods, in that it can help limit the

results to only new or changed items. This makes sense for querying devices on a network. However, a device’s

available web services does not change very often if at all without a new firmware update. Therefore, this value

should almost always be a 0.





Retrieving a Device’s Attribute




the System Manager entry in the Device & Service Discovery section, which provides you with UDNs for Pelco devices

available on your network.

Device attributes are values that describe the device in some way such as its model number or its model name. The

following are the most common device attributes:

SYS_UpnpPelcoDeviceUdn: A Pelco device’s Unique Device Name (UDN); a special device identifier for networks

SYS_UpnpFriendlyName: A more human readable version of the device’s name.

SYS_UpnpDeviceType: A URN that denotes the device’s category.

SYS_UpnpDevDescUrl: This shows the location of the device’s UPnP Device Descriptor File (DDF).

SYS_UpnpSerialNumber: The device’s serial number

SYS_UpnpModelNumber: The device’s model number

SYS_UpnpModelDescription: A more detailed description of the device.

int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm. GetServiceInfoSync(loginId, 0, "uuid:00047D01-4CA5-5370-6563-747261495605", &storage);

Pelco

Pelco SDK 94

SYS_UpnpManufacturerUrl: The device manufacturer’s website.

SYS_UpnpModelName: The device’s model name.

This outlines the steps needed to return a specific device attribute:








• The name of the device attribute to query


Retrieving a System Manager’s Attribute



A System Manager’s attributes are similar to a generic Pelco device’s attributes, except in my most cases a System

Manager attribute is exclusive to Pelco System Managers. If you aren’t familiar with device attributes, System Manager

attributes are simply values that describe the System Manager in some way such as its current time zone or its current

security mode. The following are the more common System Manager attributes:

SYS_CFG_NtpAddr: this value is used to indicate the location at which the NTP server (if any) can be located. The

expected value is an IP address.

SYS_CFG_SecMode: This value is used to identify the system's current security mode.

SYS_CFG_SmtpAddr: This value is used to indicate the location at which the SMTP server (if any) can be located. The

expected value is an IP address.

SYS_CFG_TzInfo: This value is used to report time zone information. This value is comma delimited (without

whitespace). The following describes each number in the order they appear in the comma delimited list (ex.

1205056800,60,480):

PelcoAPI::xstring sModelNumber;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetDeviceAttributeValue(loginId, "uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpModelNumber", &sModelNumber);

Pelco

Pelco SDK 95

• Change Time: This number is the absolute daylight savings time (in time_t time() seconds). If this value is zero, there is

no daylight savings time for the time zone and nothing will have to be done to support daylight savings. If the value is

non-zero, the time zone does support daylight savings time. In this case, if the value is negative, the time value is being

used to indicate the time to turn off daylight savings time. If the value is positive, the value is being used to indicate the

time at which daylight savings time is to be turned on.

• DST Offset: This number is the number of minutes to adjust the time when daylight savings time is in affect. The offset

should be added to the GMT time after adding the GMT offset (see next value).

• GMT Offset: This value indicate the number of minutes to adjust the GMT time in order to get the local time (this is the

minutes "west" of the GMT). To get the current local time, simply add this number of minutes to the current GMT time.

SYS_CFG_UPNP_RENEWAL: The UPnP renewal value in seconds. The default setting is 1800 seconds (30 min).

SYS_CFG_UserLanguage: This value is used to indicate the default user language.

To determine a particular attribute value on your System Manager, do the following:





• The name of the System Manager attribute: in this case it’s SYS_CFG_TzInfo

• A pointer to the variable that will hold the result

Retrieving a Web Service’s Attribute




the System Manager entry in the Device & Service Discovery section, which provides you with UDNs for Pelco devices

available on your network.


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

int iUpnpRenewal;int loginId = sm.UserLogin("brian", "pelco");bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL", &iUpnpRenewal);

Pelco

Pelco SDK 96

• You login ID: This ID is returned after a successful login. (Please refer to the Initializing the System Manager





• The target web service’s ID (Please refer to the Retrieving a Web Service’s ID entry for details.)

• The name of the web service’s attribute to query

• A pointer to the variable that will store the result

Creating a IDeviceStorage Class



What is the IDeviceStorageNet class? An IDeviceStorageNet is simply an interface that parses XML responses from the

System Manager and stores the resulting device data from the XML response internally. Users need an

implementation of this interface, if they wish to manage device data using the System Manager Wrapper. An

IDeviceStorageNet class must implement the following methods:

virtual bool AddDevice(const char* sUDN, const char* sAttributes): This method 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 existing device within IDeviceStorageNet.


virtual bool UpdateDevice(const char* sUDN, const char* sAttributes): This method updates an existing device within

IDeviceStorageNet.

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

Pelco

Pelco SDK 97


• The devices’s attributes, given as XML

The System Manager Wrapper will use these methods every time you call its GetDevices method; which in turn will

update your IDeviceStorage instance contents.

The System Manager Wrapper sample project should have an implementation of IDeviceStorage called MyStorage.

MyStorage is a stub class. It does not implement anything that is essential for production usage such as parsing the

SM’s XML response data (attributes). Nor does it associate the device UDN / attribute XML pairs into any constructs.

Those exercises are left to the user.

#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

Pelco

Pelco SDK 98

Appendix: Product Compatibility

Product Event

Arbiter

Event

Manager

Exporter Meta-data

Parser

Pelco API

Viewer

PTZ Control

Wrapper

SM Wrapper

DX Video

RecordersN N N N N N N

Digital Sentry N N N N N N N

DVR5100 Y Y Y Y Y Y2 Y

Endura

ExpressY Y1 Y1 Y Y Y2 Y1

IP110 Y Y1 N Y Y Y Y1

IP3701 Y Y1 N Y Y N Y1

NET5301R Y Y1 N Y Y N Y1

NET5402R-HD Y Y1 N Y Y N Y1

NET5301T Y Y1 N Y Y Y2 Y1

NET5308T Y Y1 N Y Y Y2 Y1

NET5301T-I Y Y1 N Y Y Y2 Y1

NET5400T-I Y Y1 N Y Y Y2 Y1

NSM5200 Y Y1 Y1 Y Y Y2 Y1

Sarix Y Y1 N Y Y N Y1

Spectra HD Y Y1 N Y Y Y Y1

Spectra IV IP Y Y1 N Y Y Y Y1

Spectra Mini Y Y1 N Y Y Y Y1

SM5000 Y Y N Y N Y2 Y

1. This is only active if there is an active System Manager on the network.

2. This is only active if the attached IP camera is PTZ capable.

Pelco

Pelco SDK 99

Appendix: Endura

OverviewIn 2005, Endura provided a distributed architecture that delivered both flexibility and performance. Endura is a complete solution for high definition video encoding, recording, and display. It controls the origination, transport, recording, and display of integrated, security-related audio and video.

From a technical standpoint, what defines an Endura system?

System Manager + Endura Devices = Endura System

System Manager (SM)First and foremost, an Endura system must have a System Manager (SM). The SM is the heart of Endura. It is responsi-ble for the following:• Managing devices such as cameras, decoders, and NVRs, including administering rights and privileges• Storing device information, like status • Administering users, which includes permissions management• Logs errors and alarms• Security key management

Endura DevicesEndura devices can be defined as IP cameras, encoders, decoders, NVRs, or even work stations. Each Endura device, including the SM itself, has an Application Programming Interface (API). An API is simply a specified way for software clients to programmatically communicate with Endura devices, allowing access to their functionality. All Endura devices provide an API through a set of related web services. These web services adhere to the SOAP standard. (For more de-tails on SOAP, please refer to the following http://en.wikipedia.org/wiki/SOAP.) It is beyond the scope of this documenta-tion to fully describe all Endura web services. For details, such as the SOAP web service API reference, please refer to the Pelco Developer Network (PDN) at http://pdn.pelco.com.

One of the main purposes of a System Manager is to provide a central place to retrieve information on all Endura de-vices. How does the System Manager collect all of this information?

Pelco

Pelco SDK 1





1. The System Manager constantly provides a broadcast of its location on the Endura Network. Once a device comes

online, it will listen for this broadcast. When the new device finds the SM, it will then register itself to the System

Manager.

2. At some point the System Manager will query the device’s available web services and its attributes, using a variety of

sources including the UPnP Device Description File (DDF). DDFs are files containing device attributes in XML format.

3. After the initial query, the System Manager will periodically update the device’s status. To be considered online, a

device must constantly notify the SM that it is still ‘alive’.

4. At any point a client can make requests to the System Manager regarding devices, including the SM itself, and their

web services.

Endura Events and AlarmsThere are two major ways to subscribe to Endura web service events:• Directly contacting the device on which the target web service resides

• Using the System Manager as an intermediary to perform actual eventing related work

On newer Endura network deployments, the first option is default. Users can enable the System Manager to act as a middle man by enabling its EventArbiter web service (not to be confused with the Event Arbiter Library). The EventArbiter

Pelco

Pelco SDK 2

web service is used for receiving GENA events from devices within an Endura network. The Event Arbiter provides two ways for subscribing to events:

The first way is through control URLs

The second method involves subscribing to events with event URIs provided

Pelco

Pelco SDK 3

The URI is provided by the user through the System Manager's EventArbiter service, made possible by implementing the

PelcoAPI::IEventAgent interface.

What is the advantage of using the System Manager as an intermediary for Endura events? The System Manager can help manage all event related network traffic, ensuring that an Endura network never gets overwhelmed by eventing net-work traffic.

Video ExportsCurrently the Exporter library requires a System Manager present in order to function. How does it work? The Exporter

client sends its request for video clips to export with a timestamp range filter to the System Manager; that is it wants clips

Pelco

Pelco SDK 4

that fall within a starting date time and an ending date time. The System Manager will then query all available NSMs for

clips that meet both the starting timestamp and the beginning timestamp. Specifically there may be instances where the

System Manager will have to ‘stitch’ the end result from more than one NSM source of video clips in order to meet the

filter.

Where does the Pelco API SDK fit within Endura?The Pelco API SDK is meant to make using Endura web services easier by providing convenience methods and utilities. It protects the user from all of the potentially overwhelming and complicated details of Endura SOAP web services. Of course users are still free to directly use Endura web services. However Pelco has found that many of our customers enjoy the convenience and ease of use that the Pelco API SDK provides.

Pelco

Pelco SDK 5

Appendix: General Event Messages

LoggableEventThis defines the general structure of logged data for events. It does not have a set of enclosing tags. For further details,

please refer to the event message descriptions below.

deviceUdn: The unique device name. ex. uuid:AK-2

deviceUrn: The device's resource name. ex. 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

LoggableEventParametersThis contains a list of LoggableEventParameter data types. For further details, please 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"/>

Pelco

Pelco SDK 6

parameter: A LoggableEventParameter data type.

LoggableEventParameterThis represents a event related parameter. For further details, please refer to the event message descriptions below.

paramId: The parameter's unique identifier.

name: The parameter's name.

value: The parameter's value.

type: The parameter's type identifier.

<complexType name="LoggableEventParameters"> <sequence> <element minOccurs="0" maxOccurs="unbounded" name="parameter" type="tns:LoggableEventParameter"/> </sequence></complexType>

<complexType name="LoggableEventParameter"> <sequence> <element name="paramId" type="xs:int"/> <element name="name" type="xs:string"/> <element name="value" type="xs:int"/> <element name="type" type="xs:int"/> </sequence></complexType>

Pelco

Pelco SDK 7

Appendix: Hardware Diag-nostics Event Messages

ConfigurationButton (20180)This event triggers if the front panel configuration button has failed.

PdDiagnosticThis is the data subscribers will receive when the event triggers.

objGuid: The event's Universally Unique Identifier. The value must be set to '394af82c-2b05-4df8-b2a6-2caed9ad4fae'.

objId: The event's unique database identifier. The value must be '20180'.

current: The current state of the button. Possible values are:

• 1 for BUTTON_CONFIG: The button is in "Configuration mode".

• 2 for BUTTON_REBOOT: The button is in "Reboot system".

• 3 for BUTTON_RESET: The button is in "Reset configuration".

• 4 for BUTTON_NORMAL: The button currently does not have a state.

previous: The previous state of the button. For possible values, please refer to current.

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

Pelco

Pelco SDK 8

LoggableEvent ObjectFor more details please refer to the LoggableEvent entry above.

DriverFailure (20150)A DriverFailure PdDiagnostic object is only sent when a device's driver fails, so a LoggableEvent object is to set the

correct major, minor, type, and reason. This is typically used for multi-channel encoder (MCE) devices.


objGuid: The event's Universally Unique Identifier. The value must be set to '94b6d2d3-

c68e-4b13-974a-08f69f50cb67'.

<pdDiagnostic> <objGuid>394af82c-2b05-4df8-b2a6-2caed9ad4fae</objGuid> <objId>20180</objId> <current>1</current> <previous>3</previous> </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>4</type> <reason>1</reason> <parameters></parameters>

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

Pelco

Pelco SDK 9

http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-LoggableEvent


http://en.wikipedia.org/wiki/UUID



name: The name of the device driver.


Fans (20020)Any device with any fans having a changed state will have a LoggableEvent fired.


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


Pelco

Pelco SDK 10



objGuid: The event's Universally Unique Identifier. The value must be set to '31e41907-53be-4f57-8ae2-

a56c12d98d0e'.


states: A FanStates data type.

FanStatesThis contains list of one or more FanState date types.

state: A FanState data type.

FanStateThis represents the current and previous condition of a fan.

cur: The current state identifier. Possible values are the following:

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

<complexType name="FanStates"> <sequence> <element name="state" maxOccurs="unbounded" minOccurs="1" type="tns:FanState"/> </sequence></complexType>

<complexType name="FanState"> <sequence> <element name="cur" type="xs:int"/> <element name="prev" type="xs:int"/> </sequence></complexType>

Pelco

Pelco SDK 11

• 1 for FAN_OK: The fan is operating normally.

• 2 for FAN_FAILED: The fan has failed.

• 3 for FAN_UNKNOWN: The state of the fan is currently unknown; this fan does not have an initial state registered.

NOTE: This will always be the final stream state.

prev: The previous state identifier. This has the same possible values as cur.


<pdDiagnostic> <objGuid>31e41907-53be-4f57-8ae2-a56c12d98d0e</objGuid> <objId>20220</objId> <states> <state> <cur>1</cur> <prev>0</prev> </state> <state> <cur>0</cur> <prev>0</prev> </state> <state> <cur>0</cur> <prev>0</prev> </state> </states> </pdDiagnostic>


Pelco

Pelco SDK 12

HardDrives (20060)For each CPdDiagHarddrives object we send loggable events for hard drives that have a state change. Set the state of

the hard drive to the appropriate major, minor, type, and reason.


objGuid: The event's Universally Unique Identifier. The value must be set to '31e41907-53be-4f57-8ae2-

a56c12d98d0e'.


states: A HardDrivesStates data type.

HardDrivesStatesThis contains list of one or more HardDrivesState date types.

state: A HardDrivesState data type.

HardDrivesStateThis represents the current and previous condition of a hard drive.

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

<complexType name="HardDrivesStates"> <sequence> <element name="state" maxOccurs="unbounded" minOccurs="1" type="tns:HardDrivesState"/> </sequence></complexType>

Pelco

Pelco SDK 13



http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-HardDrivesStates

http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-HardDrivesStates

cur: The current state identifier. Possible values are the following:

• 1 for HDS_READY: Indicates that the hard disk is currently in use. NOTE: This may indicate a problem if the disk is

known to be currently NOT in use.

• 2 for HDS_ONLINE: Indicates that a disk is online and currently being used.

• 3 for HDS_FAILED: Indicates that a disk has failed.

• 4 for HDS_HOTSPARE: Indicates that a disk is currently being used as a 'hot spare' within the array.

• 5 for HDS_REBUILD: Indicates that a disk is currently being rebuilt.

• 6 for HDS_NONE: Shows that there is currently no hard drive connected, and there is room for a hard drive.

• 7 for HDS_UNKNOWN: The hard drive's state is currently unknown; this typically means that the hard drive has yet to

register any state. NOTE: This will always be the final stream state.

prev: The previous state identifier. This has the same possible values as cur.

<complexType name="HardDrivesState"> <sequence> <element name="cur" type="xs:int"/> <element name="prev" type="xs:int"/> </sequence></complexType>

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

Pelco

Pelco SDK 14


ImproperShutdown (20070)A ImproperShutdownPdDiagnostic object is sent when an improper shutdown occurs, so a LoggableEvent object can be

initialized with the appropriate major, minor, type, and reason data.


objGuid: The event's Universally Unique Identifier. The value must be set to 'a44945e0-fa54-4fb0-a614-2e71886c508f'.


mode: The mode of the shutdown.

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

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

Pelco

Pelco SDK 15

http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-ImproperShutdownPdDiagnostic

http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-ImproperShutdownPdDiagnostic






LinkSpeed (20200)This event triggers when the link speed changes. We then set the correct major, minor, type, and reason for

LoggableEvent. The current LinkSpeed is sent as a parameter with the LoggableEvent object.


<pdDiagnostic> <objGuid>a44945e0-fa54-4fb0-a614-2e71886c508f</objGuid> <objId>20070</objId> <mode>4</mode> </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>

Pelco

Pelco SDK 16





objGuid: The event's Universally Unique Identifier. The value must be set to 'b9359885-711a-4d71-

b908-4bdf8753dbe8'.

objId: The device's unique database identifier. The value must be '20200'.

min: The minimum link speed. ex. 100

cur: The current state. ex. 1


PowerSupply (20120)A PowerSupplyPdDiagnostic object is sent when an improper shutdown occurs, so a LoggableEvent object can be

initialized with the appropriate major, minor, type, and reason data.

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

Pelco

Pelco SDK 17



http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-PowerSupplyPdDiagnostic

http://update.pelco.com/confluence/display/xdn/Event+Messages#EventMessages-PowerSupplyPdDiagnostic


objGuid: The event's Universally Unique Identifier. The value must be '26f051aa-009b-4a5d-ab20-09b064a07a52'.


inAlarm: This represents whether or not a device is in a problem state. Possible values are:

• 0 for the power supply is operating properly; not in an alarm state.

• 1 for problems with the power supply; in alarm state.


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

<pdDiagnostic> <objGuid>26f051aa-009b-4a5d-ab20-09b064a07a52</objGuid> <objId>20120</objId> <inAlarm></inAlarm> </pdDiagnostic>


Pelco

Pelco SDK 18



UPS (20170)This event triggers if a UPS either fails or runs out of power.


objGuid: The event's Universally Unique Identifier. The value must be 'e746c2c8-0b97-402e-abc3-c784890c8d99'


cur: The current state identifier. ex. 4

pre: The previous state identifier. ex. 1


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

<pdDiagnostic> <objGuid>e746c2c8-0b97-402e-abc3-c784890c8d99</objGuid> <objId>20170</objId> <Cur>4</Cur> <Pre>1</Pre> <Rem>0</Rem> </pdDiagnostic>

Pelco

Pelco SDK 19



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

Pelco

Pelco SDK 20

Appendix: Software Diag-nostics Event Messages

DataLoss 20040When this is trigger by a data loss, we set the correct major, minor, type, reason for the LoggableEvent.


objGuid: The event's Universally Unique Identifier. The value must be '94b6d2d3-c68e-4b13-974a-08f69f50cb67'.


LoggableEvent objectFor more details please refer to the LoggableEvent entry above.

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

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

Pelco

Pelco SDK 21

InputStreams 20160For each stream entry that has its state changed from previous state, we send out a loggable event with appropriate

major, minor, type and reason.

objGuid: The event's Universally Unique Identifier. The value must be '31e41907-53be-4f57-8ae2-a56c12d98d0e'.


entries: A InputStreamsEntries data type.


<complexType name="InputStreams"> <sequence> <element name="objGuid" type="xs:string" fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/> <element name="objId" type="xs:int" fixed="20160"/> <element name="states" type="tns:InputStreamsEntries"/> </sequence></complexType>

Pelco

Pelco SDK 22

InputStreamsEntriesA list of InputStreamsEntry data types.

entry: A InputStreamsEntry data type.

InputStreamsEntry

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

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

Pelco

Pelco SDK 23

id: The entry's unique identifier ex. is2

mediaType: A media type identifier ex. 0

hardwareId: A hardware identifier ex. hwidv1

stateCur: The current state identifier. Possible values are:

• 1 for ISS_RECORDING — Currently recieving a stream and it is being recorded.

• 2 for ISS_RECORD_ERROR — Currently recieving a stream, but it is unable to be recorded due to an error.

• 3 for ISS_RECEIVING — Currently recieving a stream.

• 4 for ISS_RECEIVE_ERROR — Unable to receive a stream.

• 5 for ISS_MISSING — Expecting a stream but there is no available stream. In analog inputs, this means the device is

unable to detect a connection.

• 6 for ISS_UNKNOWN — The state of the stream is currently unknown; this stream does not have an initial state

registered. NOTE: This will always be the final stream state.

statePrev: The previous state identifier. Please refer to 'stateCur' for possible valid values.


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

Pelco

Pelco SDK 24

PacketLoss 20080This event is fired when there is data loss during video data writing. Sets the appropriate major, minor, type, and reason

in Loggable Event.


<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>3</reason> <parameters> <param> <paramId>9</paramId> <name>Id</name> <value>1</value> <type>1</type> </param> <param> <paramId>10</paramId> <name>MediaType</name> <value>1</value> <type>1</type> </param> <param> <paramId>11</paramId> <name>HardwareId</name> <value>hwaid1</value> <type>0</type> </param> <param> <paramId>12</paramId> <name>ChannelId</name> <value></value> <type>0</type> </param> </parameters>

Pelco

Pelco SDK 25

objGuid: The event's Universally Unique Identifier. The value must be 'ddfa09d6-64f1-4b39-a7e7-de0c5f7780cc'.


max: The maximum acceptable packet loss percentage. ex. 1.1235

cur: The current packet loss percentage. ex. 5.1235


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

<deviceUdn>uuid:AK-2</deviceUdn> <deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn> <serviceUrn></serviceUrn> <logId></logId> <major>7</major> <minor>0</minor> <type>11</type> <reason>0</reason> <parameters> <param> <paramId>3</paramId> <name>PercentageOfCurrentPacketLoss</name> <value>5.1235</value> <type>0</type> </param> </parameters>

Pelco

Pelco SDK 26



SEBs 20210For each PdDiagSebs object we send loggable events only when a particular SEB has its state changed. Set the state of

the SEB to the appropriate major, minor, type, and reason.


objGuid — The event's Universally Unique Identifier. The value must be '31e41907-53be-4f57-8ae2-a56c12d98d0e'.

objId — The event's unique database identifier. The value must be '20210'.

entries — A SEBsEntries data type.

SEBsEntriesA list of SEBsEntry data types.

entry: a SEBSEntry data type.

SEBsEntry

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

<complexType name="SEBsEntries"> <sequence> <element name="entry" maxOccurs="unbounded" minOccurs="1" type="tns:SEBsEntry"/> </sequence></complexType>

Pelco

Pelco SDK 27

stateCur: The current state identifier.

statePrev: The previous state identifier. Please refer to stateCur for valid possible values.

id: (attribute) the entry's identifier - string.


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

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

Pelco

Pelco SDK 28

StorageFull 20190When this event triggers from a device with fully used storage, we set the appropriate major, minor, type, and reason in

the Loggable event.


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 for storage is not full; not in an alarm state.

• 1 for full storage; in alarm state.

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

<complexType name="StorageFullPdDiagnostic"> <sequence> <element name="objGuid" type="xs:string" fixed="94b6d2d3-c68e-4b13-974a--08f69f50cb67"/> <element name="objId" type="xs:int" fixed="20190"/> <element name="inAlarm" type="xs:int"/> </sequence></complexType>

Pelco

Pelco SDK 29


StorageTime 20130This event is fired if the NVR/DVR is unable to achieve the user configured video storage time.


<pdDiagnostic> <objGuid>3df223ee-8041-4c1a-be77-2d140e5588aa</objGuid> <objId>20190</objId> <inAlarm></inAlarm> </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>13</type> <reason>0</reason>

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

Pelco

Pelco SDK 30

objGuid: The event's Universally Unique Identifier. The value must be 'e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0'


min: The minimum number of hours of storage time allowed.

cur: The current number of hours of storage time available.


Temperature 20140A Temperature PdDiagnostic object is triggered when temperature goes beyond specific range. The current range is set

between 10°C - 50°. This verifies if the current temperature is below minimum or above maximum threshold, and then

determine whether to send Loggable events; with reason set to either LOW and HIGH accordingly.

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

Pelco

Pelco SDK 31


objGuid: The event's Universally Unique Identifier. The value must be '26f051aa-009b-4a5d-ab20-09b064a07a52'.


min: The minimum allowable temperature.

max: The maximum allowable temperature.

cur: The current temperature.


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

<pdDiagnostic> <objGuid>7448f68a-de77-4ea9-b000-65b63bf54bd5</objGuid> <objId>20140</objId> <min>10</min> <max>20</max> <cur>5</cur> </pdDiagnostic>

Pelco

Pelco SDK 32



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

Pelco

Pelco SDK 33

Change History

This highlights major content changes.

Date Section(s) Change Summary

10/7/2010 Events & Alarms Removed irrelevant event messages.

10/7/2010 Events & Alarms

Device & Service

Discovery

Adds more references to the requirement for a System Manager for both the

Event Manager and System Manager Wrapper.

10/05/2010 Video Export Added export overlay issue regarding MPEG-4.

10/05/2010 Appendix Changed Headings for event message reference section, and split into new

sections by type of event message

10/04/2010 Appendix Add event message reference

9/28/2010 Exporting Video Added dateformat and timeformat enum definitions because API reference

failed to generate.

9/27/2010 Exporting Video Elaborated on export info settings.

9/27/2010 Exporting Video Elaborated on overlay settings.

9/27/2010 Exporting Video Separated out clip export settings from overlay settings initialization.

9/23/2010 Scripting Added notes where you can find the full source for scripting entries.

9/23/2010 Exporting Video Added a separate Initializing the Exporter entry.

9/23/2010 All Added more details for the plugin directory,

9/23/2010 All Removed dead links to the SDK API reference entries

9/21/2010 Appendix Added product compatibility matrix.

09/20/2010 Video Export Fixed video export entries and added a new one.

09/20/2010 All Grammar and spelling corrections

09/17/2010 Appendix Removed API reference content into separate Doxygen PDFs

Displaying & Controlling

Streams

Adding separate entries for starting live and playback streams

Panning & Tilting Update Panning and Tilting content to reflect API changes

Appendix Separated API reference from the main document.

09/08/2010 Appendix Removed user and role related API references

09/06/2010 Eventing Changed Event Arbiter sample references

09/04/2010 Meta-data Changed description of some enums to “system reserved values”

Pelco

Pelco SDK 34


09/04/2010 All Made parameters more clear with either explicit strings or declarations added

09/01/2010 Appendix Re-inserted Endura related content

09/01/2010 Changed documentation title

All Removed Misc Tasks section. Readers had to backtrack too often for

common tasks.

All Removed unnecessary references to the System Manager

All Grammatical fixes

All Removed more references to Endura

Legal Removed Mono

08/09/2010 P2-3 Changed introduction. Removed References to Endura

08/09/2010 All Fixed page numbers

Meta-data Added to Meta-data overview

Appendix Update PTZ Control Wrapper API - corrected rotational z and translational xyz

Panning & Tilting Updated PTZ tutorials

08/04/2010 Device & Service

Discovery

Fixed SM language for determining IP

08/03/2010 Appendix Added PTZ Control Wrapper API

08/03/2010 Appendix Added Endura Exporter API

08/03/2010 Appendix Added Meta-data Parser API

08/03/2010 Appendix Added Event Manager API

08/03/2010 Appendix Added Event Arbiter API

08/02/2010 Eventing Elaborated on event handling entry

08/02/2010 Appendix Added SM Wrapper API reference

Added interim Getting Started entries

Exporting Video Added Exporter C++ samples

Meta-data Added Meta-data C++ samples

Appendix Added Retrieve Web Service Attribute Entry

Appendix Added Retrieve SM Attribute Entry

Appendix Replaced device C# samples (and related content) with C++

Replaced user & role C# samples (and related content) with C++

Appendix Move Creating Attribute, Role, and User Class entries to the Appendix

Eventing Added Event Manager content

Eventing Added Endura eventing intro content

Eventing Reverted Event Manager back to Event Arbiter Lib

Replaced eventing C# samples (and related content) with C++

Viewing Streams Created more content on stream playback

Appendix P2 Creating a StreamParameters Class entry moved to Appendix

New Section Magnification, Zoom, Focus and Iris Control section added

New Section Panning and Tilting section added

Pelco

Pelco SDK 35


07/05/2010 Multiple Sections Replace sections focused on API SDK components with sections focused on

tasks.

Appendix P1 Moved Creating an IDeviceStorageNet class entry into the Appendix

07/07/2010 Replaced SM Wrapper with System Manager Wrapper.

06/24/2010 Event Manager P1- Changed section title, content, and diagrams from Event Arbiter Library to

Event Manager

06/24/2010 Pelco API Viewer P9-34 Overhauled Pelco API Viewer Usage content

06/24/2010 Pelco API Viewer P6 Added ActiveX COM registration instruction

Pelco

Pelco SDK 36

Documents

Pelco SDK 2.0 Programmers Guide for C++