Pelco API Programming Manual

Pelco SDK 3.

PROGRAMMING
C5617M-C
12/2012
Contents | Pelco SDK
Contents
Chapter 1: Introduction............................................................................... 6
Getting Started with the Pelco SDK.................................................................................................... 6
General Requirements......................................................................................................................... 8
Installing the Pelco SDK......................................................................................................................9
System Environment Settings for the Pelco SDK............................................................................... 9
Including Required SDK Components For Your Application............................................................. 10
Setting Up Sample Projects.............................................................................................................. 10
Registering the ActiveX Control..............................................................................................10
Adding References to Managed Libraries for C#................................................................... 11
Chapter 2: Object Model........................................................................... 16

Overview.............................................................................................................................................16
Device Caching.................................................................................................................................. 16
Samples..............................................................................................................................................17
Chapter 3: Displaying and Controlling Video Streams.......................... 21

Overview.............................................................................................................................................21
Initializing the Pelco API Viewer (C++)............................................................................................. 21
Initializing the Pelco API Viewer (C#)............................................................................................... 22
Using the PelcoAPIViewer Component.................................................................................. 23
Using the PelcoAPIMPFViewerControl Component............................................................... 23
Setting Size and Position of Video Display Area.............................................................................. 24
Querying an RTP Stream.................................................................................................................. 25
Opening, Playing, and Displaying a Live or Playback RTP Stream..................................................26
Opening, Playing, and Displaying an RTSP Stream......................................................................... 28
Forward Playback of RTP and RTSP Streams................................................................................. 29
Reverse Playback of RTP and RTSP Streams.................................................................................29
Fast Forward / Reverse Playback of RTP and RTSP Streams.........................................................29
Pausing RTP and RTSP Playback Streams..................................................................................... 30
Frame Forward Playback of the RTP Stream................................................................................... 30
Frame Reverse Playback of the RTP Stream...................................................................................31
Resuming the RTP or RTSP Stream from a Paused State.............................................................. 31
Stopping the RTP and RTSP Stream................................................................................................31
Start Manual Recording of RTP Stream........................................................................................... 32
Stop Manual Recording of RTP Stream............................................................................................32
Setting Audio Volume of a Live or Playback RTP stream.................................................................33
Displaying Analytic Events for an RTP Stream.................................................................................33
Displaying Motion Events for an RTP Stream...................................................................................33
Displaying a Timestamp Overlay for RTP and RTSP Streams......................................................... 33
Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams...................................35
Pan, Tilt, Zoom (PTZ) Control for RTP Stream Using PelcoAPIViewer............................................ 35
Chapter 4: Pan, Tilt, Zoom (PTZ) Control................................................36

Overview.............................................................................................................................................36
Initializing the PTZ Control Wrapper................................................................................................. 36
Continuous Panning...........................................................................................................................38
2
Pelco SDK | Contents
Continuous Tilting.............................................................................................................................. 39
Continuous Diagonal Movement........................................................................................................39
Stopping Continuous Movement........................................................................................................40
Enabling Continuous Pan/Tilt/Move and Zoom APIs via UDP Instead of TCP................................. 40
Panning to a Specific Position...........................................................................................................41
Tilting to a Specific Position.............................................................................................................. 41
Moving to a Specific Position............................................................................................................ 42
Moving to a Position Relative to the Current Location......................................................................42
Getting the Camera’s Current Position..............................................................................................43
Managing the Magnification (Zoom) Value........................................................................................43
Managing the Focus Value................................................................................................................ 44
Iris Control..........................................................................................................................................45
Scripting..............................................................................................................................................46
Creating a Preset...............................................................................................................................47
Updating an Existing Preset.............................................................................................................. 47
Creating a Pattern..............................................................................................................................47
Going to an Existing Preset...............................................................................................................48
Removing an Existing Preset............................................................................................................ 48
Updating an Existing Pattern............................................................................................................. 49
Executing an Existing Pattern........................................................................................................... 49
Stopping a Pattern Currently Being Executed...................................................................................49
Chapter 5: Events and Alarms................................................................. 50

Overview.............................................................................................................................................50
Where Does the Pelco SDK Fit?............................................................................................50
Event Arbiter Library............................................................................................................... 51
Event Manager........................................................................................................................ 51
Event Arbiter Library Compared to Event Manager.......................................................................... 52
Creating an Event Agent................................................................................................................... 52
Returning the Event Subscription URL............................................................................................. 55
Initializing the Event Arbiter Library...................................................................................................55
Initializing the Event Arbiter Library for C++...........................................................................55
Initializing the Event Arbiter Library for C#.............................................................................56
Initializing the Event Manager........................................................................................................... 57
Device or Service Specific Subscriptions.......................................................................................... 57
Using the Event Arbiter Library to Subscribe Using the Device’s IP Address........................ 58
Using the Event Arbiter Library to Subscribe Using the Event Subscription URL...................58
Using the Event Arbiter Library to Subscribe to All Instances of a Service............................ 59
Using the Event Arbiter Library to Subscribe to a Device's Web Service...............................60
Using the Event Arbiter Library to Unsubscribe from a Service............................................. 60
Mass Subscriptions by Category....................................................................................................... 61
Using the Event Manager to Subscribe to All Services..........................................................61
Using the Event Manager to Unsubscribe from All Services..................................................62
Handling Incoming Events................................................................................................................. 62
Polling Events.................................................................................................................................... 65
Chapter 6: Extracting Audio and Video Metadata.................................. 66

Extracting Audio and Video Metadata............................................................................................... 66
Motion Detection Metadata................................................................................................................67
Pelco Analytics Drawing Primitives................................................................................................... 67
Timestamps........................................................................................................................................ 67
Getting Started................................................................................................................................... 68
Initializing the Metadata Parser Class............................................................................................... 69
Creating a Metadata Renderer Class................................................................................................69
3
Contents | Pelco SDK
Retrieving the Current Timestamp Metadata.....................................................................................70

Motion Detection Metadata................................................................................................................70
Retrieving Motion Detection Metadata....................................................................................70
Rendering Motion Detection Metadata................................................................................... 71
Drawing Metadata.............................................................................................................................. 71
Retrieving Drawing Metadata..................................................................................................71
Rendering Drawing Metadata................................................................................................. 72
Chapter 7: Exporting Video...................................................................... 73

Overview.............................................................................................................................................73
Where Does the Pelco SDK Fit?............................................................................................73
Custom Application Development......................................................................................................73
Getting Started................................................................................................................................... 74
Initializing the Exporter...................................................................................................................... 74
Setting Up Overlay Data on Video to Be Exported...........................................................................75
OverlayData Parameters.........................................................................................................76
Resetting Overlay Data...........................................................................................................80
Exporting Video..................................................................................................................................80
Exporting a Single Video Clip.................................................................................................80
Exporting Video Using a Playlist (PPX)..................................................................................81
Stitching Multiple Clips into a Single Video Export.................................................................83
Polling a Video Export....................................................................................................................... 85
Stopping a Video Export....................................................................................................................85
Exporting A JPEG Snapshot............................................................................................................. 86
Chapter 8: Web Service Proxies.............................................................. 87

Web Service Proxies......................................................................................................................... 87
General Usage................................................................................................................................... 87
Chapter 9: Discovery.................................................................................89
Device and Service Discovery Overview...........................................................................................89
Initializing the Pelco SDK System Manager Wrapper....................................................................... 90
Automatically Determining the System Manager’s IP Address and Port Number............................. 91
Logging In and Logging Out..............................................................................................................91
Querying Available Devices from the System Manager....................................................................92
Retrieving the System Manager’s Time Zone........................................................................ 93
Retrieving the Network Time Server Address........................................................................ 94
Retrieving a Web Service’s ID................................................................................................94
Retrieving a Specific Web Service’s Control URL..................................................................95
Retrieving the NVR Associated with the Device.................................................................... 96
Retrieving the Device’s Friendly Name.................................................................................. 97
Retrieving the Device’s Device Description File (DDF) URL.................................................. 97
Retrieving All Web Services Available on a Device............................................................... 98
Retrieving Device Attributes.............................................................................................................. 99
Retrieving a System Manager’s Attribute............................................................................. 100
Retrieving a Web Service’s Attribute.................................................................................... 101
Creating an IDeviceStorage Class.................................................................................................. 102
Appendix A: Logging.............................................................................. 104
Appendix B: Product Compatibility....................................................... 106
4
Pelco SDK | Contents
Appendix C: Endura................................................................................ 108
Appendix D: General Event Messages.................................................. 112
Appendix E: Hardware Diagnostics Event Messsages........................ 114

ConfigurationButton (20180)............................................................................................................ 114
DriverFailure (20150)....................................................................................................................... 115
Fans (20020)....................................................................................................................................116
HardDrives (20060)..........................................................................................................................118
ImproperShutdown (20070)............................................................................................................. 120
LinkSpeed (20200)...........................................................................................................................121
PowerSupply (20120).......................................................................................................................122
UPS (20170).................................................................................................................................... 122
Appendix F: Software Diagnostics Event Messsages..........................124

DataLoss 20040............................................................................................................................... 124
InputStreams 20160.........................................................................................................................125
PacketLoss 20080............................................................................................................................126
SEBs 20210..................................................................................................................................... 127
StorageFull 20190............................................................................................................................129
StorageTime 20130..........................................................................................................................130
Temperature 20140.......................................................................................................................... 131
Appendix G: Glossary............................................................................. 133
5
Pelco SDK | Introduction
Chapter
1
Introduction
Getting Started with the Pelco SDK

The Pelco SDK is a powerful software developer kit to help third parties use Pelco products alongside
non-Pelco products and software. While the Pelco API is both flexible and powerful, it can also potentially
overwhelm some users; of course, developers are still free to directly use the Pelco API as they wish.
However, Pelco has found that many of our customers enjoy the convenience and ease of use that the
Pelco SDK provides. The Pelco SDK provides the following functionality:
• Video rendering
• Device and service discovery
• User and role management
• Pan, tilt, and zoom (PTZ) control
• Eventing support
• Video export
• Audio and video metadata parsing
• Object model
What Does the Pelco SDK Contain?

The following table shows the major Pelco SDK components.
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.
Control Pan/Tilt/Zoom on Pelco PTZ-enabled cameras.
PTZ Control Wrapper Pan and tilt control

Zoom, iris, and focus control
Basic script management
2
Event Arbiter Library Advanced event subscription management:
Subscribe to individual web service events
1
PelcoGsoap is not a separately installable library, but it is included in the other components as required.
2
EventArbiter component also contains Event Manager. Therefore, Event Manager is not a separately
installable component.
6
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.
NOTE:
Event Manager requires an Endura System Manager.
Metadata Parser Parses Pelco Video Elementary Stream (VES) metadata:

Timestamp, Motion Detection, Video Analytics Primitives
Render primitives and other data to video frame
Exporter Export video streams into a variety of popular video formats:

AVI, MP4, 3GP, or PEF
Overlay data on exported video
Object Model The object model uses objects to communicate with networked
video management systems and devices. The object model
operates in conjunction with device caching, which discovers
networked devices and stores the device list on the local
computer on which the program is running.
The Pelco SDK also contains sample projects, as shown in the following table.
Code Sample Default Location
Event Arbiter Sample C:\Program Files\Pelco\API\SampleCode

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

3
\EventArbiterSample
3
Exporter Sample C:\Program Files\Pelco\API\SampleCode\ExporterSample
MetaDataParser Sample C:\Program Files\Pelco\API\SampleCode

3
\MetaDataParserSample
Pelco API Viewer Sample C:\Program Files\Pelco\API\SampleCode

3
\PelcoAPIViewerSample
PTZ Control Wrapper C:\Program Files\Pelco\API\SampleCode

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

3
\SystemManagerWrapperSample
3
Get Devices Sample C:\Program Files\Pelco\API\CPP\GetDevices
3
On 64-bit systems, C:\Program Files will change to C:\Program Files (x86)
7
3
C:\Program Files\Pelco\API\DotNet\GetDevices
There are additional Pelco SDK advanced samples, which show further scenarios for using the Pelco SDK.
The advanced samples are available in a separate download listed on the Pelco PDN Web site. See http://
pdn.pelco.com/content/pelco-sdk-samples.
General Requirements
Hardware
The minimum hardware requirements for the client machine to use for completing the steps outlined in this
document are the following:
• CPU: Intel 2.4 GHz Core 2 Duo (or higher)
• Memory: 2 GB
• GPU: DirectX 9 compatible; must be a dedicated graphics card with at least 128 MB of memory, and
use an AGP bus or a PCI Express bus
• HD: 1 GB free hard disk space
NOTE: Virtual machines are not supported for streaming video from Pelco cameras.
In addition to your client machine, a Pelco SDK compatible Pelco device is required. A list of currently
compatible Pelco hardware can be found in the Appendix.
Software
The software requirements for completing the steps outlined in this document are the following:
• ONE of the following operating systems:
• Microsoft Windows Server 2003 32-bit
• Microsoft Windows XP 32-bit
• Microsoft Windows XP 64-bit
• Microsoft Windows Vista 32-bit
• Microsoft Windows Vista 64-bit
• Microsoft Windows 7 32-bit
NOTE: Pelco does not support using the SDK in 64-bit mode applications. Applications must be
built in 32-bit mode, and will still run on 64-bit operating systems.
• The latest version of DirectX 9.0c must be installed even if DirectX 10 or 11 is already installed as part
of Windows Vista or higher (see http://www.microsoft.com/en-us/download/details.aspx?id=8109)
• ONE of the following combinations of Visual Studio and Microsoft .NET Framework:
• Visual Studio 2008 and Microsoft .NET Framework 3.5
• Visual Studio 2010 and Microsoft .NET Framework 4.0
NOTE: Improper use of audio/visual recording equipment may subject you to civil and criminal
penalties. Applicable laws regarding the use of such capabilities vary between jurisdictions and may
8
require, among other things, express written consent from the recorded subjects. You are solely
responsible for insuring strict compliance with such laws and for strict adherence to any/all rights of
privacy and personalty.
Installing the Pelco SDK

1. Download the Pelco SDK from the Pelco Developer Network (PDN) at http://pdn.pelco.com. It can be
found in the Pelco SDK Related Downloads sub-section inside the Downloads section. Pelco SDK has
two separate set of downloads: One for Visual Studio 2010 (download Pelco SDK vc10) and one for
Visual Studio 2008 (download Pelco SDK vc9). Select the appropriate download for your version of
Visual Studio.
2. Once finished downloading, doubleclick on the Pelco SDK installer to begin installation. Simply follow
the on-screen prompts to complete installation.
NOTE: If you have a previous version of the Pelco SDK installed, you must uninstall it before
installing the latest version.
3. After installation, restart the system to ensure that environment variables are running correctly.
Assuming the default installation path was chosen, users can find the following folders:
File Folder Path Description
C:\Program Files\Pelco\API Header files for all of the Pelco SDK related classes can be
4
\Include\C++\PelcoAPI found here.
C:\Program Files\Pelco\API\Libs Pelco SDK release module libraries can be found within the
4
\Release Release directory.
C:\Program Files\Pelco\API\Libs Pelco SDK debug module libraries can be found within the
4
\Debug Debug directory.
C:\Program Files\Pelco\API\Libs Pelco SDK release plugins can be found within the Plugins
4
\Release\Plugins directory.
C:\Program Files\Pelco\API Contains all the sample code projects related to Pelco SDK
4
\SampleCode components.
C:\Program Files\Pelco\API Contains an application called LoggingSetup.exe which

4
\Logging allows you to write a log file for debugging purposes. You
can manage other logging related information by running
LoggingSetup.exe.
NOTE:
Each Pelco SDK component may have additional installation and / or configuration requirements.
System Environment Settings for the Pelco SDK

The Pelco SDK installer adds three environment variables/paths to the installed system:
• EVEREST_BIN - Location of the binaries. By default, this is set to C:\Program Files\Pelco\API
\Libs
4
On 64-bit systems, C:\Program Files will change to C:\Program Files (x86)
9
• EVEREST_ROOT - Location of the Pelco header files. By default this is set to C:\Program Files
\Pelco\API\Include\C++
• PATH - This initially points to the C:\Program Files\Pelco\API\Libs\Debug folder
NOTE: If you want to build the SDK in release mode, you must change the PATH variable to point
to the Release directory (for example, C:\Program Files\Pelco\API\Libs\Release). If any
of the paths have been changed from the defaults, you will be responsible for removing the path if
the SDK is uninstalled.
Including Required SDK Components For Your Application

When distributing your application that relies on the Pelco SDK, you must ensure that the required SDK
component redistributables are installed on the target client machine. As with other re-distributables, a UI
will not be presented to the user, and the re-distributable itself can be called by your custom installer. Once
the re-distributable is finished, your custom installer can check the status of the install and whether or not
it needs a reboot. In addition, the client machines must have DirectX 9.0c installed, plus Visual C++ 2008
Runtime and .NET Framework 3.5, or Visual C++ 2010 Runtime and .NET Framework 4.0, depending on
your requirements.
As with the full SDK, download individual Pelco SDK components and Pelco SDK re-distributables from the
Pelco Developer Network (PDN) at http://pdn.pelco.com. Once finished downloading, double click on the
Pelco SDK installer to begin installation. Simply follow the on-screen prompts to complete installation.
NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com.
The sample projects assume that the default target installation directory was chosen during installation.
Setting Up Sample Projects

WARNING: Any provided sample code is meant to be a reference implementation focused on
educating developers about Pelco devices. Though there are exceptions, in general Pelco sample
code is NOT intended for immediate production use.
NOTE: Ensure the Pelco SDK is installed. Also, the Pelco API Viewer sample project requires
Microsoft’s DirectX 9, and a video card that supports DirectX 9.
To begin using the sample project code, locate the appropriate sample within the Pelco SDK SampleCode
directory:
• On 32-bit computers: C:\Program Files\Pelco\API\SampleCode
• On 64-bit computers: C:\Program Files (x86)\Pelco\API\SampleCode
NOTE: Some Pelco SDK sample projects, such as the Pelco API Viewer sample, are spread
across more than one class. There may also be more than one sample project associated with the
particular SDK component.
It is assumed that you will be examining the sample project alongside this documentation.
NOTE:
On 64-bit computers, set Platform target to x86 before building the project. You will see how to do
that shortly.
Registering the ActiveX Control

By default, on 32-bit systems the installer registers the Active X Component (OCX) in the C:\Program
Files\Pelco\API\Libs\Debug directory. On 64-bit systems, the directory is C:\Program Files
10
(x86)\Pelco\API\Libs\Debug. To ensure that the OCX registration is successful, change the PATH
variable to point to this directory.
For release builds, you can manually register the Pelco API Viewer ActiveX Component:
PelcoAPICOMViewer.ocx. To register the PelcoAPICOMViewer.ocx ActiveX Component, open
the command line and navigate to the Pelco SDK library release directory, which on 32-bit systrems is
by default: C:\Program Files\Pelco\API\Libs\Release. On 64-bit systems, the directory is C:
\Program Files (x86)\Pelco\API\Libs\Release.
Once within the folder, run the Microsoft Register Server (Regsvr32.exe) to register the SDK
component as appropriate. This must be run with administrative permissions. For example, to register the
PelcoAPICOMViewer.ocx file: Regsvr32 PelcoAPICOMViewer.ocx
Adding References to Managed Libraries for C#

After you have registered the Pelco API COM Viewer ActiveX control, open the sample project you want to
build in Visual Studio (for example, open the Pelco API Viewer Sample C# project).
The next step is to add the references to the Pelco managed library DLLs to the project.
Within Visual Studio’s Solution Explorer window, expand the References section.
Make a note of which of the following Pelco library references are present:
• ManagedEnduraExport(9)
• ManagedEventArbiter
• ManagedEventManager
• ManagedPelcoAPICommon
• ManagedPTZControlWrapperNet
• ManagedSystemManagerWrapper
• Pelco.SDK
• PelcoAPIMPFViewer
You will need the list of references shortly. Each Pelco reference might have a yellow exclamation
mark (!) next to it. For the Pelco API Viewer Sample C# project, the references needed are
ManagedPelcoAPICommon and PelcoAPIMPFViewer.
Delete the existing Pelco references by right-clicking each Pelco reference and selecting Remove. For
the Pelco API Viewer Sample C# project, remove the references to ManagedPelcoAPICommon and
PelcoAPIMPFViewer.
From the File menu, select Save All.
From the Build menu, select Clean Solution.
Right-click References and select Add Reference.
11
Click the Browse tab. Navigate to the correct Pelco library directory. Assuming you used the default
installation path, the directory containing the debug libraries on 32-bit computers will be C:\Program
Files\Pelco\API\Libs\Debug. On 64-bit computers, the directory will be C:\Program Files
(x86)\Pelco\API\Libs\Debug.
NOTE: If you are building an application for release, then you use the release libraries in the
Pelco\API\Libs\Release directory.
12
Find the project library files that you made a note of earlier, and control-click each of the files. For
example, the Pelco API Viewer Sample C# project requires the ManagedPelcoAPICommon.dll and
PelcoAPIMPFViewer.dll files. Click OK to add the files.
On a 64-bit computer, set Platform target to x86.
13
NOTE: Pelco does not support using the SDK in 64-bit mode applications. Applications must be
built in 32-bit mode, and will still run on 64-bit operating systems.
You can now build and then run the Pelco API Viewer Sample C# project.
NOTE: For projects that require the PelcoAPICOMViewer.ocx control, you might need to clean
and rebuild the project several times before the OCX control will work. This is a Visual Studio / OCX
limitation.
NOTE: For C++ projects, be sure to set the character set to Use Multi-Byte Character Set under
the project properties. Click the project, then select Properties > Configuration Properties >
General. You will then see Character Set. Set it to Use Multi-Byte Character Set.
14
15
Pelco SDK | Object Model
Chapter
2
Object Model
Overview
Pelco SDK 3.0 introduces an object model, which will simplify development of applications that utilize the
SDK. Future versions of the SDK will phase out previous SDK components and replace them with objects.
The object model uses objects to communicate with networked video management systems and devices.
The object model consists of a group of classes for representing systems, devices connected to those
systems, device properties, and other items.
Component Libraries
The following component libraries contain the functionality for the object model:
• PelcoSDK.dll, which is used for C++
• Pelco.SDK.dll, which is used for C#
Public Classes
The following table shows the public classes used in the object model.
Table 1: Object Model Public Classes
Class Description
System An Endura system
SystemCollection A collection of systems
Device A device connected to a system
DeviceCollection A collection of devices
Property A device property
PropertyCollection A colleciton of properties
Event An unmanaged event
Events A collection of unmanaged events
Exception An exception
Device Caching
Device caching is implemented using the object model. Device caching is a feature of the SDK where
information about devices is cached on the local computer on which the program using the SDK is running.
16
The caching of device information results in faster response times and reduced network traffic. Device
caching is performed on objects.
The device information is stored in a database on the local computer. The first attempt to connect to a new
Pelco system retrieves all of the device information and device parameters, and stores the information
in the database. Future attempts to retrieve the same information is obtained from the database. A
continously running background task ensures the device information is the latest version. The minimum
device cache database refresh interval is five minutes.
The device cache database is stored on the local computer. The directory where the database is stored
depends on the operating system used, as described in the following table.
Table 2: Database Location
Operating System Directory
• Windows XP C:\Documents and Settings\All Users\Application Data

• Windows Server 2003 \Pelco\SDK
• Windows Server 2008
• Windows Vista C:\ProgramData\Pelco\SDK

• Windows 7
• Windows 8
• Windows Server 2012
Samples
This section contains sample C# that illustrates how to implement device caching using the object model.
Complete C# and C++ sample programs are contained in the directories specified in the following table.
Table 3: Samples
Directory Description
C:\Program Files\Pelco\API\SampleCode\CPP\GetDevices C++ sample
C:\Program Files\Pelco\API\SampleCode\DotNet\GetDevices C# sample
The samples show how to retrieve a list of connected devices. When running the samples, the default user
name is admin. The default password is also admin.
Display the Devices

The following sample shows how to display the devices:
int _tmain(int argc, _TCHAR* argv[])

{
try
{
// Create a system object
PelcoSDK::System system("admin:admin@pelcosystem://10.220.196.187:60001?
alias=Sample");
// Create a device collection object and populate it with the devices

from the system object
PelcoSDK::DeviceCollection
deviceCollection(system.GetDeviceCollection());
17
// Loop over the device collection object and display each device name
printf("\n\n> DEVICES =================================\n");
for (deviceCollection.Reset(); deviceCollection.MoveNext(); )
{
// Retrieve the current device object
PelcoSDK::Device device(deviceCollection.Current());
// Display the device name

printf("\tDevice Name: %s\n", device.GetModelName());
}
// Display the number of devices

printf("=========================================\n");
printf("Total Devices: %d", deviceCollection.GetCount());
}
catch (PelcoSDK::Exception ex)
{
printf("An error occured\nError: %s", ex.Message().c_str());
}
return 0;
}
The following sections describe the sample details.
Connecting to a System
The following line connects to the system:
PelcoSDK::System system("admin:admin@pelcosystem://10.220.196.187:60001?
alias=Sample");
The string passed to the constructor is a URL scheme. The scheme consists of four parts, which are
described in the following table.
Table 4: URL Scheme Components
Component Description Example

Credentials User name and password. If the user name and password admin:admin
are not provided, then the system object is read only,
which will prevent retrieval of a device collection and
access to a device object through the GetDevice()
method. Basic properties such as the display name, IP
address, port, alias, and system refresh time can still be
retrieved. Any attempt to call GetDeviceCollection(),
GetDevice(), SetRefreshTime(), SetAlias(), or
Remove() will throw an exception with an error code of
PelcoSDK::NotAuthenticated.
System Provider System provider identifier. For an Endura system, the identifier pelcosystem
is "pelcosystem". Other system providers might be supported
in the future.
System Address IP address and port of the system to access. In the sample, a 10.220.196.187:60001
"direct discovery" operation is performed, where both the IP
address and port are specified. An "auto discovery" operation
can be performed by omitting the IP address and port. Pelco
SDK 3.0 only supports auto discovery of Endura systems.
18
Component Description Example

Parameter Optional parameter. Pelco SDK 3.0 only supports the alias alias=Sample
parameter. This parameter allows the developer to assign a
key to the system, which enables easy retrieval at a future
point. The alias can be set to any unique value for a particular
system.
A system object can be created without first retrieving a system collection object. This provides a
convenient way to add or get a system object.
When the system object is created, a new entry in the Pelco device cache is created. The cache
contains details for the objects contained within the cache. There is a slight delay while the cache entry
is populated. The next time the application containing the system object creation statement is started, the
SDK will retrieve the system information from the cache and make the information immediately available.
Retrieving a Device Collection

The following line creates a device collection object and populates the object with the retrieved devices:
PelcoSDK::DeviceCollection deviceCollection(system.GetDeviceCollection());
The GetDeviceCollection() method of the system object returns the collection of devices retrieved
from the system object.
Displaying Device Information

The following sample uses a loop to access the devices in the device collection object, and displays each
device name:
// Loop over the device collection object and display each device name
printf("\n\n> DEVICES =================================\n");
for (deviceCollection.Reset(); deviceCollection.MoveNext(); )
{
// Retrieve the current device object
PelcoSDK::Device device(deviceCollection.Current());
// Display the device name

printf("\tDevice Name: %s\n", device.GetModelName());
}
In the sample, deviceCollection.Current() returns an object of type PelcoSDK::Device(). The

sample then displays the name of the device using device.GetModelName().
As can be seen in the sample, the SDK contains methods for iterating over collection objects. A typical use
of the iteration methods is to display a list of systems and devices.
The iteration methods are shown in the following table.
Table 5: Iteration Methods
Method Description
Reset() Moves back to the start of the collection.
MoveNext() Moves to the next collection item. This method must be called before Current().
Returns true or false (true means the end of the items has not been reached, false
means the end has been reached).
Current() Retrieves the current item in the collection.
19
The SDK also contains methods for directly accessing a collection. The methods are shown in the following
table.
Table 6: Methods
Method Description
GetItem(index) Retrieves the item at the specified index.
GetItemByKey(key) Retrieves the item with the specified key. For a device, the key is the
device UUID. For a system, the preferred key is the system alias.
NOTE: Another SDK method is GetVersion(), which returns the device version. The device
is accessed directly to retrieve the version, and the retrieved value is not cached. Avoid calling
GetVersion() in a loop because of the delay while a response is sent from the device.
20
Chapter
3
Displaying and Controlling Video Streams
Overview
The 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.
This section contains sample C# and C++ that illustrates how to display and control video streams.
Complete C# and C++ sample programs are contained in the following subdirectory where the Pelco SDK
is installed: C:\Program Files\Pelco\API\SampleCode\PelcoAPIViewerSample
Where Does the Pelco SDK Fit?

To display and control video streams, use the Pelco API Viewer. The Pelco API Viewer is an easy 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 RTSP mode. In RTP mode, the player uses one of
several Pelco API methods to initiate and control streams. While in RTSP mode, the player expects to work
with either devices, such as a Sarix IP camera, where RTSP is supported by default; or software solutions
like the RTSP Server.
The Pelco API Viewer can be used in three ways:
1. C++
2. C#
3. OCX (ActiveX Control)
Support is provided for viewing both MPEG-4 and H.264 streams, but changing a video configuration from
one format to the other causes the video to stop streaming.
What’s Ahead
There are two major tasks for viewing a video stream using the Pelco API Viewer:
• Opening, playing, displaying a stream
• Controlling the stream
Initializing the Pelco API Viewer (C++)

Before you can use the Pelco API Viewer, you need to declare and configure your new instance.
1. Declare the Pelco API Viewer instance.
21
Pelco SDK | Displaying and Controlling Video Streams
NOTE: The related source code for this entry can be found in main.cpp’s main function, which
resides in the PelcoAPIViewer sample project.
PelcoAPI::PelcoAPIViewer _pViewer;
2. Set the instance’s plug-in directory.

Assuming that you did not change the default target installation directory, it can be found here: C:
\Program Files\Pelco\API\Libs\Debug\Plugins
NOTE: If running in Release mode, change this path to C:\Program Files\Pelco\API
\Libs\Release\Plugins.
The plug-in directory contains components that are key to the SDK’s encoding, decoding, and
transcoding capabilities. Without a proper reference, key features of the Pelco SDK may not function
properly. Please note that the plug-in directory is dependent on where you installed the Pelco SDK.
resides in the PelcoAPIViewer sample project.
_pViewer.SetPluginDir("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins
\\");
3. If required, set the authentication credentials to log into the camera.

The following example checks if authentication is enabled for the camera, and, if so, sets the user name
to "admin" and the password to "admin_password".
// Set example parameters

#define CAMERA_IP_ADDRESS "10.220.196.179"
#define PORT_NUMBER 80
#define CAMERA_NUMBER 1
// Check if authentication is enabled

if (_pViewer.IsAuthenticationEnabled(CAMERA_IP_ADDRESS, CAMERA_PORT,
CAMERA_NUMBER))
{
// Set the user name to "admin", the password to "admin_password", and
use basic authentication
PelcoAPI::AuthenticationCredentials authentication("admin",
"admin_password", PelcoAPI::AuthenticationCredentials::BASIC);
_pViewer.SetAuthenticationCredentials(&authentication);
}
NOTE: To manage the camera authentication and the users, use the Pelco Web interface.
4. Create a new window handle and associate it to the Pelco API Viewer instance.
Please note that logic to create the window handle can be found in the _DbgCreateParentWindow
method.
HWND _hWndParent = NULL;

//... Logic to create a window and display it. Refer to
_DbgCreateParentWindow ...
m_pViewer->SetWindowHandle((_hWnd ? _hWnd : this->m_hWnd));
Initializing the Pelco API Viewer (C#)

NOTE: In release mode, you need to select the Enable unmanaged code debugging checkbox in
the project settings to see console output.
22
Before you can use the Pelco API Viewer, you need to declare and configure your new instance.
PelcoAPIMPFViewer contains two components: PelcoAPIMPFViewerControl, a convenient, prebuilt
control, or a managed version of the PelcoAPIViewer library that enables the developer to control the
videostream programmatically. Both approaches are described below.
Using the PelcoAPIViewer Component

To use the more programmable PelcoAPIViewer library, complete the following steps.
1. Declare the PelcoAPIViewer instance, set the plugin directory, and set the window handle.
PelcoAPI.PelcoAPIViewerNet _pViewer = new PelcoAPI.PelcoAPIViewerNet();

_pViewer.SetPluginDir(objstreamparam.PluginDir);
_pViewer.SetWindowHandle(windowsviewerobj.Handle);


const String CAMERA_IP_ADDRESS = "10.220.196.179";
const int PORT_NUMBER = 80;
const int CAMERA_NUMBER = 1;

CAMERA_NUMBER))
{
AuthenticationCredentialsNet tmpAuthentication =
new AuthenticationCredentialsNet("admin", "admin_password",
PelcoAPI.AuthenticationSchemeTypeNet.Basic);
_pViewer.SetAuthenticationCredentials(tmpAuthentication);
}
Using the PelcoAPIMPFViewerControl Component

To use the prebuilt control PelcoAPIMPFViewerControl, complete the following steps.
NOTE: Example source code can be found in PelcoAPIViewerForm.designer.cs constructor, which
resides in the PelcoAPIViewerSample sample project.
1. Declare the Pelco API MPF Viewer instance.
private PelcoAPIMPFViewer.PelcoAPIMPFViewerControl _pViewer;

this._pViewer = new PelcoAPIMPFViewer.PelcoAPIMPFViewerControl();
2. Listen for the user selected plug-in directory.

Assuming that you did not change the default target installation directory, it can be found here: C:
\Program Files\Pelco\API\Libs\Debug\Plugins
NOTE: The plug-in directory contains components that are key to the SDK’s encoding,
decoding, and transcoding capabilities. Without a proper reference key features of the Pelco
SDK may not function properly. Please note that the plug-in directory is dependent on where you
installed the Pelco SDK.
private void BrowseForPluginDir(object sender, EventArgs e)

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


const String CAMERA_IP_ADDRESS = "10.220.196.179";
const int PORT_NUMBER = 80;
const int CAMERA_NUMBER = 1;

CAMERA_NUMBER))
{
AuthenticationCredentialsNet tmpAuthentication =
new AuthenticationCredentialsNet("admin", "admin_password",
PelcoAPI.AuthenticationSchemeTypeNet.Basic);
_pViewer.SetAuthenticationCredentials(tmpAuthentication);
}
4. Save the stream settings.
private void SaveStreamSettings(object sender, EventArgs e)

{
try
{
_pViewer.SetPluginDir(_txtFolder.Text);
_pViewer.SetupStream(_txtIP.Text, _txtPort.Text,
_txtServiceId.Text,_txtTransport.Text);
}
catch (Exception /*ex*/) { }
}
Setting Size and Position of Video Display Area

Calling the SetDisplayRect method to center the video stream display inside a window with margins
does not automatically center it. You need to set the size and position of the video display rectangle so that
its width and height are equal to the width and the height of the window.
The SetDisplayRect method allows resizing the video display area when the window is resized. Thus,
SetDisplayRect would typically be called from a resize event procedure.
SetDisplayRect contains the following parameters:
top
The starting Y coordinate of the rectangle for its top side.
left
The starting X coordinate of the rectangle for its left side.
24
width
The width of the rectangle.
height
The height of the rectangle.
PELCO_API_EXPORT void SetDisplayRect(int top, int left, int width, int

height)throw ();
For example:
TRACE_INFO("Calling SetDisplayRect\n");
_pViewer.SetDisplayRect(75, 100, 824, 618);
Querying an RTP Stream

The VideoQuery function can be used to query the camera or the NSM to retrieve video properties of a
stream.
For example:
_pViewer.VideoQuery("NOW", "INFINITE", "10.220.196.169", "49153", "1", "4",

"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", False, NULL);
NOTE: Another example usage of this function can be found in the main.cpp file's main function,
which belongs to the PelcoAPIViewer sample project SampleConsole9.
The following list shows the parameters:
szStartTime
Required. The start time within the stream to start play back. For play back of a recorded
RTP stream, the start time must be specified in UTC using the following time format:
YYYY-MM-DDTHH:MM:SS. For play back of a live RTP stream, set the time to the string
"NOW".
szEndTime
Required. The end time within the stream to end play back. For play back of a recorded
RTP stream, the end time must be specified in UTC using the following time format:
"INFINITE".
szIpAddress
Required. The IP address of the video stream source device for NSM, NVR, or EE500. For
a live RTP stream, this is the IP address of the camera. For play back of a recording, this is
the IP address of NSM/NVR.
szPort
Required. The port number of the video stream source device for NSM, NVR, or EE500.
For a live RTP stream, this is the port number of the camera. For play back of a recording,
this is the port number of NSM/NVR.
szNVRServiceId
The NVR ID. Optional for a live RTP stream; required for manual recording of a live RTP
stream, and for a play back of a RTP stream. For example, if an end point URL ends with
“VideoOutput-1”, then the service ID must be set to 1.
szCameraServiceId
25
The last number of the web service endpoint URL of a camera. For example, if an endpoint
URL ends with “VideoOutput-4” then 4 is the service ID.
szCameraUuid
The IP camera’s UPnP Unique Device Name (UDN). For example,
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15".
NOTE: The IP camera’s UDN is required if you want to start manual
recording of a live stream. Otherwise, this parameter is optional.
bLowBandwidth
Sets the stream bandwidth from the camera to low. The camera must be configured to
have the secondary low bandwidth stream enabled. For backwards compatibility, this
parameter is set to FALSE by default.
NOTE: This parameter is only valid for live streams.
streamInfoNet
Streaming data, which is to be filled in. This value can be passed back to a live or a play
back call to StartStream for RTP only. For backwards compatibility, this parameter is set
to NULL by default.
Opening, Playing, and Displaying a Live or Playback RTP Stream

belongs to the PelcoAPIViewer sample project SampleConsole9. When in debug mode, if the
video playback is paused during program execution, then RTCP messages are displayed in the
console window. The messages provide information about the RTCP packekts.
Before being able to control a video stream, you must first open the stream, and display it on a Window
instance.
1. Initialize the Pelco API Viewer.
Refer to Initializing the Pelco API Viewer (C++) for details.
2. Start the video stream to display, by calling the StartStream method, passing in the following
parameters:
szStartTime
Required. The start time within the stream to start play back. For play back of a recorded
RTP stream, the start time must be specified in UTC using the following time format:
"NOW".
szEndTime
Required. The end time within the stream to end play back. For play back of a recorded
RTP stream, the end time must be specified in UTC using the following time format:
"INFINITE".
szIpAddress
Required. The IP address of the video stream source device for NSM, NVR, or EE500. For
a live RTP stream, this is the IP address of the camera. For play back of a recording, this is
the IP address of NSM/NVR.
szPort
Required. The port number of the video stream source device for NSM, NVR, or EE500.
For a live RTP stream, this is the port number of the camera. For play back of a recording,
this is the port number of NSM/NVR.
26
szServiceId
The last number of the web service endpoint URL. For example, if an endpoint URL ends
with “VideoOutput-4” then 4 is the service ID.
szTransport
The video stream’s transport (RTP) URL (optional for a live RTP stream, because the
camera starts a MULTICAST stream if no value is supplied. Required for playback.) The
IP address must be the IPv4 address of the machine on which the code is running, for the
network through which it will connect to the video source. The port number must be an
even number, and must not be in use.
Example:rtp://ip_of_local_machine:open_port_even
NOTE: When one RTP unicast stream is already playing, and another
is started, be sure to set an RTP port that is at least four higher than the
previous stream. The port that is two higher than the previous port might
already be in use by the previous stream’s audio channel.
szCamUuid
The IP camera’s UPnP Unique Device Name (UDN). For example,
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15".
NOTE: The IP camera’s UDN is required if you want to start manual
recording of a live stream. Otherwise, this parameter is optional.
szNvrId
The NVR ID. Optional for a live RTP stream; required for manual recording of a live RTP
stream, and for a play back of a RTP stream. For example, if an end point URL ends with
“VideoOutput-1”, then the service ID must be set to 1.
ITimeStampDelegate
Signals if you want the timestamp returned by the API. If no timestamp is required, do not
supply a value for this parameter.
bVideoOnly
Stream video without audio. By default, this parameter is set to FALSE for backwards
compatibility.
bLowBandwidth
Sets the stream bandwidth from the camera to low. The camera must be configured to
have the secondary low bandwidth stream enabled. For backwards compatibility, this
parameter is set to FALSE by default.
NOTE: This parameter is only valid for live streams.
streamInfoNet
Streaming data, which is to be filled in. This value can be passed back to a live or a play
back call to StartStream for RTP only. For backwards compatibility, this parameter is set
to NULL by default.
For a live RTP stream:
MyAppNamespace::TimeStamp _pDelegate;
const char* pszSesId = NULL;
//... Other logic ...
pszSesId = _pViewer.StartStream("NOW", "INFINITE",
"10.220.196.149", "49154", "1", "rtp://10.220.196.148:7162",
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", &_pDelegate, False,
False, NULL);
27
where:
• StartTime is the time you want to start video. For live streams, use the value as "NOW",
• endTime is the time you want the video to end. For live streams, use the value “INFINITE”.
NOTE: For NULL/optional values, use “” for strings and NULL for interface values.
• szServiceId is the camera service ID, etc,

For a playback RTP stream:
//... Other logic ...
pszSesId = _pViewer.StartStream("2010-08-08T18:02:00",
"2010-08-08T18:28:00",
"10.220.196.149", "49154", "1", "rtp://10.220.196.148:7162",
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15", "1", &_pDelegate, False,
False, NULL);
where:
• szServiceId is the camera service ID,
• szTransport and szCamUuid are required for playback.
If successful, these methods will return a session ID, pszSesId, of the stream. This will be used
throughout this document for tasks related to the Pelco API Viewer.
Opening, Playing, and Displaying an RTSP Stream

belongs to the PelcoAPIViewer sample project SampleConsole9.
1. Initialize the Pelco API Viewer.
Refer to Initializing the Pelco API Viewer (C++) or Initializing the Pelco API Viewer (C#) entry for details.
2. Start the video stream to display, by calling the StartStream method, passing in the following
parameters:
The location of the RTSP stream
The username to use for authentication (Optional)
The password to use for authentication (Optional)
A boolean indicating whether or not the stream is multicast
The timestamp parameter is an object that implements the ITimeStampDelegate interface,

or NULL if you don’t want to receive timestamps as the video plays. (Optional)
//... Other logic e.g. setting up windows, and so on ...
//Live example:
pszSesId = _pViewer.StartStream(
"rtsp://10.220.196.169/?deviceid=uuid:d557efb9-3a2d-48a1-b2fa-
b48231f62f15", NULL, NULL,
false, &_pDelegate);
//Playback example:
pszSesId = _pViewer.StartStream(
"rtsp://10.221.224.35/?deviceid=uuid:01b766f9-9d87-4613-
a168-5e5d179d339d&starttime=2011-12-04T10:00:00&endtime=2011-12-04T11:00:00",
28
NULL, NULL,
false, &_pDelegate);
If successful, the method will return a session ID of the stream. Keep this in mind, as this will be used
throughout for tasks related to the Pelco API Viewer.
Forward Playback of RTP and RTSP Streams

This entry assumes that you have already completed the steps outlined in the Opening, Playing, and
Displaying an RTSP Stream entry.
To perform a forward or reverse playback of a currently running video stream, call the Pelco API Viewer
instance’s PlayForward or PlayReverse method passing in the following parameters:
The target video stream’s session ID. A successful call to the StartStream method
returns this value.
A float value representing the desired playback speed. Valid possible playback speeds
can range from 0 - 300, with 0 representing a paused state and 1 representing regular
playback speed. (Also, 1 represents the speed for live video.)

//... Get pszSesId, the stream’s session ID, by starting a stream ...
if(_pViewer.PlayForward(pszSesId, 8.0) !=0 ){
//... Handle error ...
}
Reverse Playback of RTP and RTSP Streams

To perform a reverse playback of a currently running video stream, call the Pelco API Viewer instance’s
PlayReverse method; passing in the following parameters:
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 and 1 representing regular
playback speed.
WARNING: Reverse playback is not possible for live streams.

if(_pViewer.PlayReverse(pszSesId, 8.0) !=0 ){
}
Fast Forward / Reverse Playback of RTP and RTSP Streams

To perform a fast forward (using FrameForward, which advances by a single frame) or fast reverse
playback of a currently running video stream (using FrameReverse, which reverses by a single i-
frame that may include multiple p-frames), call the Pelco API Viewer instance’s PlayForward or
PlayReverse method (as appropriate), passing in the following parameters:
29
returns this value.
A float value representing the desired playback speed. Valid possible playback speeds can
range from - 300 to 300, with speed greater than 1 (regular playback speed). Slow motion
is supported where the speed is set at half the regular speed (e.g., -0.5 or 0.5).
Currently for RTP, PlayReverse only plays backward, and PlayForward only plays forward,
regardless of whether the speed parameter is negative or positive. Therefore, call PlayForward for
fast forward, and call PlayReverse for fast reverse.

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

if(_pViewer.PlayReverse(pszSesId, 8.0) !=0 ){
}
Pausing RTP and RTSP Playback Streams

WARNING: DO NOT pause live streams. Pausing a live stream may produce an unpredictable
result.
Displaying an RTSP Stream entry.
To pause currently running video stream, call the Pelco API Viewer instance’s Pause method; passing
in the target video stream’s session ID.

if(_pViewer.Pause(pszSesId) !=0 ){
}
Frame Forward Playback of the RTP Stream

A frame forward operation advances playback of a currently paused video stream by a single frame.
To perform this operation, call the Pelco API Viewer instance’s FrameForward method, passing in the
following parameter:
The target video stream’s session ID. A successful call to the StartStream method,
returns this value.

if(_pViewer.FrameForward(pszSesId) !=0 ){
30
Frame Reverse Playback of the RTP Stream

A frame reverse operation steps a currently paused video stream backward by a single i-frame, which can
include multiple p-frames.
To perform this operation, call the Pelco API Viewer instance’s FrameReverse method; passing in the
following parameter:
The target video stream’s session ID. A successful call to the StartStream method,
returns this value.

if(_pViewer.FrameReverse(pszSesId) !=0 ){
}
Resuming the RTP or RTSP Stream from a Paused State

NOTE: This entry assumes that you have already completed the steps outlined in Opening,
Playing, and Displaying a Live or Playback RTP Stream.
To resume a paused playback stream, call the Pelco API Viewer instance’s Resume method, passing in
the target video stream’s session ID.

if(_pViewer.Resume(pszSesId) !=0 ){
}
Stopping the RTP and RTSP Stream

Displaying the Stream entry.
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.

if(_pViewer.StopStream(pszSesId) !=0 ){
}
31
Start Manual Recording of RTP Stream

Manual recording can only be done on a live RTP stream.
NOTE: The related source code for this entry can be found in the main.cpp file’s main function,
To start manual recording of the RTP stream, call the Pelco API Viewer instance’s
StartManualRecording method, passing in the following parameters:
pszSesId
The target video stream's session ID.
cameraId
The last number of the Web service endpoint URL of the camera. For example, if an
endpoint URL ends with “VideoOutput-4”, then the ID number is 4.
nvrIp
Required. The IP address of the source of the video stream for NSM, NVR, or EE500. For
live RTP, this is the IP address of the camera. For playback, this is the IP address of the
NSM/NVR.
nvrPort
Required. The IP address and port number of the source of the video stream for NSM,
NVR, or EE500. For a live RTP stream, this is the port number of the camera. For playback
of a recorded stream, this is the port number of the NSM/NVR (required).
nvrId
The NVR ID. For example, if an endpoint URL ends with “VideoOutput-1”, then the service
ID is 1.
// Start a stream and obtain the session ID pszSesId

...
// Start manual recording, passing in the session ID pszSesId

if (_pViewer.StartManualRecording(pszSesId, "4", "10.220.196.169",
"49153", "1")) {
// ... Handle error ...
}
Stop Manual Recording of RTP Stream

Manual recording can only be done on a live RTP stream.
NOTE: The related source code for this entry can be found in the main.cpp file’s main function,
To stop manual recording of the RTP stream, call the Pelco API Viewer instance’s
StopManualRecording method, passing in the following parameters:
pszSesId
The target video stream's session ID.
// Stop manual recording, passing in the session ID pszSesId

_pViewer.StopManualRecording(pszSesId);
32
Setting Audio Volume of a Live or Playback RTP stream

Audio volume of a playback stream can be controlled using the SetAudioVolume method, by passing
in the video stream’s session ID and an integer volume level, where the range is 0 to 100, with 0
representing mute.

if(_pViewer.SetAudioVolume(pszSesId, 10) !=0 ){
}
Displaying Analytic Events for an RTP Stream

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

if(_pViewer.DisplayAnalyticEvents(pszSesId, true) !=0 ){
}
Displaying Motion Events for an RTP Stream

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

if(_pViewer.DisplayMotionEvents(pszSesId, true) !=0 ){
}
Displaying a Timestamp Overlay for RTP and RTSP Streams

To display a timestamp overlay for live/playback video streams, call the DisplayTimestampOverlay
method, passing in the target video stream's session ID, bEnable set to true, and an instance of
ViewerOverlayInfo struct.
If the struct (the 3rd parameter) is set to null, the default style overlay is displayed. The default style
would be:
• Location: Bottom left
• Date format: MMDDYYYY
• Time format: HHMMSSTT
• Font name: Arial
• Font size: 9
• Font color: Yellow
• Background color: transparent to the current screen
33
C++ Example:
PelcoAPI::ViewerOverlayInfo overlay;
PelcoAPI::COLOR fontColor = {0xFF, 0xFF, 0xFF, 0xA0};
PelcoAPI::COLOR fontBgColor = {0x00, 0x00, 0x00, 0x00};
overlay.m_dateFormat = PelcoAPI::VIEWER_DATE_FORMAT_MMDDYY;
overlay.m_timeFormat = PelcoAPI::VIEWER_TIME_FORMAT_TTHHMMSS;
overlay.m_fontColor = fontColor;
overlay.m_fontBgColor = fontBgColor;
overlay.m_location = PelcoAPI::VIEWER_OVERLAY_LOCATION_TOP_LEFT;
overlay.m_nFontSize = 12;
overlay.m_fontNameStr = "Arial";
bool bSuccess = _pViewer.DisplayTimestampOverlay(pszSesId, true,
&overlay);
C# Example:
System.Drawing.Color fontColor = System.Drawing.Color.FromArgb(0xFF, 0xFF,

0xFF, 0xA0);
System.Drawing.Color fontBgColor = System.Drawing.Color.FromArgb(0x00,
0x00, 0x00, 0x00);
ViewerOverlayInfoNet overlay = new ViewerOverlayInfoNet();
overlay.m_location =
PelcoAPI.ViewerOverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT;
overlay.m_dateFormat = PelcoAPI.ViewerDateFormatNet.DATE_FORMAT_MMDDYYYY;
overlay.m_timeFormat = PelcoAPI.ViewerTimeFormatNet.TIME_FORMAT_HHMMSSTT;
overlay.m_fontNameStr = "Arial";
overlay.m_nFontSize = 16;
overlay.m_fontColor = fontColor;
overlay.m_fontBgColor = fontBgColor;
Boolean bSuccess = _rtpViewer.DisplayTimestampOverlay(_rtpSessionId,
true, overlay);
NOTE: Live and playback RTSP streams from Sarix cameras are unable to display timestamp
information.
34
Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams
To take a snapshot of the current video frame, call the Pelco API Viewer instance’s TakeSnapShot
method; passing in the target video stream’s session ID, and the desired resulting filename and file
path.

nResult = m_pViewer->TakeSnapShot(szSessionId, "C:\\snapshots.jpg");
Pan, Tilt, Zoom (PTZ) Control for RTP Stream Using PelcoAPIViewer
Cameras with PTZ functionality can also be controlled using the PelcoAPIViewer. For more information,
see Pan, Tilt, Zoom (PTZ) Control.
NOTE: This only works with PelcoAPIViewer in RTP Live mode.
35
Pelco SDK | Pan, Tilt, Zoom (PTZ) Control
Chapter
4
Pan, Tilt, Zoom (PTZ) Control
Overview
code is NOT intended for immediate production use without modification.
WARNING: The content below assumes that the default target installation directory was chosen
during installation.
For the latest Pelco documentation, visit http://pdn.pelco.com.
After you’ve found the IP camera on your network and displayed its live stream on your display, you will
probably want to start controlling your camera’s viewing position: up and down and left and right, as well as
magnification (zoom), focus, and camera iris.
This section contains sample C# and C++ that illustrates how to display and control video streams.
Complete C# and C++ sample programs are contained in the following subdirectory where the Pelco SDK
is installed: Pelco\API\SampleCode\PTZControlWrapperSample
The StopContinuous method is available to stop the camera from continually moving, and the Stop()
call is available to stop Lens control (zoom, iris, and focus) actions. To stop continuous positioning calls,
pass in a 0 value. For example, after executing ContinuousMove, call ContinuousMove(0, 0) to stop
moving.

To move your IP camera’s current view, you need to start using the Pelco SDK’s PTZ Control Wrapper. The
PTZ Control Wrapper is an easy to use tool for controlling various PTZ and lens related functionality. For
this section we’ll only focus on panning and tilting the camera.
As in the previous section we’ll be examining the sample project code. Specifically, this section covers the
PTZ Control Wrapper. This sample project exhibits PTZ Control Wrapper functionality.
NOTE: PTZ control functionality is also available as part of the PelcoAPIViewer. For each of the
methods described in this topic, there is an equivalent method in the PelcoAPIViewer API.
Initializing the PTZ Control Wrapper

NOTE: The related source code for this entry can be found in main.cpp’s main function (for C
++) or Program.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper sample
project.
To instantiate the managed PTZ Control Wrapper instance, use the following parameters:
36
Your IP camera’s current IP address
Your IP camera’s port number
Your IP camera’s service ID (usually 1 unless this number represents a channel in a multi-
channel encoder)
C++ Example
PelcoAPI::PTZControlWrapper ptzControlWrapper("10.220.196.144”, 49152, 1);
You also need to check if authentication is enabled for the camera, and if so, set the authentication
credentials. For example:

if (ptzControlWrapper.IsAuthenticationEnabled())
{
// Set the user name to "admin", the password to "admin_user", and use
basic authentication
AuthenticationCredentials credentials("admin", "admin_password",
PelcoAPI::AuthenticationCredentials::BASIC);
ptzControlWrapper.SetAuthenticationCredentials(&credentials);
}
After you are finished with the camera operations, stop all PTZ Control Wrapper actions:
bool bSuccess = ptzControlWrapper.Stop();
NOTE: The following stop actions are available:

• To stop Lens control actions such as zoom, iris, and focus, use the Stop() call.
• To stop continuous movement triggered by ContinuousMove, ContinuousPan, and
ContinuousTilt, use the StopContinuous() call.
C# Example
ManagedPTZControlWrapperNet managedPTZControl = new

ManagedPTZControlWrapperNet("10.220.196.144”, 49152, 1);
You also need to check if authentication is enabled for the camera, and if so, set the authentication
credentials. For example:

#define CAMERA_IP_ADDRESS "10.220.196.179"
#define PORT_NUMBER 80
#define CAMERA_NUMBER 1

if (managedPTZControl.IsAuthenticationEnabled(CAMERA_IP_ADDRESS,
CAMERA_PORT, CAMERA_NUMBER))
{
// Set the user name to "admin", the password to "admin_password", and use
basic authentication
PelcoAPI::AuthenticationCredentials authentication("admin",
"admin_password", PelcoAPI::AuthenticationCredentials::BASIC);
managedPTZControl.SetAuthenticationCredentials(&authentication);
}
37
After you are finished with the camera operations, stop all PTZ Control Wrapper actions:
Boolean bSuccess = managedPTZControl.Stop();
NOTE: The following stop actions are available:

• To stop Lens control actions such as zoom, iris, and focus, use the Stop() call.
• To stop continuous movement triggered by ContinuousMove, ContinuousPan, and
ContinuousTilt, use the StopContinuous() call.
Continuous Panning
project.
This entry covers the portion of the sample project that deals with moving the camera left and right.
1. Initialize the PTZ Control Wrapper.
Refer to Initializing the PTZ Control Wrapper for details.
2. Call the PTZ Control Wrapper instance’s ContinuousPan method.
• To pan your IP camera left, pass in a negative rotational x parameter.
• To pan the IP camera right, pass in a positive value for the rotational x parameter.
For more details on the ContinuousPan method, please refer to the PTZ Control Wrapper API
reference documentation.
C++ Example:
//panning left
bool bSuccess = ptzControlWrapper.ContinuousPan(-10000);
//panning right
bool bSuccess = ptzControlWrapper.ContinuousPan(10000);
C# Example:
//panning left
Boolean bSuccess = managedPTZControl.ContinuousPan(-10000);
//panning right
Boolean bSuccess = managedPTZControl.ContinuousPan(10000);
3. When you want to stop the camera from continually moving, use the StopContinuous() method
(refer to Continuous Stop for details), or pass in a 0 value to the ContinuousPan method as shown in
the following example.
C++ Example:
bool bSuccess = ptzControlWrapper.ContinuousPan(0);
C# Example:
Boolean bSuccess = managedPTZControl.ContinuousPan(0);
38
Continuous Tilting
NOTE: The related source code for this entry can be found in main.cpp’s main function (for C++)
or Program.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper C++ sample
project.
This entry covers the portion of the sample project that deals with moving the camera up and down.
2. Call the PTZ Control Wrapper instance’s ContinuousTilt method.
• To tilt the IP camera down, pass in a negative rotational y value for the second parameter.
• To tilt the IP camera up, pass in a positive value for the rotational y parameter.
For more details on the ContinuousTilt method, please refer to the PTZ Control Wrapper API
C++ Example:
//tilting down
bool bSuccess = ptzControlWrapper.ContinuousTilt(-9000);
//tilting up
bool bSuccess = ptzControlWrapper.ContinuousTilt(9000);
C# Example:
//tilting down
Boolean bSuccess = managedPTZControl.ContinuousTilt(-9000);
//tilting up
Boolean bSuccess = managedPTZControl.ContinuousTilt(9000);
(refer to Continuous Stop for details), or pass in a 0 value to the ContinuousTilt method as shown
in the following example.
C++ Example:
bool bSuccess = ptzControlWrapper.ContinuousTilt(0);
C# Example:
Boolean bSuccess = managedPTZControl.ContinuousTilt(0);
Continuous Diagonal Movement

or Program.cs’s Main function (for C#), which belongs to the PTZ Control Wrapper C++ sample
project.
This entry covers the portion of the sample project that deals with continuously moving the camera in a
diagonal manner.
39

2. Call the ContinuousMove method.
The first parameter represents both speed and direction on the X plane. Use a negative integer to pan
left and 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, pplease refer to the PTZ Control Wrapper API reference documentation.
C++ Example:
//tilting down
bool bSuccess = ptzControlWrapper.ContinuousMove(10000, -10000);
//tilting up
bool bSuccess = ptzControlWrapper.ContinuousMove(10000, 10000);
C# Example:
//tilting down
Boolean bSuccess = managedPTZControl.ContinuousMove(10000, -10000);
//tilting up
Boolean bSuccess = managedPTZControl.ContinuousMove(10000, 10000);
(refer to Continuous Stop for details), or pass in a 0 value to the ContinuousMove method as shown
in the following example.
C++ Example:
bool bSuccess = ptzControlWrapper.ContinuousMove(0,0);
C# Example:
Boolean bSuccess = managedPTZControl.ContinuousMove(0,0);
Stopping Continuous Movement

To stop the camera from continually moving, call the StopContinuous method.
C++ Example:
bool bSuccess = ptzControlWrapper.StopContinuous();
C# Example:
Boolean bSuccess = managedPTZControl.StopContinuous();
Enabling Continuous Pan/Tilt/Move and Zoom APIs via UDP Instead of TCP
Call the PTZ Control Wrapper's SetLowLatencyMode method, passing in true as an argument. This
will send the subsequent ContinuousMove, ContinuousTilt, ContinuousPan, StopContinuous
and Zoom calls via UDP.
C++ Example:
bool bSuccess = ptzControlWrapper.SetLowLatencyMode(true);
40
C# Example:
Boolean bSuccess = managedPTZControl.SetLowLatencyMode(true);
Zoom API calls over UDP currently work on Sarix firmware 1.7.41 and higher.
Panning to a Specific Position

project.
This entry covers the portion of the sample project that deals with moving the camera to a specific point in
2D space. Units are shown in centidegrees (hundredths of a degree).
2. Call the PTZ Control Wrapper’s AbsolutePan method, passing in the desired position on the rotational
X plane.
• Passing a negative value moves left of the home position.
• Passing a positive value moves right of the home position.
For more details on the AbsolutePan method, please refer to the PTZ Control Wrapper API reference
documentation.
Generally, the panning range is limited to 0 to 360 degrees (0 to 36,000 centidegrees). This limit might
differ, depending on the type of camera used.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsolutePan(36000);
C# Example:
Boolean bSuccess = managedPTZControl.AbsolutePan(36000);
Tilting to a Specific Position

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

For more details on the AbsoluteTilt method, refer to the PTZ Control Wrapper API reference
documentation.
Generally, the tilting range is limited to 0 to -90 degrees (0 to -9000 centidegrees). This limit might differ,
depending on the type of camera used.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsoluteTilt(-9000);
C# Example:
Boolean bSuccess = managedPTZControl.AbsoluteTilt(-9000);
Moving to a Specific Position

project.
2. Call the PTZ Control Wrapper’s AbsoluteMove method, passing in the desired position on the
rotational X and Y planes.
• Passing a negative value for X moves the camera left of the home position.
• Passing a positive value for X moves the camera right of the home position.
• Passing a negative value for Y moves the camera down from horizontal.
• Passing a positive value for Y moves the camera up from horizontal.
Refer to your camera model’s specifications for tilt position limits. For more details on the
AbsoluteMove method, please refer to the PTZ Control Wrapper API reference documentation.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsoluteMove(20, 40);
C# Example:
Boolean bSuccess = managedPTZControl.AbsoluteMove(20, 40);
Moving to a Position Relative to the Current Location

Call the PTZ Control Wrapper's RelativeMove method, passing in the relative X and Y plane values
that the camera should move from the current location.
Units are shown in centidegrees (hundredths of a degree).
42
C++ Example:
bool bSuccess = ptzControlWrapper.RelativeMove(3000, 5000);
C# Example:
Boolean bSuccess = managedPTZControl.RelativeMove(3000, 5000);
Getting the Camera’s Current Position

project.
This entry covers the portion of the sample project that deals with returning the camera current position
expressed as a specific point in 3D space.
2. Call the PTZ Control Wrapper’s GetAbsolutePosition method.
For more details on the GetAbsolutePosition method, please refer to the PTZ Control Wrapper API
C++ Example:
int positionX = 0;
int positionY = 0;
bool bSuccess = ptzControlWrapper.GetAbsolutePosition(&positionX,
&positionY);
C# Example:
int positionX = 0;
int positionY = 0;
Boolean bSuccess = managedPTZControl.GetAbsolutePosition(ref positionX,
ref positionY);
Managing the Magnification (Zoom) Value

project.
This section describes how to change the camera’s current magnification level. Magnification refers to
the camera’s zoom level, which in turn describes the focal length for which the camera's lens is currently
set. Zoom level is expressed as 100 times the level of magnification that you want. For example, 1x
magnification becomes 100, and 18x magnification becomes 1800.
To change the current magnification level, and to later retrieve the current magnification value, do the
following:
43

2. Call the PTZ Control Wrapper’s AbsoluteZoom method passing in the desired zoom level.
If the request was successful, your camera’s magnification level should now be changed. For more
details on the AbsoluteZoom method, refer to the PTZ Control Wrapper API reference documentation.
C++ Example:
bool bSuccess = ptzControlWrapper.AbsoluteZoom(150);
C# Example:
Boolean bSuccess = managedPTZControl.AbsoluteZoom(150);
3. Call the GetAbsoluteZoom method to return the camera’s current magnification setting.
If the request was successful, your camera’s magnification level should be returned. For more details on
the GetAbsoluteZoom method, refer to the PTZ Control Wrapper API reference documentation.
C++ Example:
int magnification = 0;
bool bSuccess = ptzControlWrapper.GetAbsoluteZoom(magnification);
C# Example:
int magnification = 0;
Boolean bSuccess = managedPTZControl.GetAbsoluteZoom(ref magnification);
Managing the Focus Value

project.
NOTE: We recommend that you let your IP camera manage focus automatically.
This portion of the documentation covers how to focus near the IP camera or focus far away from the IP
camera.
2. Call the SetFocus method, passing in the desired focus command.
For a little background, the SetFocus method takes in only the following values:
0
To stop all focus related operations.
1
To start focusing farther.
2
To start focusing nearer.
If the request was successful, your camera’s focus should now be changing (unless you passed a
0). This will not stop until a SetFocus request is made with a different value, or if you call the Stop
method, which will stop movement or lens related action the camera is currently doing.
44
C++ Example:
bool bSuccess = ptzControlWrapper.SetFocus(1);

C# Example:
Boolean bSuccess = managedPTZControl.Focus(1);

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.
C++ Example:
bool bSuccess = ptzControlWrapper.AutoFocus(true);
C# Example:
Boolean bSuccess = managedPTZControl.AutoFocus(true);
Iris Control
project.
NOTE: We recommend that you let your IP camera manage its iris automatically.
This section demonstrates how to open and close your camera’s iris.
2. Call the SetIris method, passing in the desired iris command.
For a little background, the SetIris method takes only following values:
0
To stop all iris related operations.
1
To start closing the iris.
2
To start opening the iris.
If the request was successful, your camera’s iris should now be changing (unless you passed a 0). This
will not stop until the SetIris request is made with a different value, or if you call the Stop method,
which will stop movement or lens related action the camera is currently doing.
C++ Example:
bool bSuccess = ptzControlWrapper.SetIris(1);

bool bSuccess = ptzControlWrapper.SetIris(2);
45
C# Example:
Boolean bSuccess = managedPTZControl.Iris(1);

Boolean bSuccess = managedPTZControl.Iris(2);
3. Alternatively the recommended way of controlling the iris is to let your IP camera manage it
automatically. 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.
C++ Example:
bool bSuccess = ptzControlWrapper.AutoIris(true)
C# Example:
Boolean bSuccess = managedPTZControl.AutoIris(true)
Scripting
One of Pelco’s most powerful features enables users to manage and run scripts. Scripts allow you to
extend the behavior of Pelco devices with little effort. Before we show you how to use the SDK’s scripting
related features, it’s important to know about the different types of Pelco scripts:
Preset
A preset is a script that allows you to save a camera's stationary position, zoom, and other settings such as
auto-iris and auto-focus, collectively known as a bookmark. Users can save multiple presets per camera.
For example if you’re monitoring several specific points using the same camera, you can set one preset for
each location that needs to be monitored; each with its own set of zoom, iris, and focus values.
Presets that you create must be names, such as “PRESETX”, where the keyword PRESET must be used
(uppercase) followed by a positive integer. For example, PRESET9.
The number of presets that can be saved and activated is dependent on the Pelco device.
Pattern
A pattern is like a group of presets combined. For example, you might control an IP PTZ camera guarding
a hallway with two entrances and a window. With patterns, you can set a bookmark for camera behavior
that changes the camera’s view from one of the three points of interest to another every 15 seconds.
Patterns that you create must be names as “PATTERNX”, where the keyword PATTERN must be used
(uppercase) followed by a positive integer. For example, PATTERN5.
NOTE: There are pre-configured patterns that cannot be created. You cannot create a Pattern by
combining existing Presets.
Like a preset, patterns are typically only relevant for IP cameras. The number of patterns that can be
recorded and activated is dependent on the Pelco device. For example, the 16X and 18X models of the
Spectra IV can store only a single pattern, while the 22X, 23X and 35X Spectra IV models can store up to
eight patterns.
Normal Script
A general script consists of a group of commands that run over a set period of time. It is akin to a macro.
46
Creating a Preset
project.
These steps will show you how to create a preset.
2. Now set up your Pelco IP camera with a combination of settings that you want to save.
For example, the IP camera’s current viewing position, iris setting, focus setting, zoom, and so on.
3. Then call the SetPreset method, passing in the desired name of the preset.
Depending on whether the preset already exists or not, it will either create a new one or modify an
existing one by that name.
C++ Example:
bool bSuccess = ptzControlWrapper.SetPreset("PRESET99");
C# Example:
Boolean bSuccess = managedPTZControl.SetPreset("PRESET99");
Updating an Existing Preset

To update an existing preset, just following the steps outlined in Creating a Preset, ensuring that you
use the name of the existing preset to modify as the parameter for the SetPreset method.
Creating a Pattern
project.
This is just like creating a preset, except you will be saving more than one camera state.
2. Now set up your Pelco IP camera with a combination of settings that you want to save.
For example, the IP camera’s current viewing position, iris setting, focus setting, zoom, and so on.
3. Then call the StartPatternRecording method, passing in the desired name of the preset.
Depending on whether the pattern already exists or not, it will either create a new one or modify an
existing one by that name.
C++ Example:
bool bSuccess = ptzControlWrapper.StartPatternRecording("PATTERN99");
47
C# Example:
Boolean bSuccess = managedPTZControl.StartPatternRecording("PATTERN99");
4. At this point start performing the actions that you’d want your camera to remember as a pattern.
For example, if you have three points of interest you would first go to the first point of interest with a
certain zoom and focus level. After waiting for some predetermined time, you then move the camera’s
view into the second point of interest which has a different zoom level and iris setting; and do the same
for the final point of interest.
5. Finally, call the EndPatternRecording method, passing in the same pattern name as you did before.
C++ Example:
bool bSuccess = ptzControlWrapper.EndPatternRecording("PATTERN99");
C# Example:
Boolean bSuccess = managedPTZControl.EndPatternRecording("PATTERN99");
Going to an Existing Preset

project.
To move the device to a specific preset state, call the PTZ Control Wrapper’s GotoPreset method,
passing in the name of the preset.
The camera or device will move to the preset and then stop.
C++ Example:
bool bSuccess = ptzControlWrapper.GotoPreset("PRESET99");
C# Example:
Boolean bSuccess = managedPTZControl.GotoPreset("PRESET99");
Removing an Existing Preset

project.
To remove an existing preset, call the PTZ Control Wrapper’s RemovePreset method, passing in the
name of the preset.
The preset will then be deleted.
C++ Example:
bool bSuccess = ptzControlWrapper.RemovePreset("PRESET99");
48
C# Example:
Boolean bSuccess = managedPTZControl.RemovePreset("PRESET99");
Updating an Existing Pattern

To update an existing pattern, just following the steps outlined in Creating a Pattern. Ensure that you
use the name of the pattern to modify as the parameter for both the StartPatternRecording and
EndPatternRecording methods.
Executing an Existing Pattern

project.
To run a a script, call the PTZ Control Wrapper’s RunPattern method, passing in the name of the
script to run.
The script will continue to run until stopped by the user using the HaltPattern method, detailed
Stopping a Pattern Currently Being Executed on page 49.
C++ Example:
bool bSuccess = ptzControlWrapper.RunPattern("PATTERN99");
C# Example:
Boolean bSuccess = managedPTZControl.RunPattern("PATTERN99");
Stopping a Pattern Currently Being Executed

project.
If you want to stop a script that is currently running, call the PTZ Control Wrapper’s HaltPattern
method, passing in the name of the script to stop.
C++ Example:
bool bSuccess = ptzControlWrapper.HaltPattern("PATTERN99");
C# Example:
Boolean bSuccess = managedPTZControl.HaltPattern("PATTERN99");
49
Pelco SDK | Events and Alarms
Chapter
5
Events and Alarms
Overview
WARNING: The content in this section assumes that the default target installation directory was
chosen during installation.
For a list of the latest special issues and problems regarding the Event Arbiter library, visit http://
pdn.pelco.com/content/event-arbiter-library-issues
For a list of the latest special issues and problems regarding the Event Manager, visit http://pdn.pelco.com/
content/event-manager-issues.
Events and alarms are essentially XML formatted messages triggered by Pelco products, when some
particular criteria is met. Specifically Pelco products, acting as event providers, send these events and
alarms to their subscribers. Typically event providers are web services, while subscribers are software
clients. For example, if an IP camera’s MotionDetection service detected movement within a particular
region in the video frame, it can send an event to all of its subscribers such as a VMS.
This section contains sample C# and C++ that illustrates how to use events and alarms. Complete C# and
C++ sample programs are contained in the following subdirectory where the Pelco SDK is installed: Pelco
\API\SampleCode\EventArbiterSample.

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. Its main purpose is to provide users with ease of use in exchange for decreased control.
50
Event Arbiter Library

The Event Arbiter Library allows you to either subscribe directly to a device’s web service events or
indirectly; allowing you to choose to subscribe to the particular web service from all devices providing the
service.
Once a subscription is established, the software client just has to wait for an event to fire. The web service
will direct the event to your software client through the Pelco SDK. As for subscription renewals, it should
be noted that the Event Arbiter Library now also handles subscription renewals automatically. You will no
longer have to worry about renewing an event subscription.
The Event Arbiter Library allows subscriptions to all available web services for all devices on a 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. These events are sent when a physical alarm input on a device is
triggered.
• Diagnostic Reporting events. These events are sent when a hardware alarm on a device is triggered
(for example, a temperature alarm, video loss alarm, and so on).
• Motion Detection events. These events are sent when a motion alarm is triggered.
• Video Analytics events. These events are sent when a video analytic alarm is triggered.
• Relay Array Configuration events. These are included for backward compatibility only, no events are
generated.
Environment Pelco SDK Consequence

No System Manager Only direct device subscription available.
Not all event data will be parsed by Pelco SDK.
System Manager available; EventArbiter web Able to subscribe to all devices at once that provide
service active a specific web service.
All event data is available and parsed.
System Manager available; EventArbiter web Only direct device subscription is available.
service NOT active
Event Manager
The Event Manager represents a new tool for eventing and a new component within the Pelco SDK. The
Event Manager provides another abstraction on top of the Event Arbiter Library, and simplifies event
operations even further. It allows subscriptions to all available web services for all devices on a given
network that fall under a specific category. To subscribe, all you have to provide is the event category. The
categories are as follows:
• Alarm Array Configuration events
• Diagnostic Reporting events
• Motion Detection events
• Video Analytics events
• Relay Array Configuration events (included for backward compatibility only, no events are generated)
Environment Pelco SDK Consequence

No System Manager Does not apply -- can’t use Event Manager.
System Manager available; EventArbiter web Able to subscribe to all available web services
service active that are under a specified category via the SM
EventArbiter web service, in one subscription.
51
System Manager available; EventArbiter web All event data is available and parsed. If the SM
service NOT active EventArbiter web service is not active, however,
or if you choose not to use it, the EventManager
library will automatically subscribe to each
individual device's web service in the specified
category, resulting in many subscriptions.
Event Arbiter Library Compared to Event Manager

Event Arbiter Event Manager
Harder to use, but with more options and flexibility. Easier to use, but not as flexible: the user only
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. That is, a user can subscribe to all
MotionDetection web services for all devices with
just one request.
NOTE: For more Endura specific information, refer to the Appendix.
What’s Ahead
This is a high level overview of what steps are needed for handling events.
1. Subscribe to the desired web service's events through the Event Arbiter Library or the Event Manager.
2. Create the method that will handle the event. Associate that method with the Event Arbiter Library
instance’s event handler. Wait for an event to occur (or trigger an event to test), then handle it.
3. When no longer interested in receiving events (or when finished testing), unsubscribe from the
subscribed web service.
Creating an Event Agent

NOTE: The related source code for this entry (for C++) can be found in the MyEventAgent
header file, which belongs to the Event Arbiter Library C++ sample project. The related
source code for this entry (for C#) can be found in the class MyEventAgentNet in the
ManagedEventArbiterSample.cs file, which belongs to the Event Arbiter Library C# sample
project.
The main purpose of an EventAgent class is to deal with any incoming events that have been subscribed
to by the Event Arbiter.
To create your own EventAgent class, implement the NotifyEvent method in the IEventAgent
interface. NotifyEvent includes parameters for the response and the event.
Details of implementation are left to the user. However in the MyEventAgent sample class, we
demonstrate basic functionality for accessing event related data.
C++ Example:
#include "PelcoAPI/Trace.h"
52
#include "PelcoAPI/EventArbiterDefs.h"
#include "MyEventAgent.h"
//=======================================================
// Constructor
//=======================================================
MyEventAgent::MyEventAgent() : m_nCounter(0)
{
}
//=======================================================
// Destructor
//=======================================================
MyEventAgent::~MyEventAgent()
{
}
//=======================================================
// NotifyEvent
//=======================================================
void MyEventAgent::NotifyEvent(const char * szResponse, const Event *
pEvent)
{
TRACE_INFO("Notify EVENT %d: \n", ++m_nCounter);
TRACE_INFO("\tUDN: %s\n", pEvent->m_strUdn.c_str());

TRACE_INFO("\tService ID: %s\n", pEvent->m_strServiceId.c_str());
TRACE_INFO("\tUTC Time: %s\n", pEvent->m_strUtcEventTime.c_str());
TRACE_INFO("\tType: %d\n", (int) pEvent->m_nType);

TRACE_INFO("\tFriendly Name: %s\n", pEvent-
>m_strDeviceFriendlyName.c_str());
if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION)
{
TRACE_INFO("\tAssociated Camera UDN: %s\n", pEvent-
>m_strAssociateCameraUdn.c_str());
for (size_t i = 0; i < pEvent ->m_alarmOrRelayInfo.size(); i++)
{
TRACE_INFO("\tAlarm ID: %d\n", pEvent->m_alarmOrRelayInfo[i]-
>m_nId);
TRACE_INFO("\t\tSeverity: %d\n", pEvent-
>m_alarmOrRelayInfo[i]->m_nSeverity);
TRACE_INFO("\t\tChanged: %s\n", (pEvent-
>m_alarmOrRelayInfo[i]->m_bChanged ? "Yes" : "No"));
TRACE_INFO("\t\tState: %s\n", (pEvent->m_alarmOrRelayInfo[i]-
>m_bState ? "On" : "Off"));
}
}
else if (pEvent->m_nType ==
PelcoAPI::EVENT_TYPE_RELAY_ARRAY_CONFIGURATION)
{
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size(); i++)
{
TRACE_INFO("\tRelay ID: %d\n", pEvent->m_alarmOrRelayInfo[i]-
>m_nId);
TRACE_INFO("\t\tChanged: %s\n", (pEvent-
>m_alarmOrRelayInfo[i]->m_bChanged ? "Yes" : "No"));
TRACE_INFO("\t\tState: %s\n", (pEvent->m_alarmOrRelayInfo[i]-
>m_bState ? "On" : "Off"));
}
}
else if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_MOTION_DETECTION)
{
53
TRACE_INFO("\tAlarm State: %s\n", (pEvent->m_bAlarmState ? "On" :

"Off"));
}
else if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_VIDEO_ANALYTICS)
{
TRACE_INFO("\tAlarm State: %s\n", (pEvent->m_bAlarmState ? "On" :
"Off"));
TRACE_INFO("\tSeverity: %d\n", pEvent->m_nVideoAnalyticsSeverity);
}
TRACE_INFO("EVENT Details: \n%s\n", szResponse);

}
C# Example:
class MyEventAgentNet:PelcoAPI.IEventAgentNet
{
Int32 nCounter = 0;
public void NotifyEvent(String sResponse, PelcoAPI.EventNet eventNet)
{
Console.Write("\nNotify EVENT {0}:\n", ++nCounter);
Console.Write("\tUDN: {0}\n", eventNet.m_sUdn);
Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);
Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime);
Console.Write("\tType: {0}\n", eventNet.m_nType);
Console.Write("\tFriendly Name: {0}\n",
eventNet.m_sDeviceFriendlyName);
if (eventNet.m_nType == 1)
{
Console.Write("\tAssociated Camera UDN: {0}\n",
eventNet.m_sAssociateCameraUdn);
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++)
{
Console.Write("\tAlarm ID: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nId);
Console.Write("\t\tSeverity: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nSeverity);
Console.Write("\t\tState: {0}\n",
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
}
else if (eventNet.m_nType == 2)
{
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++)
{
}
}
{
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ?
"On" :
"Off"));
}
{
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ?
"On" :
"Off"));
Console.Write("\tSeverity: {0}\n",
54
eventNet.m_nVideoAnalyticsSeverity);
}
Console.Write("EVENT Details:\n{0}\n", sResponse);
}
}
Returning the Event Subscription URL

NOTE: The related source code for this entry can be found in main.cpp’s main function (for C++),
or Program.cs’s Main function (for C#), which belongs to the System Manager Wrapper C++ and
C# sample project.
1. Initialize the System Manager Wrapper.
Refer to Initializing the System Manager Wrapper for details.
2. Call the System Manager Wrapper instance’s GetDeviceServiceAttribute method, passing in the
following:
login ID
A result returned from a successful call to the UserLogin method.
target device’s Unique Device Name (UDN)
To retrieve a deviceUDN, cycle through the stored results of a GetDevices call within
your IDeviceStorage class instance. For details, refer to Querying Available Devices
from the System Manager.
web service’s Service ID
A URN value found in the web service’s corresponding WSDL file.
attribute name of SYS_UpnpEventSubUrl
pointer to the variable that will hold the result
PelcoAPI::xstring sEvntUrl;
bSuccess = sm.GetDeviceServiceAttribute(loginId,
"UUID:B11DBF247E984B9BB83B7E74497DE6CA",
"urn:schemas-pelco-com:service:MotionDetection:1",
"SYS_UpnpEventSubUrl", &sEvntUrl)
Initializing the Event Arbiter Library
Initializing the Event Arbiter Library for C++

NOTE: The related source code for this entry can be found in EventArbiterSample.cpp’s
main function which belongs to the Event Arbiter Library sample project. This assumes that you
have already completed the steps outlined in Creating an Event Agent.
2. Declare the Event Arbiter Library instance. Set the Event Arbiter Library instance's network location and
port number, using the System Manager’s IP address and port number.
Refer to Automatically Determining the System Manager’s IP Address and Port Number for more
details.
PelcoAPI::IEventArbiter * pEventArbiter = new

PelcoAPI::EventArbiter("10.220.196.187", "60001", true);
55
3. Set the Event Arbiter Library instance's network location and port number, using the local host IP
address and port number.
pEventArbiter->SetupIPAndPort("10.220.196.200", "9716");
4. Register your Event Agent class with the Event Arbiter Library instance.
For details on creating an Event Agent, refer to Creating an Event Agent.
MyEventAgent agent;
pEventArbiter->RegisterEventAgent(&agent);
Initializing the Event Arbiter Library for C#

A System Manager Is Available on Your Network

NOTE: The related source code for this entry can be found in
ManagedEventArbiterSample.cs’s main function, which belongs to the Event Arbiter Library
C# sample project. This assumes that you have already completed the steps outlined in Creating an
Event Agent.
2. Initialize your implemented Event Agent.
Refer to Creating an Event Agent for details.
MyEventAgentNet pAgent = new MyEventAgentNet();
3. Next, declare the Event Arbiter Library instance. Set the following parameters:
Event Arbiter Library instance's network location and port number
The client machine where it resides.
Your implemented Event Agent to register
The System Manager’s IP address and port number.

Refer to Automatically Determining the System Manager’s IP Address and Port Number for
more details.
boolean
True to force the EventArbiter library to use the System Manager, false otherwise.
PelcoAPI.EventArbiterNet pEventArbiter = new PelcoAPI.EventArbiterNet(

"10.220.196.200", "9716", pAgent, "10.220.196.187", "60001", true);
A System Manager Is Not Available on Your Network

Use empty strings for parameters representing the System Manager’s IP address and port
number.
56
Set the last parameter to false.

Explicitly not rely on the System Manager‘s EventArbiter service.
PelcoAPI.EventArbiterNet pEventArbiter = new PelcoAPI.EventArbiterNet(

"10.220.196.200", "9716", pAgent, "", "", false);
Initializing the Event Manager

The related source code for this entry (for C++) can be found in EventManagerSample.cpp’s main
function, which belongs to the Event Manager Library C++ sample project. The related source code for this
entry (for C#) can be found in the ManagedEventManagerSample.cs’s main function, which belongs to
the Event Manager C# sample project.
This assumes that you have already completed the steps outlined in the Creating an Event Agent. These
steps also require the existence of a System Manager on your network.
MyEventAgentNet pAgent = new MyEventAgentNet();
The System Manager’s IP address and port number.

Refer to Automatically Determining the System Manager’s IP Address and Port Number for
more details.
boolean
True to stop the EventArbiter library from using the System Manager. False to start the
EventArbiter library using the System Manager.
C++ Example:
MyEventAgent agent;
PelcoAPI::IEventManager * pEventManager = new PelcoAPI::EventManager(
"10.220.196.200", "9716", &agent, false, "10.220.196.187", "60001");
C# Example:
PelcoAPI.EventManagerNet pEventManager = new PelcoAPI.EventManagerNet(

"10.220.196.200", "9716", pAgent, false, "10.220.196.187", "60001");
Device or Service Specific Subscriptions

If you want to subscribe to events from a specific web service or device, then this section will show you the
most common scenarios.
57
Using the Event Arbiter Library to Subscribe Using the Device’s IP Address
NOTE: This entry is relevant for users who are not relying on either the System Manager
or its EventArbiter service. The related source code for this entry can be found in
EventArbiterSample.cpp’s main function (for C++) or ManagedEventArbiterSample.cs’s
main function (for C#), which belongs to the Event Arbiter Library sample project.
This topic describes how to use the Event Arbiter Library to subscribe to a specific device’s particular web
service using the device’s IP address. Having an event subscription simply tells a device that you would
like to receive its event notifications. To request a event subscription, the following must be done:
1. Initialize the Event Arbiter Library.
Refer to Initializing the Event Arbiter Library for details.
2. Call the Event Arbiter wrapper instance's SubscribeToEvents method (SubscribeEvents in C#),
passing the event subscription URL.
For details, refer to Returning the Event Subscription URL. If the request was successful, the method
will return the event subscription's unique ID which will allow users to either renew or unsubscribe the
event subscription. If unsuccessful, the method returns NULL.
NOTE: Pelco SDK now automatically handles subscription renewals.
C++ Example:
const char * szSid_1 = pEventArbiter-

>SubscribeToEvents("http://10.220.196.184:80/event/
AlarmArrayConfiguration-1");
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(

"http://10.220.196.184:80/event/AlarmArrayConfiguration-1”);
Using the Event Arbiter Library to Subscribe Using the Event Subscription URL
service using the Event Subscription URL.
NOTE: This entry is ONLY relevant for users who use an Endura network, specifically with an
active System Manager and an enabled EventArbiter service on the System Manager. The related
source code for this entry can be found in EventArbiterSample.cpp’s main function (for C+
+) or ManagedEventArbiterSample.cs’s main function (for C#), which belongs to the Event
Arbiter Library sample project.
2. Construct an event service ID.
It consists of the device’s UDN and the web service’s URN, which is its namespace on its WSDL file.
(For details on determining a web service’s ID, refer to Returning the Event Subscription URL.)
C++ Example:
std::string strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-

b48231f62f15/urn:pelco-com:serviceId:AlarmArrayConfiguration-1";
C# Example:
String strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/

urn:pelcocom:serviceId:AlarmArrayConfiguration-1";
58
3. Call the Event Arbiter Library instance's SubscribeToEvents method (SubscribeEvents in C#),
passing the event service ID.
If the request was successful, the method will return the event subscription's unique ID which will allow
users to either renew or unsubscribe the event subscription.
C++ Example:

>SubscribeToEvents(strEventServiceId.c_str());
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(strEventServiceId);
Using the Event Arbiter Library to Subscribe to All Instances of a Service

If you want to subscribe to all devices that provide a specific web service like MotionDetection (or any other
web service that has events), do the following:
2. Construct an event URN.
It is essentially the SOAP web service URN. You can determine this URN value looking at the web
service’s associated WSDL file (it should be near the top of the file).
C++ Example:
std::string strEventUrn = "urn:schemas-pelco-

com:service:MotionDetection:1";
C# Example:
String strEventUrn = "urn:schemas-pelco-com:service:MotionDetection:1";
3. Call the Event Arbiter wrapper instance's SubscribeToEvents method (SubscribeEvents in C#),
passing the event URN.
C++ Example:

>SubscribeToEvents(strEventUrn.c_str());
C# Example:
String strSid_2 = pEventArbiter.SubscribeEvents(strEventUrn);
59
Using the Event Arbiter Library to Subscribe to a Device's Web Service

service using the Event Subscription URL.
2. Construct an event service ID.
It consists of the device’s UDN and the web service’s URN, which is its namespace on its WSDL file.
(For details on determining a web service’s ID, refer to Returning the Event Subscription URL.)
C++ Example:
std::string strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-

b48231f62f15/urn:pelco-com:serviceId:VideoAnalytics-2";
C# Example:
String strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/

urn:pelcocom:serviceId:VideoAnalytics-2";
3. Call the Event Arbiter Library instance's SubscribeToEvents method (SubscribeEvents in C#),
passing the event service ID.
C++ Example:

>SubscribeToEvents(strEventServiceId.c_str());
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(strEventServiceId);
Using the Event Arbiter Library to Unsubscribe from a Service

NOTE: The related source code for this entry can be found in EventArbiterSample.cpp’s
main function (for C++) or ManagedEventArbiterSample.cs’s main function (for C#), which
belongs to the Event Arbiter Library sample project. This entry assumes that the user has already
completed the steps outlined in any of the Event Arbiter subscription-related entries.
To unsubscribe from an existing event subscription, call the Event Arbiter wrapper instance's
UnSubscribeToEvents method (UnsubscribeEvents in C#), passing the subscription identifier.
You should receive subscription IDs on successful calls to SubscribeToEvents. If the request was
successful, the method will return a 1 (for C++) or true (for C#). Otherwise it will return a 0 (for C++) or
false (for C#).
C++ Example:
const char * szSid_1 = pEventArbiter->SubscribeToEvents(

"urn:schemas-pelco-com:service:MotionDetection:1");
60
// ... misc logic ...

pEventArbiter->UnSubscribeToEvents(strSid_1);
C# Example:
String strSid_1 = pEventArbiter.SubscribeEvents(

"urn:schemas-pelco-com:service:MotionDetection:1");
// ... misc logic ...
Boolean ret = pEventArbiter.UnsubscribeEvents(strSid_1);
Mass Subscriptions by Category

If you don’t really know what particular events or devices where you would like a subscription, then this
section is for you. It will show you how to subscribe to all events that fall under your desired category.
Using the Event Manager to Subscribe to All Services

NOTE: The related source code for this entry can be found in EventManagerSample.cpp’s
main function (for C++) or ManagedEventManagerSample.cs’s main function (for C#), which
belongs to the Event Manager Library sample project. Also note that the Event Manager requires
the presence of a System Manager on the network.
The following steps will allow you to subscribe to all events that fall under one of several categories defined
by the Pelco SDK.
1. Initialize the Event Manager.
Refer to Initializing the Event Manager for details.
2. Call the Event Manager instance's Start method, passing the desired event type as defined by the
Pelco SDK.
The Event Manager will now start ‘listening’ to events. Use one or more of the following options (you
can add several of these values together to subscribe to more than one category of event at a time):
C++ Example:
enum EventType
{
EVENT_TYPE_UNKNOW = 0x00000000,
EVENT_TYPE_ALARM_ARRAY_CONFIGURATION = 0x000000001,
EVENT_TYPE_RELAY_ARRAY_CONFIGURATION = 0x00000002,
EVENT_TYPE_MOTION_DETECTION = 0x00000004,
EVENT_TYPE_VIDEO_ANALYTICS = 0x00000008,
EVENT_TYPE_DIAGNOSTIC_REPORTING = 0x00000010,
EVENT_TYPE_MASK = 0x0000001F
};
C# Example:
enum REGISTER_EVENTS
{
ALARM_ARRAY_CONFIGURATION = 0x00000001,
RELAY_ARRAY_CONFIGURATION = 0x00000002,
MOTION_DETECTION = 0x00000004,
VIDEO_ANALYTICS = 0x00000008,
DIAGNOSTIC_REPORTING = 0x00000010
}
Alarm Array Configuration
61
Events that are related to the AlarmArrayConfiguration web service, such as an alarm
circuit connected to the camera has been turned on or off.
Relay Array Configuration
Events that are related to the RelayArrayConfiguration web service. This web service
generates no events. Tthe functionality is provided for backward compatibility only.
Motion Detection
Events that are related to the MotionDetection web service, such as the camera started or
stopped detecting motion.
Unknown
This is a system-reserved value and can be disregarded.
Mask
A system-reserved value that combines all the different event categories, allowing you to
subscribe to all of them at once.
NOTE: Always refer to the EventArbiterDefs header for the latest options. If the request was
successful, the method will return true; false otherwise.
C++ Example:
bool ret = pEventManager->Start(PelcoAPI::EVENT_TYPE_MASK);
C# Example:
Boolean ret = pEventManager.Start(REGISTER_EVENTS.EVENT_TYPE_MASK);
Using the Event Manager to Unsubscribe from All Services

NOTE: The related source code for this entry can be found in EventManagerSample.cpp’s
main function (for C++) or ManagedEventManagerSample.cs’s main function (for C#), which
belongs to the Event Manager Library sample project. Also note that the Event Manager requires
the presence of a System Manager on the network. This entry assumes that the user has already
completed the steps outlined in the Event Manager subscription-related entry.
To unsubscribe from an existing event subscription for Event Manager, call the Event Manager
instance’s Stop method.
If successful it will return true, false otherwise. The following example unsubscribes from all active event
subscriptions at once.
C++ Example:
bool ret = pEventManager->Stop();
C# Example:
Boolean ret = pEventManager.Stop();
Handling Incoming Events

NOTE: The related source code for this entry can be found in MyEventAgent.cpp’s
NotifyEvent function (for C++), or the NotifyEvent function in the class MyEventAgentNet
(for C#), which belongs to the Event Arbiter Library sample project. The availability of some data is
62
dependent on the availability of a System Manager on your network, that is, if a System Manager is
not online, then some event data will be missing.
The Pelco SDK already parses event related data for you. All that is required is for you to figure out how to
use our provided Event struct.
1. Define a class that implements the EventAgent interface.
For details, refer to Creating an Event Agent.
2. Within your EventAgent implementation is the NotifyEvent method.
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
C++ Example:
void MyEventAgent::NotifyEvent(const char * szResponse, const Event *

pEvent)
{
//... other logic ...
pEvent->m_strUdn.c_str();
pEvent->m_strServiceId.c_str();
pEvent->m_strUtcEventTime.c_str();
pEvent->m_nType;
pEvent->m_strDeviceFriendlyName.c_str();
C# Example:
Int32 nCounter = 0;
public void NotifyEvent(String sResponse, PelcoAPI.EventNet
eventNet)
{
Console.Write("\nNotify EVENT {0}:\n", ++nCounter);
Console.Write("\tUDN: {0}\n", eventNet.m_sUdn);
Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);
Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime);
Console.Write("\tType: {0}\n", eventNet.m_nType);
Console.Write("\tFriendly Name: {0}\n",
eventNet.m_sDeviceFriendlyName);
If the incoming event is an alarm from the AlarmArrayConfiguration web service, it will provide
information on the camera it is associated with as well as general alarm data.
C++ Example:
if (pEvent->m_nType ==
PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION)
{
//the camera associated to this event
pEvent->m_strAssociateCameraUdn.c_str();
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size();

i++)
{
//alarm ID
pEvent->m_alarmOrRelayInfo[i]->m_nId;
63
//alarm severity
pEvent->m_alarmOrRelayInfo[i]->m_nSeverity;
//the state of the alarm 0 off 1 on
pEvent->m_alarmOrRelayInfo[i]->m_bState;
}
}
C# Example:
if (eventNet.m_nType == 1)
{
Console.Write("\tAssociated Camera UDN: {0}\n",
eventNet.m_sAssociateCameraUdn);
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
Console.Write("\t\tSeverity: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nSeverity);
}
}
The RelayArrayConfiguration web service does not generate events. The functionality is provided
for backwards compatibility only.
C++ Example:
PelcoAPI::EVENT_TYPE_RELAY_ARRAY_CONFIGURATION)
{
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size();
i++)
{
pEvent->m_alarmOrRelayInfo[i]->m_nId;
pEvent->m_alarmOrRelayInfo[i]->m_bState;
}
}
C# Example:
{
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
}
}
If the incoming event is from the MotionDetection web service, it will show whether or not the motion
detection region is active or inactive.
C++ Example:
PelcoAPI::EVENT_TYPE_MOTION_DETECTION)
64
{
pEvent->m_bAlarmState;
}
C# Example:
{
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" :
"Off"));
Console.Write("\tSeverity: {0}\n",
eventNet.m_nVideoAnalyticsSeverity);
}
The szResponse parameter contains the raw event data in XML format. This is useful for debugging, or
XML data binding to your classes.
C++ Example:
TRACE_INFO("EVENT Details: \n%s\n", szResponse);
C# Example:
Console.Write("EVENT Details:\n{0}\n", sResponse);
Polling Events
NOTE: The related source code for this entry can be found in EventArbiterSample.cpp's
main function (for C++) or ManagedEventArbiterSample.cs's Main function (for C#), which
belongs to the Event Arbiter Library sample project. The availability of some data is dependent on
the availability of a System Manager on your network, that is, if a System Manager is not online,
then some event data will be missing.
This API allows you to poll events instead of having to perform a callback.
1. Set the EventAgent to NULL in the RegisterEventAgent method.
C++ Example:
pEventArbiter->RegisterEventAgent(NULL);
C# Example:
MyEventAgentNet pAgent = null;
2. To poll events one by one using Event Arbiter or Event Manager, call the Event Arbiter or Event
Manager instance's PollEvent method.
std::string strRawEvent;
PelcoAPI::Event pelcoEvent
// Additional logic...
if (pEventArbiter->PollEvent(strRawEvent, pelcoEvent))
// ...
String sRawEvent = "";

PelcoAPI.EventNet pelcoEvent = null;
// Additional logic...
if (pEventManager.PollEvent(ref sRawEvent, ref pelcoEvent))
// ...
65
Pelco SDK | Extracting Audio and Video Metadata
Chapter
6
Extracting Audio and Video Metadata
Extracting Audio and Video Metadata

There will always be special situations, such as custom video analytics, that call for processing video meta-
data like timestamps.
This section contains sample C# and C++ that illustrates how to use meta-data. Complete C# and C++
sample programs are contained in the following subdirectory where the Pelco SDK is installed: Pelco\API
\SampleCode\MetaDataParserSample

The Meta-data Parser is a utility for parsing Pelco Video Elementary Stream (VES) meta-data from Pelco
streams. Pelco VES frames contain the following meta-data:
• MotionDetection active areas
• Timestamps
• Pelco Analytics drawing primitives
• RSA Signature and other information necessary to verify the frame
The Meta-data Parser consists of an interface that provides access to the various objects within the
elementary stream.
66
Motion Detection Metadata
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.
What motion detection metadata is available? Currently in terms of metadata, each video frame can only
hold a single ROI. Consequently, for each frame, the metadata describes the length and width of the ROI,
while also holding a Pelco base64 bit mask for the state of the ROI.
NOTE: The difference between Pelco base64 and standard base64 implementations is that the
Pelco version always appends an = character at the end of the encoded value.
Pelco Analytics Drawing Primitives
Drawing primitives are basic graphical elements. They encompass drawing points, fills, lines, arcs, and
even text. This basically contains information related to the points, lines, arcs, and so on.
Timestamps
Timestamp metadata represents the exact date and time when the video frame was captured. The
Metadata Parser Library can return this data in a number of ways.
struct timeval
The timestamp represented as a struct timeval.
tv_sec
The time interval in seconds since the epoch.
tv_usec
The time interval in microseconds since the epoch.
typedef struct timeval {

long tv_sec;
long tv_usec;
} timeval;
67
struct tm
The timestamp represented as a struct tm.
tv_sec
The time interval in seconds. (0-59)
tv_min
The time interval in minutes. (0-59)
tv_hour
The time interval in hours. (0-23)
tv_mday
The time interval in day of the current month. (1-31)
tv_mon
The time interval in months since January. (0-11)
tv_year
The time interval in years since 1900.
tv_wday
The time interval in days since Sunday. (0-6)
tv_yday
The time interval in days since January 1st. (0-365)
tv_isdst
A boolean that is true if it is currently daylight savings time, false otherwise.
typedef struct tm {
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
}
In addition to returning the data above, the Metadata Parser Library also returns the daylight savings offset,
the current timezone, and values in local time.
Getting Started
For more information about getting started and setting up the working directory, refer to Setting Up Sample
Projects.
Depending on whether you would like to use the release version of the Pelco SDK libraries or the debug
version, change the Working Directory value as appropriate. Assuming that you did not change the default
installation directory for the Pelco SDK, use C:\\Program Files\Pelco\API\Libs\Debug.
NOTE: If running in Release mode, change this path to C:\Program Files\Pelco\API\Libs
\Release.
What’s Ahead
This is a high level overview of possible tasks related to metadata:
68
1. Access the metadata from the stream.

2. Render metadata onto a video frame.
Initializing the Metadata Parser Class

belongs to the Metadata Parser C++ sample project.
1. Create a MetaDataParser instance.
2. Call its SetData method, passing the buffer containing the data to analyze and the buffer length as
parameters.
PelcoAPI::MetaDataParser parser;
parser.SetData(videoBuffer, length);
Creating a Metadata Renderer Class

NOTE: The related source code for this entry can be found in SampleMetaDataRenderer.cpp,
which belongs to the MetaDataParser C++ sample project. You are expected to implement the
actual logic.
This class is used for drawing onto video frames.
1. Implement the following required protected methods:
a) DrawLine to draw a line using two given points: 'v1' and 'v2'
virtual void DrawLine(const PelcoAPI::VECTOR &v1, const PelcoAPI::VECTOR

&v2,
PelcoAPI::COLOR color) throw();
b) DrawRectangle to draw a rectangle whose upper left corner is determined by the parameter v1,
while the lower right corner is determined by the parameter v2. If the fill parameter is set to true, the
rectangle should be solid. Otherwise, it should only be an outline.
virtual void DrawRectangle(const PelcoAPI::VECTOR &v1, const

PelcoAPI::VECTOR &v2,
PelcoAPI::COLOR color, bool fill) throw();
c) DrawPolygon to draw a polygon with corners defined within the Vector array. If the fill parameter is
set to true, the polygon should be solid. Otherwise, it should only be an outline.
virtual void DrawPolygon(PelcoAPI::VECTOR *vectors, unsigned int

count,PelcoAPI::COLOR fillColor, PelcoAPI::COLOR borderColor, bool fill)
throw();
d) DrawText
virtual void DrawText(const std::string &text, const PelcoAPI::VECTOR

&location,
PelcoAPI::COLOR color) throw();
2. (Optional) Implement the following protected methods:

a) BeginDraw to perform any pre-drawing work.
virtual void BeginDraw() throw();
69
b) EndDraw to perform any post-drawing work.
virtual void EndDraw() throw();

c) TransformVectorForDisplay to handle point translation and scaling.
virtual PelcoAPI::VECTOR TransformVectorForDisplay(const

PelcoAPI::VECTOR &v)
throw();
Retrieving the Current Timestamp Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessTimestamp
function, which belongs to the Metadata Parser C++ sample project.
1. Initialize the MetaDataParser.
For details, refer to Initializing the Metadata Parser Class.
2. Verify whether the parser has found a timestamp by calling the HasTimeStamp method, which will
return true if found, false otherwise.
if(true == parser.HasTimestamp()){
3. If there is a timestamp, call the GetTimeStampAsString method, passing in a local time Boolean
parameter, which if true returns the timestamp in local time, while false returns the UTC value:
std::string timestamp = parser.GetTimestampAsString(true, "%c");
Motion Detection Metadata
Retrieving Motion Detection Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessMotionData
1. Initialize the MetaDataParser. For details, refer to Initializing the Meta-Data Parser Class.
2. Check if the parser has found motion detection data by calling the HasMotionData method, which will
if(true == parser.HasMotionData()){
3. If there is motion detection metadata, call the GetMotionData method and pull the result into a new
MotionData instance.
PelcoAPI::MotionData *data = parser.GetMotionData();
4. Parse the resulting data from the MotionData instance.
if(NULL != data){
unsigned int cols = data->Columns();
unsigned int rows = data->Rows();
unsigned char *mask = data->Bitmask();
// Do something with the data here
// Delete the motion data object
70
Rendering Motion Detection Metadata

NOTE: The related source code for this entry can be found in main.cpp’s ProcessMotionData
NOTE: This entry assumes that the user has already completed the steps outlined in Creating a
Metadata Renderer Class.
2. Check if the parser has found motion detection data. Call the HasMotionData method, and if true,
retrieve the motion metadata.
if(true == parser.HasMotionData()){
PelcoAPI::MotionData *data = parser.GetMotionData();
3. After you retrieve the motion detection metadata, declare your MetaDataRenderer class.
SampleMetaDataRenderer renderer;
4. Create a new COLOR struct, setting the desired alpha transparency and colors to display on the screen.
In this example, the colors (red, green, blue) are fully opaque with zero transparency.
PelcoAPI::COLOR color = {255,0,128,255};
5. Render the motion metadata onto the screen by calling the RenderMotionData method.
renderer.RenderMotionData();
Drawing Metadata
Retrieving Drawing Metadata

NOTE: The related source code for this entry can be found in main.cpp’s
ProcessDrawingData function, which belongs to the Metadata Parser C++ sample project.
2. Determine if the parser has found drawing data by calling the HasDrawingData method, which will
if(true == parser.HasDrawingData()){
3. If drawing metadata is found, call the GetDrawingData method, pulling the result into a
DrawingData instance.
PelcoAPI::DrawingData *data = parser.GetDrawingData();
4. Parse the resulting data by iterating through the returned drawing primitives.
PelcoAPI::DrawingPrimitive *primitive = data->GetNextPrimitive();;

while(primitive != NULL){
primitive->GetPrimitiveType();
PelcoAPI::DrawingPrimitive::FreePrimitive(primitive);
primitive = data->GetNextPrimitive();
}
71
Rendering Drawing Metadata

NOTE: The related source code for this entry can be found in main.cpp’s RenderDrawingData
This entry assumes that the user has already completed the steps outlined in Creating a Metadata
Renderer Class.
1. Iinitialize the MetaDataParser. For details, refer to Initializing the Metadata Parser Class.
2. Determine if the parser has found drawing data by calling the HasDrawingData method, and if true,
retrieve the drawing metadata by calling the GetDrawingData.
if(true == parser.HasDrawingData()){
PelcoAPI::DrawingData *data = parser.GetDrawingData();
3. After you grab the drawing metadata, declare your MetaDataRenderer class.
SampleMetaDataRenderer renderer;
4. Create a new COLOR struct, setting the desired alpha transparency and colors to show on the screen. In
this example, the colors (red, green, and blue) are fully opaque with zero transparency.
PelcoAPI::COLOR color = {255,0,128,255};
5. Render the drawing metadata onto the screen by calling the RenderDrawingData method.
renderer.RenderDrawingData();
72
Chapter
7
Exporting Video
Overview
NOTE: The content in this section assumes that the default target installation directory was chosen
This section contains sample C# and C++ that illustrates how to perform exports. Complete C# and C
++ sample programs are contained in the following subdirectory where the Pelco SDK is installed C:
\Program Files\Pelco\API\SampleCode\ExporterSample
At some point, you’ll need to export your video into a variety of major formats.

The Exporter module is a Pelco API SDK component that can export playback video, and save it in either
AVI, MP4, 3GP, or PEF format. It is multi-threaded to help ensure good performance and to export as many
streams as possible at any given time. Moreover, users will be able to export or playback saved streams
without having to initialize the stream. Consequently it provides the flexibility to specify the camera, the
start time and an end time value. This tool is also able to embed meta-data (timestamp, and so on) into
streams (this requires transcoding which affects performance and authentication). When available, audio
will be included in the export in either PEF or AVI format.
Custom Application Development

Using the Exporter, a simple application can be written to select, initiate, and receive these streams to
save them to a video file. The most common file format for such video files is AVI. However, AVI is only
a container format, not a compression format. From this point forward, there are two principally different
implementations for video storage: re-coding and native.
Re-coding Video
To avoid a complicated process, decoding and re-encoding is often employed to allow the video to be
played back using the standard codecs provided with the Windows Media Player.
The native video format is either MPEG-4 or H.264, depending on the camera settings. If the video stream
coming from the camera is encoded using MPEG-4, the exported file will generally use MPEG-4 as well.
No re-coding will be necessary unless you add overlays to the export. If the video stream coming from
the camera is encoded using H.264, the exported file may use H.264 or MPEG-4, depending on the
73
Pelco SDK | Exporting Video
container format (3GP, AVI, MP4, PEF) and whether you add overlays to the export. (There is relatively
little difference in size between container formats and compression formats.)
By default, Windows Media Player supports MPEG-4, but not H.264. VLC supports both MPEG-4 and
H.264.
Native Video
For recording large amounts of video data, such as when building near line storage solutions, storage
in the original (or native) format is essential as it preserves the bit rate. To play back these native video
files, a codec that supports the full ISO MPEG-4 standard (or at least the ISO MPEG4 SP profile) must
be installed in the end user's media player. If a codec does not support the ISO MPEG-4 SP profile, the
received video will not play back. Fortunately there are many complete ISO MPEG-4 codecs available;
ranging from free, open source versions to highly optimized commercial versions
Getting Started
Projects.
What’s Ahead
This is a high level overview of possible tasks related to export.
1. Set up desired video clips to export.
• Configure desired parameters for each video clip to export.
• If overlays are desired, set up overlays for each video clip.
2. Start the export, and continue to poll its status until it finishes successfully or encounters an error.
Initializing the Exporter

The related source code for this entry (for C++) can be found in main.cpp’s main function, which
belongs to the Export C++ sample project. The related source code for this entry (for C#) can be found in
Program.cs’s Main function, which belongs to the Export C# sample project.
Create the EnduraExporter instance, and then call its Setup method, passing the following:
The location of the 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\Debug
\Plugins
NOTE: If running in Release mode, change this path to C:\Program Files
\Pelco\API\Libs\Release\Plugins.
The System Manager’s IP address.
For details on the importance of the System Manager for the Exporter, refer to Video
Exports in the Appendix.
The IP Address to use for receiving incoming stream(s)
The client machine using the Pelco SDK.
(Optional) The name of the user that is performing the export.
74
(Optional) The initial local port to use for the export.

NOTE: If you are running simultaneous exports, you must provide different
port values.
(Optional) The end port to use if initial port is in use.
The exporter will keep increasing port numbers starting with the initial port number until the
end port is reached.
C++ Example:
PelcoAPI::EnduraExporter exporter;
exporter.Setup("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins",
"10.220.196.187", "10.220.196.189", USERNAME, 8000, -1);
C# Example:
PelcoAPI.EnduraExporterNet pEnduraExporterNet = new

PelcoAPI.EnduraExporterNet();
pEnduraExporterNet.Setup("C:\\Program Files\\Pelco\\API\\Libs\\Debug\
\Plugins",
"10.220.196.187", "10.220.196.189", USERNAME, 8000, -1);
Setting Up Overlay Data on Video to Be Exported

NOTE: This entry assumes that you are already familiar with the content in Exporting Video.
NOTE: If you choose to embed overlays with your video export, regardless of input source stream’s
format, the resulting exported file will be in MPEG-4 format.
1. First decide on what type of overlay that you would like to create.
There are several types as defined in the EnduraExporterDefines header file:
enum OverlayType
{
OVERLAY_TYPE_TIMESTAMP = 0,
OVERLAY_TYPE_CAMERANAME = 1,
OVERLAY_TYPE_TEXTSTRING = 2,
OVERLAY_TYPE_PICTURE = 3
};
2. Next, create the overlay structure.

• If performing a single video clip export as described in Exporting A Single Video Clip, the user must
use the OverlayData method for each desired overlay type before starting the export.
exporter.OverlayData(PelcoAPI::OVERLAY_TYPE_TIMESTAMP,
PelcoAPI::OVERLAY_LOCATION_BOTTOM_LEFT, NULL, FONTNAME, 10,
fontColor, fontBgColor, 0);
pEnduraExporterNet.OverlayData(PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP,
PelcoAPI.OverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT, "",
FONTNAME, 10, FONTCOLOR, FONTBGCOLOR, 0, DATEFORMAT,
TIMEFORMAT);
75
• If performing a stitched video clip export described in Stitching Multiple Clips Into a Single Video
Export, the user must use an OverlayInfo/OverlayInfoNet instance for each overlay type
wanted before starting the export.
exportInfo[i].overlayInfo = new
PelcoAPI::OverlayInfo[overlayNum];
exportInfo[i].overlayInfo[0].type =
PelcoAPI::OVERLAY_TYPE_TIMESTAMP;
// configure other parameters for the 1st overlay
PelcoAPI.OverlayInfoNet overlayInfo_0 = new

PelcoAPI.OverlayInfoNet();
overlayinfo_0.type =
PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP;
// configure other parameters for the 1st overlay
OverlayData Parameters
OverlayData contains the following parameters. (Note that PPX export does not currently support
overlays.)
timestamp
The overlay displays a timestamp that provides the time in local time.
cameraname
The overlay displays a camera’s name. Typically the camera name displayed is the source
of the video stream.
textstring
The overlay displays text that the user specifies.
picture
The overlay displays a picture that the user specifies.
Now create a new instance of OverlayInfoNet and, based on the type of overlay you chose, simply start
assigning the desired values with it such the font to use, the color of the font, the location of the overlay,
and so on.
The following is a list of other overlay settings (some may or may not apply to certain overlay types as
noted):
location
The general screen location of the overlay. (Refer to the DataMixerPluginDefines
header for the latest definition of OverlayLocation.)
enum OverlayLocation
{
OVERLAY_LOCATION_UNKNOWN,
OVERLAY_LOCATION_TOP_LEFT,
OVERLAY_LOCATION_TOP_MIDDLE,
OVERLAY_LOCATION_TOP_RIGHT,
OVERLAY_LOCATION_CENTER,
OVERLAY_LOCATION_BOTTOM_LEFT,
OVERLAY_LOCATION_BOTTOM_MIDDLE,
OVERLAY_LOCATION_BOTTOM_RIGHT,
OVERLAY_LOCATION_COORDINATE
};
unknown
This denotes that the overlay will not appear on the screen.
76
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.)
dateFormat
This is only relevant to the timestamp overlay.
enum DateFormat
{
DATE_FORMAT_MDYYYY = 0,
DATE_FORMAT_MDYY = 1,
DATE_FORMAT_MMDDYY = 2,
DATE_FORMAT_MMDDYYYY = 3,
DATE_FORMAT_YYMMDD = 4,
DATE_FORMAT_YYYY_MM_DD = 5,
DATE_FORMAT_DD_MM_YY = 6,
DATE_FORMAT_DMYY = 7,
DATE_FORMAT_DDMMYY = 8,
77
DATE_FORMAT_DMYYYY = 9,
DATE_FORMAT_DDMMYYYY = 10,
DATE_FORMAT_YYMD = 11,
DATE_FORMAT_YYYYMD = 12,
DATE_FORMAT_YYYYMMDD = 13,
DATE_FORMAT_YYYY_M_D = 14,
};
mdyyy
This date format conforms to the following structure: m/d/yyyy (month/day/year), where
both 'm' and 'd' could be either one or two digits, for example, 12/8/2001 or 2/23/2001
mdyy
This date format conforms to the following structure: m/d/yy (month/day/year), where both
'm' and 'd' could be either one or two digits, for example, 12/8/01 or 2/23/01
mmddyy
This date format conforms to the following structure: mm/dd/yy. (month/day/year), for
example, 02/23/01
mmddyyyy
This date format conforms to the following structure: mm/dd/yyyy (month/day/year), for
example, 02/23/2001
yymmdd
This date format conforms to the following structure: yy/mm/dd (year/month/day), for
example, 01/02/23
yyyy_mm_dd
This date format conforms to the following structure: yyyy_mm_dd (year_month_day), for
example, 2001-02-23
dd_mm_yy
This date format conforms to the following structure: dd_mm_yy (day_month_year), for
example, 02-23-01
dmyy
This date format conforms to the following structure: d/m/yy (day/month/year), where both
ddmmyy
This date format conforms to the following structure: dd/mm/yy (day/month/year), for
example, 08/12/01 or 23/02/01
dmyyyy
This date format conforms to the following structure: d/m/yyyy (day/month/year), where
ddmmyyyy
This date format conforms to the following structure: dd/mm/yyyy (day/month/year), for
example, 21/03/2001
yymd
This date format conforms to the following structure: yy/m/d (year/month/day), where both
yyyymd
This date format conforms to the following structure: yyyy/m/d (year/month/day), where
yyyymmdd
78
This date format conforms to the following structure: yyyy/mm/dd (year/month/day), for
example, 2001/02/23
yyyy_m_d
This date format conforms to the following structure: yyyy_m_d (year_month_day), where
both 'm' and 'd' could be either one or two digits, for example, 1954-1-31 or 1973-12-1
timeFormat
This is only relevant to the timestamp overlay.
enum TimeFormat
{
TIME_FORMAT_HHMMSSTT = 10,
TIME_FORMAT_HMMSSTT = 11,
TIME_FORMAT_HMMSS = 12,
TIME_FORMAT_HHMMSS = 13,
TIME_FORMAT_HMSTT = 14,
TIME_FORMAT_TTHMS = 15,
TIME_FORMAT_TTHHMMSS = 16,
TIME_FORMAT_HMS = 17,
};
hhmmsstt
This time format conforms to the following 12 hour structure: hh:mm:ss tt
(hours:minutes:seconds AM/PM), for example, 06:07:12 AM or 12:07:12 PM
hmmsstt
This time format conforms to the following 12 hour structure: h:mm:ss tt
(hours:minutes:seconds AM/PM), where 'h' could be either one or two digits, for example,
6:07:12 AM or 12:07:12 PM
hmmss
This time format conforms to the following 24 hour structure: h:mm:ss
(hours:minutes:seconds), where 'h' could be either one or two digits, for example, 6:07:12
or 18:07:12
hhmmss
This time format conforms to the following 24 hour structure: hh:mm:ss
(hours:minutes:seconds), for example, 06:07:12 or 18:07:12
hmstt
This time format conforms to the following 12 hour structure: h:m:s tt
(hours:minutes:seconds), where 'h', 'm', or 's' could be either one or two digits, for example,
6:7:12 AM, 12:17:12 PM, or 12:3:2 PM
tthms
This time format conforms to the following 12 hour structure: tt h:m:s (AM/PM
hours:minutes:seconds), where 'h', 'm', or 's' could be either one or two digits, for example,
AM 6:7:12, PM 12:17:12, or PM 12:3:2
tthhmmss
This time format conforms to the following 12 hour structure: tt hh:mm:ss (AM/PM
hours:minutes:seconds), for example, AM 06:07:12, PM 12:17:12, or PM 12:03:02
hms
This time format conforms to the following 24 hour structure: H:m:s
(hours:minutes:seconds), where 'h', 'm', or 's' could be either one or two digits, for example,
6:7:12, 12:17:12, or 12:3:2
79
Resetting Overlay Data

To reset overlay data to default values for the video being exported, call the ResetData method.
C++ Example:
bool bSuccess = exporter.ResetData();
C# Example:
Boolean bSuccess = pEnduraExporterNet.ResetData();
Exporting Video
This section describes various video export methods and scenarios.
Exporting a Single Video Clip

1. Determine the System Manager’s IP address.
Refer to Automatically Determining the System Manager’s IP Address and Port Number in the Device
and Service Discovery section for details.
2. Initialize the Exporter.
Refer to Initializing the Exporter for details.
3. Optional: If you would like to overlay data onto the resulting export, do so now.
Refer to Setting Up Overlay Data on Video to Be Exported
4. Begin the video export by calling the Exporter’s StartExport method, passing in the following
parameters:
The full path, including file name, of the resulting exported video.
The format changes based on the operating system, for example, Windows or Linux.
The UUID of the camera from which to export video
The desired resulting video format for the export

Refer to the EnduraExporterDefines header for the latest options.
enum VideoCodecType
{
CODEC_ID_NONE = 0,
/* video codecs */
CODEC_ID_MPEG1 = 1,
CODEC_ID_MPEG2 = 2,
CODEC_ID_MJPEG = 8,
CODEC_ID_MPEG4 = 13,
CODEC_ID_H264 = 28
};
The starting time of the recorded video to export in UTC (GMT), not local time, using the
format yyyy-mm-ddThh:mm:ss
The ending time of the recorded video to export in UTC (GMT), not local time, using the
format yyyy-mm-ddThh:mm:ss
The videoOnly parameter
80
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, it will be available in either PEF or AVI format.
The UUID of the stream to export’s audio source, if separate from the video source of the
export
C++ Example:
bool bSuccess = exporter.StartExport("D:\\Video\\test123.avi",

"uuid:691fd745-006c-4fc9-9262-23c13e977ce4",
PelcoAPI::CODEC_ID_MPEG4,
"2010-01-11T22:10:35", "2010-01-11T22:11:15", false,
"uuid:691fd745-006c-4fc9-9822-23c13e977ce4");
C# Example:
Boolean bSuccess =
exporter.StartExport("D:\\Video\\test123.avi",
"uuid:691fd745-006c-4fc9-9262-23c13e977ce4",
PelcoAPI::CODEC_ID_MPEG4,
"2010-01-11T22:10:35", "2010-01-11T22:11:15", false,
"uuid:691fd745-006c-4fc9-9822-23c13e977ce4");
5. Poll the status of the video export repeatedly, for example, once per second, until it is finished. For more
information, see Polling a Video Export.
Exporting Video Using a Playlist (PPX)

The playlist (PPX) format supports advanced playback features, including synchronized and sequential
(stitched) playback.
For the following play-list example consider the following scenario; we have a system with nine cameras,
named “camera_x”, where “x” is the spelling of a number from zero to eight. We want to play the files
in the following way; camera_zero from 9:05-9:10, followed by camera_one and camera_three played
together in a 2x1 layout both from 9:11 to 9:15. Assume that the video from camera_one for 9:13 has been
deleted. Following this we want to play camera_four from 9:20 to 9:30, then we want to play camera_two,
camera_six, and camera_seven from 9:30 to 9:45, assume that camera_two’s video for 9:31-9:33 has
been deleted, and that its video from 9:42 to 9:44 has been deleted. Finally, we want to view camera_eight
from 9:42 to 10:00. The following diagram illustrates the view flow.

81
3. Call the PlaylistExportInfo method to set up the clip groups that will be played sequentially in the
order provided.
PlaylistExportInfo contains the following parameters:
DeviceID
The UUID of the camera from which to export video
AudioDeviceID
The UUID of the stream to export’s audio source, if separate from the video source of the
export.
StartTime
The start time in UTC (GMT), not local time, using the format yyyy-mm-ddthh:mm:ss
EndTime
The end time in UTC (GMT), not local time, using the format yyyy-mm-ddThh:mm:ss
VideoOnly
A boolean indicating if the clip should be exported with video only. If false, audio will also
be included.
ClipGroup
An integer representing the sequential order to play video clips. Up to 4 clips can be in the
same clip group which will play in sync within the export player.
C++ Example:
PelcoAPI::PlaylistExportInfo playlistExportInfo[ NUM_CLIPS ];

playlistExportInfo[0].sDeviceID = CAMERA_1;
playlistExportInfo[0].sStartTime = START_TIME_1;
playlistExportInfo[0].sEndTime = END_TIME_1;
playlistExportInfo[0].bVideoOnly = false;
playlistExportInfo[0].nClipGroup = 1;
C# Example:
ArrayList playlistExportInfo = new ArrayList( num_clips );

playlistExportInfo.Add( new PelcoAPI.PlaylistExportInfoNet( CAMERA_1,
"", START_TIME_1, END_TIME_1, false, 1 ) );
parameters:
exportFolder
The path of the folder for exports. (The format changes based on operating system.)
playlistName
The name of the playlist. This should be a simple name with no extensions
playlistExportInfo
An array of playlist information for export.
exportInfoCount
The number of export info entries
C++ Example:
bool bSuccess = exporter.StartExport("D:\\Video\\test123",

“PlaylistName”, PlaylistExportInfo, exportInfoCount);
82
C# Example:
Boolean bSuccess = pEnduraExporterNet.StartExport("D:\\Video\\test123",

“PlaylistName”, PlaylistExportInfo, exportInfoCount);
5. Poll the status of the video export repeatedly, for example, once per second, until it is finished.
For more information, see Polling a Video Export.
Stitching Multiple Clips into a Single Video Export

NOTE: This stitching procedure is DEPRECATED. Stitched video clips do not play correctly with
Pelco Export Player. Please use Exporting Video Using a Playlist (PPX).
NOTE: Enabling sequential stitching may or may not be much slower than exporting a single video
clip, depending on whether any of the clips need to be transcoded.
There are occasions where you will need to export a single video from multiple video clips.
• First initialize as many video clip export settings (ExportInfo) instances as you will need. For details
on how to set up one set of video clip export settings, refer toSetting Up Overlay Data on Video to Be
Exported .
• At this point determine if you want to associate any overlays to the video clips. If so, create and
initialize any overlays to associate with the video clip to export. In the example excerpt below, we have
associated four previously created OverlayInfo instances with two ExportInfo instances.
3. Optional: If you would like to overlay data onto the resulting export, do so now.
Refer to Setting Up Overlay Data on Video to Be Exported for details.
parameters:
The full path, including file name, of the resulting exported video.
The format changes based on operating system, for example, Linux or Windows.
The desired resulting video format for the export.
Refer to the EnduraExporterDefines header for the latest options.
enum VideoCodecType
{
CODEC_ID_NONE = 0,
/* video codecs */
CODEC_ID_MPEG1 = 1,
CODEC_ID_MPEG2 = 2,
CODEC_ID_MJPEG = 8,
CODEC_ID_MPEG4 = 13,
CODEC_ID_H264 = 28
};
An array of the ExportInfo instances, containing instances of OverlayInfo.
The number of ExportInfo instances, one for each clip to stitch.
Below is a stitched video export example:
83
C++ Example:
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";
exportInfo[0].sStartTime = "2009-08-16T05:08:00";
exportInfo[0].sEndTime = "2009-08-16T05:09:00";
exportInfo[0].bVideoOnly = false;
exportInfo[0].overlayNum = overlayNum;
exportInfo[1].sDeviceID =
"uuid:691fd745-006c-4fc9-9262-23c13e977ce4";
// configure other export settings for the 2nd clip to export
if (overlayNum > 0)
{
for (i = 0; i < clipNum; i++)
{
exportInfo[i].overlayInfo = new
PelcoAPI::OverlayInfo[overlayNum];
PelcoAPI::OVERLAY_TYPE_TIMESTAMP;
// configure other settings for the 1st overlay
PelcoAPI::OVERLAY_TYPE_CAMERANAME;
// configure other settings for the 2nd overlay
PelcoAPI::OVERLAY_TYPE_PICTURE;
// configure other settings for the 3rd overlay
PelcoAPI::OVERLAY_TYPE_TEXTSTRING;
// configure other settings for the 4th overlay
}
}
bool bSuccess = exporter.StartExport("D:\\Video\\test123.mp4",

PelcoAPI::CODEC_ID_MPEG4, exportInfo, 2);
C# Example:
PelcoAPI.ExportInfoNet exportInfo_0 = new

PelcoAPI.ExportInfoNet();
exportInfo_0.sDeviceID =
"uuid:00047D01-4CA5-5370-6563-747261495605";
exportInfo_0.sStartTime = "2009-08-16T05:08:00";
exportInfo_0.sEndTime = "2009-08-16T05:09:00";
exportInfo_0.bVideoOnly = true;
PelcoAPI.ExportInfoNet exportInfo_1 = new

PelcoAPI.ExportInfoNet();
// initialize another export video clip setting
exportInfo_0.overlayInfo = new ArrayList();

exportInfo_0.overlayInfo.Add(overlayInfo_0);
// add any other overlay settings here
exportInfo_1.overlayInfo = new ArrayList();
exportInfo_1.overlayInfo.Add(overlayInfo_0);
84
// add any other overlay settings here

ArrayList exportInfo = new ArrayList(2);
exportInfo.Add(exportInfo_0);
exportInfo.Add(exportInfo_1);
Boolean bSuccess = pEnduraExporterNet.StartExport("C:\\test456.avi",

PelcoAPI.VideoCodecTypeNet.CODEC_ID_MPEG4, exportInfo, 2);
5. Poll the status of the video export repeatedly, for example, once per second, until it is finished.
For more information, see Polling a Video Export.
Polling a Video Export

To poll the status of the video export until it is finished, perform the following:
C++ Example:
for( int clipCounter = 0; clipCounter < NUM_CLIPS; ++clipCounter

)
{
int status = 0;
while( status < 100 && status != -1 )
{
int temp = exporter.PollStatus();
if (temp != status)
{
status = temp;
TRACE_INFO("Polling status %d\n", status);
}
}
}
C# Example:
Int32 clipCounter = 0;
while (clipCounter < num_clips)
{
Int32 status = 0;
Int32 temp = 0;
while (status < 100 && status != -1)
{
temp = pEnduraExporterNet.PollStatus(60);
if (temp != status)
{
status = temp;
Console.WriteLine("Polling status - {0}\n", status);
}
}
++clipCounter;
}
Stopping a Video Export

When you want to force a video export that is currently in progress to stop, just call the StopExport
method.
C++ Example:
bool bSuccess = exporter.StopExport();
85
C# Example:
Boolean bSuccess = exporter.StopExport();
Exporting A JPEG Snapshot

To create a JPEG snapshot, call the ExportSnapshot method, passing in a .jpeg or .jpg file name,
camera uuid, and timestring (use "NOW" for a live snapshot).
The following is an example of a live snapshot.
C++ Example:
bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg",

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

"uuid:00047D01-8994-5370-6563-747261495605", "NOW");
The following is an example of a recorded snapshot.

C++ Example:
bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg",

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

"uuid:00047D01-8994-5370-6563-747261495605", "2011-11-07T19:30:00");
86
Chapter
8
Web Service Proxies
Web Service Proxies

Overview
PelcoGSoap is a static linked library generated by gSOAP tools, based on the WSDL files with minor
modifications. The PelcoGSoap library provides an interface for SOAP clients to make SOAP calls to
Pelco devices. It accounts for most issues regarding making SOAP calls to Pelco devices.
General Usage
NOTE: This entry assumes that users have already installed the Pelco SDK.
1. Include the stdsoap2 header and the web service proxy header. For example, if you want to utilize the
CameraConfiguration web service, you should include the CameraConfigurationProxy header.
#include "PelcoAPI/stdsoap2.h"
#include "PelcoAPI/CameraConfigurationProxy.h"
2. Declare your web service proxy. In this case, it will be CameraConfigurationProxy.
CameraConfigurationProxy CameraConfiguration;
3. Set the SOAP header.
pSoap->header = (struct SOAP_ENV__Header *)

soap_malloc(CameraConfiguration,
sizeof(struct SOAP_ENV__Header));
4. Set the web service’s control point URL. For details on the proper way to retrieve the control point URL,
refer to Retrieving a Specific Web Service’s Control URL.
CameraConfiguration.soap_endpoint = strEndPointURL.c_str();
5. Create a new web service action request instance.

This will hold your request parameters for the web service action ResetConfiguration.
87
Pelco SDK | Web Service Proxies
6. Create a new web service action response instance. In the below example, we create an instance of
CameraConfiguration’s ResetConfigurationResponse data type.
_CameraConfiguration__ResetConfigurationResponse *
pResetConfigurationResponse =
soap_new__CameraConfiguration__ResetConfigurationResponse(
&CameraConfiguration, -1);
This will hold the web service’s response including related values to your request.
7. Call the CameraConfiguration web service proxy ResetConfiguration action, passing in both
the 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)
88
Chapter
9
Discovery
Device and Service Discovery Overview

One of the most basic tasks is to programmatically determine what devices and services are available on
your network.
This section contains sample C# and C++ that illustrates how to discover devices and services. Complete
C# and C++ sample programs are contained in the following subdirectory where the Pelco SDK is installed:
Pelco\API\SampleCode\SystemManagerWrapperSample

The key to performing device and service discovery related tasks is the System Manager Wrapper. The
System Manager Wrapper is a component of the Pelco SDK. It provides users with convenience functions
for device and service queries.
The majority of the tasks covered in this section can be found in the the System Manager Wrapper C++
sample project. You should examine the sample project source code while reading this documentation.
NOTE: For more Endura specific information, refer to the Endura appendix.
89
Pelco SDK | Discovery
Getting Started
Projects.
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\Debug.
NOTE: If running in Release mode, change this path to C:\Program Files\Pelco\API\Libs
\Release.
Next Steps
The following set of tasks are essential for using the Pelco SDK:
• Determine the System Manager’s IP address and port number, either manually, or automatically through
the Pelco SDK as described in Automatically Determining the System Manager’s IP Address and Port
Number.
• Create a class that implements the IDeviceStorageNet interface.
• Query all available Pelco devices on your network.
Initializing the Pelco SDK System Manager Wrapper

or Program.cs’s Main function (for C#), which belongs to the System Manager Wrapper sample
project.
Before performing any of the tasks associated with the System Manager Wrapper, you must initialize an
instance of it. Then you can use the instance to log in to the System Manager, since most System Manager
Wrapper methods require a login ID.
1. Declare and initialize the System Manager Wrapper.
a) If you need to determine the System Manager’s IP address, refer to Automatically Determining the
System Manager’s IP Address and Port Number.
b) If you already know the System Manager’s IP address, enter it into the SetSMAddress method as
shown below.
C++ Example:
PelcoAPI::SystemManagerWrapper sm;
int nRet = sm.SetSMAddress((char *) sSMIPAddress);
C# Example:
PelcoAPI.SystemManagerWrapperNet sm = new
PelcoAPI.SystemManagerWrapperNet();
int nRet = sm.SetSMAddress("192.168.1.1");
2. Log in to the System Manager with the proper credentials. Call the System Manager Wrapper instance’s
UserLogin method, passing in the username and password.
C++ Example:
int loginId = sm.UserLogin("brian", "pelco");
C# Example:
Int32 loginId = sm.UserLogin("brian", "pelco");
90
If successful, this step should return an ID of your login session. Make a note of this login ID, because it
is used for many of the System Manager Wrapper’s methods.
3. After you have logged in to System Manager, you will eventually have to log out. When you have
finished all System Manager related operations, log out by calling the System Manager Wrapper
instance’s UserLogout method, passing in your login ID as the parameter.
For more details on authenticating to a Pelco system, refer to Logging In and Logging Out.
C++ Example:
sysMgr.UserLogout(loginId);
C# Example:
sm.UserLogout(loginId);
Automatically Determining the System Manager’s IP Address and Port

Number
project.
1. Initialize the System Manager Wrapper by calling its AutoDiscoverSM method to automatically
determine the System Manager's IP address and port number.
The 120 parameter represents the duration in seconds before a timeout.
int nRet = sm.AutoDiscoverSM(120);
2. To access the System Manager’s IP address and port number, call the GetSMAddress method.
C++ Example:
int rPort = 0;
// ... Auto discover SM ...
// Return the SM IP Address
PelcoAPI::xstring sIpAddress;
sm.GetSMAddress(&sIpAddress,&rPort);
TRACE_INFO("The SM IpAdress - %s and Port - %d\n", sIpAddress.data,
rPort);
PelcoAPI::xfree(&sIpAddress);
C# Example:
// ... Auto discover SM ...

String sSmIpAddress = "";
Int32 nPort = -1;
if( sm.GetSMAddress(ref sSmIpAddress, ref nPort ) )
Console.WriteLine("SM address -> {0}:{1}\n", sSmIpAddress, nPort);
else
Console.WriteLine( "Could not get SM address\n" );
Logging In and Logging Out

project.
91
In many cases, you might need to both log in and log out of System Manager.
1. To log in to the System Manager with the proper credentials, call the System Manager Wrapper
instance’s UserLogin method, passing in the username and password.
If successful, this step should return an ID of your login session.

NOTE: Make a note of this login ID, because it is used for many of the System Manager
Wrapper’s methods.
2. When you have finished all System Manager related operations, log out of the System Manager.
Call the System Manager Wrapper instance’s UserLogout method, passing in your login ID as the
parameter.
sysMgr.UserLogout(loginId);
Querying Available Devices from the System Manager

NOTE: The related source code for this entry can be found in main.cpp’s main function (for C+
+) or Program.cs’s Main function (for C#), which belongs to the System Manager Wrapper sample
project.
NOTE: Before proceeding with this entry, it is assumed that you have already completed the steps
outlined in Creating an IDeviceStorage Class.
The first major task that you need to complete is to query all Pelco devices available on your network.
Completing this enables you to access a device’s Unique Device Name (UDN) and many other device-
related attributes that are needed for other Pelco SDK related tasks.
1. Initialize the System Manager Wrapper. See Initializing the System Manager Wrapper for details.
2. Make a call to the System Manager Wrapper's GetDevices method, passing in the following
parameters:
• Your login ID: This ID is returned after a successful login. See Initializing the System Manager
Wrapper for details.
• The sequence number: This is used to filter results, only returning newly added or changed devices.
GetDevices calls return a new integer value once every few minutes during successive calls. New
values are 1 larger than the one before, for example, if the 1st call returned 1, then the subsequent
call will return a 2.
• The device type you would like to use to filter the results. Known device types include the following:
• Camera
• Encoder
• Decoder
• Monitor
• a NULL value (to not filter results by type of device)
NOTE: This is not a definitive list of Pelco device types. This list will expand as Pelco expands
its product line.
• A pointer to your IDeviceStorage implementation.
C++ Example:
int seqNum = 0;
MyStorage storage; // ... You must define this class ...
sm.GetDevices(loginId, &seqNum, "Camera", &storage);
92
C# Example:
int seqNum = 0;
DeviceInformation devStore = new DeviceInformation(); // You must define
this class
Boolean bSuccess = sm.GetDevices(loginId, seqNum, "Camera", devStore);
3. Perform the needed operations on the returned device data and store them into your
IDeviceStorage class instance. See Creating an IDeviceStorage Class for further details.
4. To query any changes with available devices from the System Manager, use the returned sequence
number value from your last call to the GetDevices method with your next call to the same method.
This call returns Pelco devices that have changed or are new to the network. Every subsequent call
returns only new changes within your network.
C++ Example:
int seqNum = 0;
MyStorage storage; // ... You must define this class ...
sm.GetDevices(loginId, &seqNum, "Camera", &storage); // ... seqNum changes
here to 1 ...
// ... Misc logic ...
sm.GetDevices(loginId, &seqNum, "Camera", &storage); // ... seqNum changes
here to 2 ...
C# Example:
int seqNum = 0;
DeviceInformation devStore = new DeviceInformation(); // You must define
this class
sm.GetDevices(loginId, ref seqNum, "Camera", &storage); // seqNum changes
here to 1 ...
// ... Misc logic ...
sm.GetDevices(loginId, ref seqNum, "Camera", &storage); // seqNum changes
here to 2 ...
Retrieving the System Manager’s Time Zone

project.
To determine your System Manager’s current time zone, do the following:
1. Initialize the System Manager Wrapper. (Refer to Initializing the System Manager Wrapper for details.)
2. Call the System Manager Wrapper’s GetSystemAttribute method, passing in the following
parameters:
Your login ID
This ID is returned after a successful login. (Refer to Initializing the System Manager
Wrapper for details.)
SYS_CFG_TzInfo
The time zone attribute’s ID.
&sTimezoneInfo
A pointer to your time zone variable.
93
C++ Example:
PelcoAPI::xstring sTimezoneInfo;
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo",
&sTimezoneInfo);
C# Example:

String sTimeZone = "";
Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo", ref
sTimeZone);
Retrieving the Network Time Server Address

project.
To your network’s network time server’s IP Address, do the following:
parameters:
Your login ID
SYS_CFG_NtpAddr
The network time server's attribute’s ID.
&sTimezoneInfo
A pointer to your NTP address variable.
C++ Example:
PelcoAPI::xstring sNtpAddress;
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr",
&sNtpAddress);
C# Example:

String sNtpAddress = "";
Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr",
ref sNtpAddress);
Retrieving a Web Service’s ID

project.
NOTE: This entry assumes that you have already completed the steps outlined in Querying
Available Devices from the System Manager, which provides you with UDNs for Pelco devices
available on your network.
94
To determine your web service's ID, do the following:

2. Call the System Manager Wrapper’s GetServiceID method, passing in the following parameters:
Your login ID
The target device’s Unique Device Name (UDN) value
sServiceType
The name of desired web service, such as VideoOutput.
sServiceId
The pointer to the variable that will hold the result.
C++ Example:
PelcoAPI::xstring sServiceId;
bool bSuccess = sm.GetServiceID(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605",
"VideoOutput", &sServiceId);
Retrieving a Specific Web Service’s Control URL

project.
Obtaining a web service’s control URL is essential for many Pelco-related operations.
2. Call the System Manager Wrapper’s GetDeviceServiceAttribute method, passing in the following
parameters:
Your login ID
The target web service’s ID
Refer to Retrieving a Web Service’s ID for details.
SYS_UpnpControlUrl
The control URL attribute’s ID.
sCtrlUrl
A pointer to the variable that will store the result of the web service control URL.
95
C++ Example:
PelcoAPI::xstring sCtrlUrl;
bool bSuccess = sm.GetDeviceServiceAttribute(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpControlUrl",
&sCtrlUrl);
C# Example:
String sCtrlUrl = “”;

Boolean bSuccess = sm.GetDeviceServiceAttribute(loginId,
ref sCtrlUrl);
Retrieving the NVR Associated with the Device

project.
To determine to which NVR or NSM your camera is connected to record, complete the following steps:
2. Call the System Manager Wrapper’s GetDeviceAttributeValue method, passing in the following
parameters:
Your login ID
SYS_NvrAssoc
The NVR association attribute’s ID.
sNvr
C++ Example:
PelcoAPI::xstring sNvr;
bool bSuccess = sm.GetDeviceAttributeValue(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc",&sNvr);
C# Example:
String sNvr = “”;

Boolean bSuccess = sm.GetDeviceAttributeValue(loginId,
96
"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc",
ref sNvr);
Retrieving the Device’s Friendly Name

project.
To determine a device’s friendly name, you can simply parse through the results of a GetDevices method
call, which includes both the device UDN and its accompanying attributes. Alternatively, you can complete
the following steps:
parameters:
Your login ID
SYS_UpnpFriendlyName
The attribute name.
sFriendlyName
C++ Example:
PelcoAPI::xstring sFriendlyName;
"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpFriendlyName", &sFriendlyName);
Retrieving the Device’s Device Description File (DDF) URL

project.
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:
parameters:
Your login ID
97

SYS_UpnpDevDescUrl
The attribute ID.
sDdfUrl
C++ Example:
PelcoAPI::xstring sFriendlyName;
"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpDevDescUrl", &sDdfUrl);
C# Example:
String sFriendlyName = “”;

"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpDevDescUrl", ref sDdfUrl);
Retrieving All Web Services Available on a Device

project.
To show all available web services on a particular Pelco device, complete the following steps:
2. Call the System Manager Wrapper’s GetServiceInfoSync method, passing in the following
parameters:
Your login ID
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 ever,
without a new firmware update. Therefore, this value should almost always be a 0.
storage
C++ Example:

bool bSuccess = sm. GetServiceInfoSync(loginId, 0,
98
"uuid:00047D01-4CA5-5370-6563-747261495605", &storage);
C++ Example:

Boolean bSuccess = sm. GetServiceInfoSync(loginId, 0,
"uuid:00047D01-4CA5-5370-6563-747261495605", storage);
Retrieving Device Attributes

project.
Device attributes are values that describe the device in some way such as its model number or its model
name. The following are the most common device attributes:
SYS_UpnpPelcoDeviceUdn
A Pelco device’s Unique Device Name (UDN); a special device identifier for networks.
SYS_UpnpFriendlyName
A more human readable version of the device’s name. A separate attribute,
friendlyName, may be present. Users can customize this attribute. When present,
friendlyName should be used in place of SYS_UpnpFriendlyName for display
purposes.
SYS_UpnpDeviceType
A URN that denotes the device’s category.
SYS_UpnpDevDescUrl
This shows the location of the device’s UPnP Device Descriptor File (DDF).
SYS_UpnpSerialNumber
The device’s serial number.
SYS_UpnpModelNumber
The device’s model number.
SYS_UpnpModelDescription
A more detailed description of the device.
SYS_UpnpManufacturerUrl
The device manufacturer’s website.
SYS_UpnpModelName
The device’s model name.
This outlines the steps needed to return a specific device attribute:
parameters:
Your login ID
99

The name of the device attribute to query.

C++ Example:
PelcoAPI::xstring sModelNumber;
"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpModelNumber", &sModelNumber);
C# Example:
String sModelNumber = "";

"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpModelNumber", ref sModelNumber);
Retrieving a System Manager’s Attribute

project.
A System Manager’s attributes are similar to a generic Pelco device’s attributes, except in most cases
a System Manager attribute is exclusive to Pelco System Managers. If you aren’t familiar with device
attributes, System Manager attributes are simply values that describe the System Manager in some way
such as its current time zone or its current security mode. The following are the more common System
Manager attributes:
SYS_CFG_NtpAddr
This value is used to indicate the location at which the NTP server (if any) can be located.
The expected value is an IP address.
SYS_CFG_SecMode
This value is used to identify the system's current security mode.
SYS_CFG_SmtpAddr
This value is used to indicate the location at which the SMTP server (if any) can be
located. The expected value is an IP address.
SYS_CFG_TzInfo
This value is used to report time zone information. This value is comma delimited (without
whitespace). The following describes each number in the order in which they appear in the
comma-delimited list (for example, 1205056800,60,480):
Change Time
This number is the absolute daylight savings time (in time_t time() seconds). If this value is
zero, there is no daylight savings time for the time zone and nothing will have to be done
to support daylight savings. If the value is non-zero, the time zone does support daylight
savings time. In this case, if the value is negative, the time value is being used to indicate
the time to turn off daylight savings time. If the value is positive, the value is being used to
indicate the time at which daylight savings time is to be turned on.
100
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 subtract
this number of minutes from the current GMT time.
SYS_CFG_UPNP_RENEWAL
The UPnP renewal value in seconds. The default setting is 1800 seconds (30 min).
SYS_CFG_UserLanguage
This value is used to indicate the default user language.
To determine a particular attribute value on your System Manager, do the following:
parameters:
Your login ID
systemAttribute
The name of the System Manager attribute. Parameter of type pointer to xstring, value
SYS_CFG_TzInfo.
A pointer to the variable that will hold the result.
C++ Example:
int iUpnpRenewal;
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL",
&iUpnpRenewal);
C# Example:
int iUpnpRenewal;
Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL",
ref iUpnpRenewal);
Retrieving a Web Service’s Attribute

project.
2. Call the System Manager Wrapper’s GetDeviceServiceAttribute method, passing in the following
parameters:
Your login ID
101
The target web service’s ID
Refer to Retrieving a Web Service’s ID for details.
The ID of the web service attribute
For example, SYS_UpnpControlUrl or SYS_UpnpEventSubUrl
A pointer to the variable that will store the result.

C++ Example:
PelcoAPI::xstring sCtrlUrl;
bool bSuccess = sm.GetDeviceServiceAttribute(loginId,
&sCtrlUrl);
C# Example:
String sCtrlUrl = "";

Boolean bSuccess = sm.GetDeviceServiceAttribute(loginId,
ref sCtrlUrl);
Creating an IDeviceStorage Class

NOTE: The related source code for this entry can be found in the MyStorage.h and
MyStorage.cpp files (for C++) or DeviceInformation.cs file (for C#), which belongs to the
System Manager Wrapper sample project.
What is the IDeviceStorageNet class? An IDeviceStorageNet is simply an interface that parses
XML responses from the System Manager and stores the resulting device data from the XML response
internally. Users need an implementation of this interface, if they wish to manage device data using the
System Manager Wrapper.
1. Ensure that the IDeviceStorageNet class implements the following methods:

• virtual bool AddDevice(const char* sUDN, const char* sAttributes): This
method adds 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.
• The device’s Unique Device Name (UDN)
• virtual bool UpdateDevice(const char* sUDN, const char* sAttributes)
102
The System Manager Wrapper will use these methods every time you call its GetDevices method,
which in turn will update your IDeviceStorage instance contents.
C++ Example:
#ifndef PELCO_API_IDEVICE_STORAGE_H
#define PELCO_API_IDEVICE_STORAGE_H
#include <string>
namespace PelcoAPI
{
class IDeviceStorage
{
public:
virtual ~IDeviceStorage(){};
virtual bool AddDevice(const char* sUDN, const char* sXmlAttributes)=0;
virtual bool DeleteDevice(const char* sUDN)=0;
virtual bool UpdateDevice(const char* sUDN, const char* sXmlAttributes)=0;

};
#endif
C# Example:
using System;
using System.Collections.Generic;
using System.Text;
namespace SystemManagerWrapperNet
{
class DeviceInformation : PelcoAPI.IDeviceStorageNet
{
public void AddDevice(string sUDN, string sAttributes)
{
// ... User implemented logic here ...
}
public void DeleteDevice(string sUDN)
{
// ... User implemented logic here ...
}
}
}
2. Note that the System Manager Wrapper sample project has an implementation of IDeviceStorage
called MyStorage.
MyStorage is a stub class. It does not implement anything that is essential for production usage, such
as parsing the System Manager’s XML response data (attributes). Nor does it associate the device
UDN/attribute XML pairs into any constructs. Those exercises are left to the user.
103
Pelco SDK | Logging
Appendix
A
Logging
Logging is specific to Endura, and is configurable.
1. To configure logging, run the LoggingSetup application in the C:\Program Files\Pelco\API
\Logging folder.
2. Select the items that you want to log, as well as the folder where the logs should be stored and the max
logfile size.
3. Click Set to save the settings.
NOTE: Logging should be run by an administrative account, because other users do not have
write permissions to C:\Program Files (x86) or subdirectories by default.
4. To view the current log, run the LoggingSetup application in the C:\Program Files\Pelco\API
\Logging folder. Click the View Log File button.
NOTE: The maximum log size is 50MB. Any settings over that value will be reset back to
the default 50MB restriction. Usually, logging should be off (no items checked) unless Pelco
technical support asks for logging information when tracing issues.
In the Logging dialog box, the following settings are available:
Error
Logs error messages. This is usually the most important item.
Memory
Logs memory allocation statistics. This should usually be left unchecked.
Info
104
Pelco SDK | Logging
The next level of severity below Error.

Verbose
Logs actions that occur often and should normally not be logged because they fill up the
logfile quickly.
105
Pelco SDK | Product Compatibility
Appendix
B
Product Compatibility
The following table shows the compatibility of the Pelco SDK with Pelco products.
Product Event Event Exporter Meta-data Pelco API PTZ SM

Arbiter Manager Parser Viewer Control Wrapper
Wrapper
DX Y Y N N Y Y Y
47/4800
HD Video
Recorders
(functionality
will only
work
with DX
version that
supports
Pelco API)
Digital N N N N N N N
Sentry
5
DVR5100 Y Y Y Y Y Y Y
6 6 6
Endura Y Y Y Y Y N Y
Express
6 6
IP110 Y Y N Y Y N Y
6 6
IP3701 Y Y N Y Y N Y
6 6
NET5301R Y Y N Y Y N Y
6 6
NET5402R- Y Y N Y Y N Y
HD
6 5 6
NET5301T Y Y N Y Y Y Y
6 5 6
NET5308T Y Y N Y Y Y Y
6 5 6
NET5301T- Y Y N Y Y Y Y
I
6 5 6
NET5400T- Y Y N Y Y Y Y
I
6 6 6
NSM5200 Y Y Y Y Y N Y
5
Active only if the attached IP camera is PTZ capable.
6
Active only if an active System Manager is available on the network. Endura Express contains a built-in
System Manager, and therefore no additional System Manager is required.
106
Pelco SDK | Product Compatibility
6 6
Sarix Y Y N Y Y N Y
6 6
Spectra HD Y Y N Y Y Y Y
720p
6 6
Spectra HD Y Y N Y Y Y Y
1080p
6 6
Spectra IV Y Y N Y Y Y Y
IP
6 6
Spectra Y Y N Y Y Y Y
Mini
6 6
Esprit IP Y Y N Y Y Y Y
SM5000 Y Y N Y N N Y
SM5200 Y Y N Y N N Y
107
Pelco SDK | Endura
Appendix
C
Endura
In 2005, Endura provided a distributed architecture that delivered both flexibility and performance. Endura
is a complete solution for high definition video encoding, recording, and display. It controls the origination,
transport, recording, and display of integrated, security-related audio and video.
From a technical standpoint, what defines an Endura system?
System Manager + Endura Devices = Endura System
System Manager (SM)

First and foremost, an Endura system must have a System Manager (SM). The SM is the heart of Endura.
It is responsible for the following:
• Managing devices such as cameras, decoders, and NVRs, including administering rights and privileges
• Storing device information, like status
• Administering users, which includes permissions management
• Logging errors and alarms
• Security key management
Endura Devices
Endura devices can be defined as IP cameras, encoders, decoders, NVRs, or even work stations. Each
Endura device, including the SM itself, has an Application Programming Interface (API). An API is simply a
specified way for software clients to programmatically communicate with Endura devices, allowing access
to their functionality. All Endura devices provide an API through a set of related web services. These web
services adhere to the SOAP standard. (For more details on SOAP, please refer to the following http://
en.wikipedia.org/wiki/SOAP.) It is beyond the scope of this documentation to fully describe all Endura web
services. For details, such as the SOAP web service API reference, please refer to the Pelco Developer
Network (PDN) at http://pdn.pelco.com.
One of the main purposes of a System Manager is to provide a central place to retrieve information on all
Endura devices. How does the System Manager collect all of this information?
108
Pelco SDK | Endura
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 Alarms

There are two major ways to subscribe to Endura web service events:
• Directly contacting the device on which the target web service resides
• Using the System Manager as an intermediary to perform actual eventing related work
On newer Endura network deployments, the first option is the default. Users can enable the System
Manager to act as an intermediary by enabling its EventArbiter web service (not to be confused with
the Event Arbiter Library). The EventArbiter web service is used for receiving GENA events from
devices within an Endura network. The Event Arbiter provides two ways for subscribing to events:
• Through control URLs
• By subscribing to events with event URIs provided
109
Pelco SDK | Endura
Figure 1: Subscribing to Events through Control URLs
Figure 2: Subscribing to Events with Event URIs Provided
The URI is provided by the user through the System Manager's EventArbiter service.
What is the advantage of using the System Manager as an intermediary for Endura events? The System
Manager can help manage all event related network traffic, ensuring that an Endura network never gets
overwhelmed by eventing network traffic.
110
Pelco SDK | Endura
Video Exports
Currently the Exporter library requires a System Manager to be present to function. How does it work?
The Exporter client sends its request for video clips to export with atimestamp range filter to the System
Manager; that is, it wants clips that fall within a starting date time and an ending date time. The System
Manager will then query all available NSMs for clips that meet both the starting timestamp and the ending
timestamp. Specifically, there may be instances where the API must ‘stitch’ the end result from more than
one NSM source of video clips to meet the filter.
Where Does the Pelco API SDK Fit Within Endura?

The Pelco API SDK is meant to make using Endura web services easier by providing convenience
methods and utilities. It protects the user from all of the potentially overwhelming and complicated details
of Endura SOAP web services. Of course users are still free to directly use Endura web services. However
Pelco has found that many of our customers enjoy the convenience and ease of use that the Pelco API
SDK provides.
111
Pelco SDK | General Event Messages
Appendix
D
General Event Messages
LoggableEvent
This defines the general structure of logged data for events. It does not have a set of enclosing tags. For
further details, refer to the event message descriptions below.
<element name="deviceUdn" type="xs:int"/>

<element name="deviceUrn" type="xs:string"/>
<element name="serviceUrn" type="xs:string"/>
<element name="logId" type="xs:int"/>
<element name="major" type="xs:int"/>
<element name="minor" type="xs:int"/>
<element name="type" type="xs:int"/>
<element name="reason" type="xs:int"/>
<element name="parameters" type="tns:LoggableEventParameters"/>
deviceUdn
The unique device name. For example: uuid:AK-2
deviceUrn
The device's resource name. For example: urn:schemas-pelco-
com:device:Pelco:1
serviceUrn
The service's resource name.
logId
The log item's unique identifier.
major
A major issue identifier.
minor
A minor issue identifier.
type
A event type identifier.
reason
An identifier that represents the cause of the event.
parameters
A LoggableEventParameters data type.
112
Pelco SDK | General Event Messages
LoggableEventParameters
This contains a list of LoggableEventParameter data types. For further details, refer to the event
message descriptions below.
<complexType name="LoggableEventParameters">
<sequence>
<element minOccurs="0" maxOccurs="unbounded" name="parameter"
type="tns:LoggableEventParameter"/>
</sequence>
</complexType>
parameter
A LoggableEventParameter data type.
LoggableEventParameter
This represents an event-related parameter. For further details, refer to the event message descriptions
below.
<complexType name="LoggableEventParameter">
<sequence>
<element name="paramId" type="xs:int"/>
<element name="name" type="xs:string"/>
<element name="value" type="xs:int"/>
<element name="type" type="xs:int"/>
</sequence>
</complexType>
paramId
The parameter's unique identifier.
name
The parameter's name.
value
The parameter's value.
type
The parameter's type identifier.
113
Pelco SDK | Hardware Diagnostics Event Messsages
Appendix
E
Hardware Diagnostics Event Messsages
ConfigurationButton (20180)
This event triggers if the front panel configuration button has failed.
PdDiagnostic
This is the data subscribers will receive when the event triggers.
<complexType name="ConfigurationButton">
<sequence>
<element name="objGuid" type="xs:string"
fixed="394af82c-2b05-4df8-b2a6-2caed9ad4fae"/>
<element name="objId" type="xs:int" fixed="20180"/>
<element name="current" type="xs:int"/>
<element name="previous" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 394af82c-2b05-4df8-
b2a6-2caed9ad4fae
objId
The event's unique database identifier. The value must be: 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, refer to current.
<pdDiagnostic>
<objGuid>394af82c-2b05-4df8-b2a6-2caed9ad4fae</objGuid>
<objId>20180</objId>
<current>1</current>
114
<previous>3</previous>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>4</type>
<reason>1</reason>
<parameters></parameters>
DriverFailure (20150)
A DriverFailure PdDiagnostic object is only sent when a device's driver fails, so a
LoggableEvent object is used to set the correct major, minor, type, and reason. This is typically used for
multi-channel encoder (MCE) devices.
PdDiagnostic
This is the data that subscribers receive when the event triggers.
<complexType name="DriverFailurePdDiagnostic">
<sequence>
fixed="94b6d2d3-c68e-4b13-974a-08f69f50cb67"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 94b6d2d3-
c68e-4b13-974a-08f69f50cb67
objId
name
The name of the device driver
<complexType name="DriverFailurePdDiagnostic">
<sequence>
</sequence>
</complexType>
115
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>5</type>
<reason>1</reason>
Fans (20020)
Any device with any fans having a changed state will have a LoggableEvent fired.
PdDiagnostic
<complexType name="FanPdDiagnostic">
<sequence>
fixed="31e41907-53be-4f57-8ae2-a56c12d98d0e"/>
<element name="states" type="tns:FanStates"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to:
31e41907-53be-4f57-8ae2-a56c12d98d0e
objId
states
A FanStates data type.
FanStates
This contains list of one or more FanState data types.
<complexType name="FanStates">
<sequence>
<element name="state" maxOccurs="unbounded" minOccurs="1"
type="tns:FanState"/>
</sequence>
</complexType>
state
A FanState data type.
116
FanState
This represents the current and previous condition of a fan.
<complexType name="FanState">
<sequence>
<element name="cur" type="xs:int"/>
<element name="prev" type="xs:int"/>
</sequence>
</complexType>
cur
The current state identifier. Possible values are the following:
1 for FAN_OK
The fan is operating normally.
2 for FAN_FAILED
The fan has failed.
3 for FAN_UNKNOWN
The state of the fan is currently unknown; this fan does not have an initial state registered.
NOTE: This will always be the final stream state.
prev
The previous state identifier. This has the same possible values as cur.
<pdDiagnostic>
<objGuid>31e41907-53be-4f57-8ae2-a56c12d98d0e</objGuid>
<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>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>5</type>
<reason>1</reason>
117
HardDrives (20060)
For each CPdDiagHarddrives object, you can 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.
PdDiagnostic
<complexType name="HardDrivesPdDiagnostic">
<sequence>
<element name="states" type="tns:HardDrivesStates"/>
</sequence>
</complexType>
objGuid
31e41907-53be-4f57-8ae2-a56c12d98d0e
objId
states
A HardDrivesStates data type.
HardDrivesStates
This contains a list of one or more HardDrivesState data types.
<complexType name="HardDrivesStates">
<sequence>
<element name="state" maxOccurs="unbounded" minOccurs="1"
type="tns:HardDrivesState"/>
</sequence>
</complexType>
state
A HardDrivesState data type.
HardDrivesState
This represents the current and previous condition of a hard drive.
<complexType name="HardDrivesState">
<sequence>
<element name="prev" type="xs:int"/>
</sequence>
</complexType>
cur
The current state identifier. Possible values are the following:
1 for HDS_READY
Indicates that the hard disk is currently in use.
118
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.
prev
The previous state identifier. This has the same possible values as cur.
<pdDiagnostic>
<objGuid>8dda89bd-3c2c-4a35-aad4-1256cb5e1d27</objGuid>
<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>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>9</type>
<reason>1</reason>
<parameters>
<param>
<paramId>6</paramId>
119
<name>HardDriveId</name>
<value>0</value>
<type>1</type>
</param>
</parameters>
ImproperShutdown (20070)
A ImproperShutdownPdDiagnostic object is sent when an improper shutdown occurs, so a LoggableEvent
object can be initialized with the appropriate major, minor, type, and reason data.
PdDiagnostic
<complexType name="ImproperShutdownPdDiagnostic">
<sequence>
fixed="a44945e0-fa54-4fb0-a614-2e71886c508f"/>
<element name="mode" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: a44945e0-
fa54-4fb0-a614-2e71886c508f
objId
mode
The mode of the shutdown.
<pdDiagnostic>
<objGuid>a44945e0-fa54-4fb0-a614-2e71886c508f</objGuid>
<mode>4</mode>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>4</type>
<reason>4</reason>
120
LinkSpeed (20200)
This event triggers when the link speed changes. We then set the correct major, minor, type, and reason
for LoggableEvent. The current LinkSpeed is sent as a parameter with the LoggableEvent object.
PdDiagnostic
<complexType name="LinkSpeedPdDiagnostic">
<sequence>
fixed="b9359885-711a-4d71-b908-4bdf8753dbe8"/>
<element name="min" type="xs:int"/>
</sequence>
</complexType>
objGuid
b9359885-711a-4d71-b908-4bdf8753dbe8
objId
The device's unique database identifier. The value must be: 20200
min
The minimum link speed. For example: 100
cur
The current state. For example: 10
<pdDiagnostic>
<objGuid>b9359885-711a-4d71-b908-4bdf8753dbe8</objGuid>
<min>100</min>
<cur>10</cur>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>6</type>
<reason>0</reason>
<parameters>
<param>
<name>CurrentLinkSpeed</name>
<value>10</value>
<type>1</type>
</param>
</parameters>
121
PowerSupply (20120)
A PowerSupplyPdDiagnostic object is sent when a power supply encounters a problem so that a
LoggableEvent object can be initialized with the appropriate major, minor, type, and reason data.
PdDiagnostic
<complexType name="PowerSupplyPdDiagnostic">
<sequence>
fixed="26f051aa-009b-4a5d-ab20-09b064a07a52"/>
<element name="inAlarm" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 26f051aa-009b-4a5d-
ab20-09b064a07a52
objId
The device's unique database identifier. The value must be: 20200
inAlarm
This represents whether or not a device is in a problem state. Possible values are:
0
The power supply is operating properly; not in an alarm state.
1
Problems with the power supply; in alarm state.
<pdDiagnostic>
<objGuid>26f051aa-009b-4a5d-ab20-09b064a07a52</objGuid>
<inAlarm></inAlarm>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>2</type>
<reason>0</reason>
UPS (20170)
This event triggers if a UPS either fails or runs out of power.
122
PdDiagnostic
<complexType name="UPSPdDiagnostic">
<sequence>
fixed="e746c2c8-0b97-402e-abc3-c784890c8d99"/>
<element name="pre" type="xs:int"/>
<element name="rem" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: e746c2c8-0b97-402e-
abc3-c784890c8d99
objId
cur
The current state identifier. For example: 4
pre
The previous state identifier. For example: 1
<pdDiagnostic>
<objGuid>e746c2c8-0b97-402e-abc3-c784890c8d99</objGuid>
<Cur>4</Cur>
<Pre>1</Pre>
<Rem>0</Rem>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>24</type>
<reason>0</reason>
<parameters>
<param>
<name>TimeRemaining</name>
<value>0</value>
<type>1</type>
</param>
</parameters>
123
Pelco SDK | Software Diagnostics Event Messsages
Appendix
F
Software Diagnostics Event Messsages
DataLoss 20040
When this is triggered by a data loss, set the correct major, minor, type, reason for the LoggableEvent.
PdDiagnostic
This is the data that subscribers will receive when the event triggers.
<complexType name="DataLossPdDiagnostic">
<sequence>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be set to: 94b6d2d3-
c68e-4b13-974a-08f69f50cb67
objId
<complexType name="DataLossPdDiagnostic">
<sequence>
</sequence>
</complexType>
LoggableEvent object
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>8</type>
<reason>0</reason>
124
InputStreams 20160
For each stream entry that has its state changed from previous state, we send out a loggable event with
appropriate major, minor, type and reason.
<complexType name="InputStreams">
<sequence>
<element name="states" type="tns:InputStreamsEntries"/>
</sequence>
</complexType>
objGuid
31e41907-53be-4f57-8ae2-a56c12d98d0e
objId
entries
An InputStreamsEntries data type.
<pdDiagnostic>
<context>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</context>
<entries>
<entry>
<id>uuid:a58172d6-a22e-45b1-a67a-9a84515c3fa0</id>
<mediaType>0</mediaType>
<hardwareId>1</hardwareId>
<channelId>1</channelId>
<stateCur>4</stateCur>
<statePrev>2</statePrev>
</entry>
</entries>
</pdDiagnostic>
InputStreamsEntries
A list of InputStreamsEntry data types.
<pdDiagnostic>
<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>
</entry>
</entries>
</pdDiagnostic>
entry
125
An InputStreamsEntry data type.
InputStreamsEntry
<complexType name="InputStreamsEntry">
<sequence>
<element name="id" type="xs:string"/>
<element name="mediaType" type="xs:int"/>
<element name="hardwareId" type="xs:string"/>
<element name="stateCur" type="xs:int"/>
<element name="statePrev" type="xs:int"/>
</sequence>
</complexType>
id
The entry's unique identifier, for example: 2
mediaType
A media type identifier, for example: 0
hardwareId
A hardware identifier, for example: hwidv1
stateCur
The current state identifier. Possible values are:
1 for ISS_RECORDING
Currently recieving a stream and it is being recorded.
2 for ISS_RECORD_ERROR
Currently receiving a stream, but it is unable to be recorded due to an error.
3 for ISS_RECEIVING
Currently recieving a stream.
4 for ISS_RECEIVE_ERROR
Unable to receive a stream.
5 for ISS_MISSING
Expecting a stream but there is no available stream. In analog inputs, this means the
device is unable to detect a connection.
6 for ISS_UNKNOWN
The state of the stream is currently unknown; this stream does not have an initial state
registered.
statePrev
The previous state identifier. Refer to stateCur for possible valid values.
PacketLoss 20080
This event is fired when there is data loss during video data writing. Sets the appropriate major, minor,
type, and reason in Loggable Event.
126
PdDiagnostic
<complexType name="PacketLossPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string" fixed="ddfa09d6-64f1-4b39-a7e7-
de0c5f7780cc"/>
<element name="max" type="xs:float"/>
<element name="cur" type="xs:float"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: ddfa09d6-64f1-4b39-
a7e7-de0c5f7780cc
objId
max
The maximum acceptable packet loss percentage, for example: 1.1235
cur
The current packet loss percentage, for example: 5.1235
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>11</type>
<reason>0</reason>
<parameters>
<param>
<name>PercentageOfCurrentPacketLoss</name>
<value>5.1235</value>
<type>0</type>
</param>
</parameters>
SEBs 20210
For each PdDiagSebs object, loggable events are sent only when the state of a particular SEB changes.
Set the state of the SEB to the appropriate major, minor, type, and reason.
PdDiagnostic
<complexType name="SEBsPdDiagnostic">
<sequence>
127

<element name="entries" type="tns:SEBSEntries"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be:
31e41907-53be-4f57-8ae2-a56c12d98d0e
objId
entries
An SEBsEntries data type.
SEBsEntries
A list of SEBsEntry data types.
<complexType name="SEBsEntries">
<sequence>
<element name="entry" maxOccurs="unbounded" minOccurs="1"
type="tns:SEBsEntry"/>
</sequence>
</complexType>
entry
An SEBsEntry data type.
SEBsEntry
<complexType name="SEBsEntry">
<sequence>
<element name="stateCur" type="xs:int"/>
<element name="statePrev" type="xs:int"/>
</sequence>
<attribute name="id" type="xs:string" fixed="US"/>
</complexType>
stateCur
The current state identifier.
statePrev
The previous state identifier. Refer to stateCur for valid possible values.
id
(Attribute) The entry's identifier - string.
<pdDiagnostic>
<objGuid>2e9f0d2e-adf3-453b-aabc-a0223a604040</objGuid>
<entries>
<entry id="hello0">
</entry>
<entry id="hello1">
128
</entry>
<entry id="hello2">
</entry>
<entry id="hello5"></entry>
</entries>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>9</type>
<reason>2</reason>
<parameters>
<param>
<name>SEBId</name>
<value>hello4</value>
<type>0</type>
</param>
</parameters>
StorageFull 20190
When this event triggers from a device with fully used storage, the appropriate major, minor, type, and
reason is set in the Loggable event.
PdDiagnostic
This is the data that subscribers receive when the event triggers.
<complexType name="StorageFullPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string" fixed="94b6d2d3-
c68e-4b13-974a-08f69f50cb67"/>
<element name="inAlarm" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 94b6d2d3-
c68e-4b13-974a-08f69f50cb67
objId
inAlarm
This represents whether or not a device is in a problem state. Possible values are:
0for storage is not full
129
Not in an alarm state.

1 for full storage
In an alarm state.
<pdDiagnostic>
<objGuid>3df223ee-8041-4c1a-be77-2d140e5588aa</objGuid>
<inAlarm></inAlarm>
</pdDiagnostic>
For more details, refer to DataLoss 20040 LoggableEvent above.
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>13</type>
<reason>0</reason>
StorageTime 20130
This event is fired if the NVR/DVR is unable to achieve the user-configured video storage time.
PdDiagnostic
<complexType name="StorageTimePdDiagnostic">
<sequence>
fixed="e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: e08fa1d1-9b30-4e62-
bc8b-16cca0f57cb0
objId
min
The minimum number of hours of storage time allowed.
cur
The current number of hours of storage time available.
<pdDiagnostic>
<objGuid>e08fa1d1-9b30-4e62-bc8b-16cca0f57cb0</objGuid>
<min>5</min>
130
<cur>4</cur>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>12</type>
<reason>0</reason>
<parameters>
<param>
<name>CurrentStorageTime</name>
<value>4</value>
<type>1</type>
</param>
</parameters>
Temperature 20140
A Temperature PdDiagnostic object is triggered when temperature goes beyond specific range. The
current range is set between 10°C - 50° Celsius. This verifies if the current temperature is below minimum
or above maximum threshold, and then determines whether to send Loggable Events, with reason set
to either LOW or HIGH accordingly.
PdDiagnostic
<complexType name="TemperaturePdDiagnostic">
<sequence>
fixed="26f051aa-009b-4a5d-ab20-09b064a07a52"/>
<element name="max" type="xs:int"/>
</sequence>
</complexType>
objGuid
The event's Universally Unique Identifier. The value must be: 26f051aa-009b-4a5d-
ab20-09b064a07a52
objId
min
The minimum allowable temperature.
max
The maximum allowable temperature.
131
cur
The current temperature.
<pdDiagnostic>
<objGuid>7448f68a-de77-4ea9-b000-65b63bf54bd5</objGuid>
<min>10</min>
<max>20</max>
<cur>5</cur>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>3</type>
<reason>0</reason>
<parameters>
<param>
<name>CurrentTemperature</name>
<value>5</value>
<type>1</type>
</param>
</parameters>
132
Appendix
G
Glossary
ActiveX
Active X is an integration platform that provides developers, users, and Web producers a fast and easy
way to create integrated programs and content for Microsoft based Internet and Intranet software. For
more information, refer to http://support.microsoft.com/kb/154544
Advertisement (UPnP)
In a UPnP network, advertisement is the act of one device presenting its services for another device to
use. In Endura, the UPnP advertisement startup and renew intervals are set from the System Configuration
tab of the Setup window.
Alarm
In video security: An alarm occurs when a camera detects motion or there is a change in a physical alarm
input, such as a door opening or closing.
In card access: This is a condition caused by a system event or action to raise awareness to security staff.
Alarm relay
The alarm relay is the relay used to output an alarm condition based on a specific system or event
message criteria.
Auto-focus
Auto-focus is the ability of the lens to remain in focus during zoom-in, zoom-out, and motion functions.
bit
Abbreviation for binary digit; the smallest unit of information a computer can use. A bit is either a 1 or a 0 (a
high or low voltage state).
bit rate
Bit rate is the number of bits that are transferred between devices in a specified amount of time, typically
one second.
133
Pelco SDK | Glossary
Brightness
In NTSC and PAL video signals, the brightness information at any particular instant in a picture is conveyed
by the corresponding instantaneous DC level of active video. Brightness control should be adjusted so that
the black picture content displays as true black on your monitor.
bps
Bits per second. This is a bit rate measurement.
Bps
Bytes per second. Also abbreviated as B/s.
Broadcast
In an IP network environment, broadcast refers to sending information from one device to every device
on the network. When broadcasting, it is not possible to control or specify which devices can receive this
information.
byte
A byte is a string of bits processed as a unit by a digital computer. A byte is equal to eight bits (256
possibilities) and is large enough to hold one character (like an “A”) or an unsigned integer from 0 to 255.
Camera group
In an Endura system, a camera group is a collection of cameras associated with each other as part of the
setup process. Camera groups may be used in filtering cameras displayed in the Nav window, as well as
those selected for schedules, scripts, or permissions.
Coaxitron
Coaxitron is the Pelco protocol that uses “up the coax” technology. Commands to control pan/tilt devices
are transmitted during the vertical blanking interval of the video signal. Instead of separate wiring for
control commands and video, Coaxitron uses the coaxial cable for both video and control.
Standard: This older technology uses 15 bits to send a command.
Extended: This newer technology uses 32 bits to send a command.
codec
Codec is an acronym for compression/decompression. This term is commonly used in the context of
multimedia compression and decompression, such as video or audio.
Common Intermediate Format (CIF)

A standard video and digital image size. Also refer to SIF.
134
CIF: 352 x 288 for PAL

2CIF: 704 x 288 for PAL
4CIF: 704 x 480 for PAL
QCIF: 176 x 144 for PAL
Compression
Compression is any algorithm used to reduce the size of a file.
Contrast
Contrast is a common term used in reference to the difference between the darkest and the brightest parts
of an image. Once brightness is set correctly, contrast should be set for comfortable viewing brightness.
D1
D1 is a digital video format developed by Society of Motion Picture and Television Engineers (SMPTE).
The D1 format resolution is 720 × 480 for NTSC and 720 × 576 for PAL.
Decoder
In an Endura system, the decoder is a high-performance video device that converts digital video streams
back into analog output for viewing on an analog video monitor, S-video monitor, or VGA monitor.
Decoding
Decoding is the opposite of encoding: decompressing a compressed digital image and then turning it back
into an analog signal.
Device
A device is a piece of hardware (camera, alarm, DVR, NVR, storage expansion box) that is part of a
network.
Device ID
A device ID is a unique identifier for an individual device on a network.
Encoder
In an Endura system, the encoder is a high-performance MPEG-4 device that takes analog video signals
through a standard BNC coax and digitizes, compresses, signs, and packetizes them for the network. It
also provides an interface for relays, alarms, and audio connections.
135
Encoding
Encoding is the process of taking an analog signal and converting it to a digital format (A to D conversion).
Compression is applied at this point in the process.
Firmware
Firmware is a process or program that is embedded in a hardware platform that instructs the hardware unit
how to behave and what action to perform.
Focus
Focus means to adjust a lens to allow objects at various distances from the camera to be sharply defined.
Frame rate
The frame rate is the number of frames or images that are captured, stored, projected, or displayed per
second.
Gamma
Gamma is the correction of the linear response of a camera to compensate for the nonlinear response
of a monitor’s phosphor screen. It is measured with the exponential value of the curve describing the
nonlinearity. A typical monochrome monitor gamma is 2.2, and a camera needs to be set to the inverse
value of 2.2 (which is 0.45) for the overall system to respond linearly (that is, unity).
H.264
Developed by the ITU-T Video Coding Experts Group (VCEG), H.264 is a low-bit-rate compressed video
format standard.
Hue
Hue is one of the characteristics that distinguishes one color from another. Hue defines color on the
basis of its position in the spectrum, that is, whether red, blue, green or yellow, etc. Hue is one of the
three characteristics of television color; the other two are saturation and luminance. In NTSC and PAL
video signals, the hue information at any particular point in the picture is conveyed by the corresponding
instantaneous phase of the active video subcarrier.
I-frame
In a compressed digital image, I-frames (intraframes) are the frames that are compressed independently of
the other frames in the sequence.
IP
Internet Protocol. IP is the main method of transmitting data across the Internet.
136
IP address
(static and DHCP) The IP address identifies a particular computer on a network to other computers. An
IP address is similar to your home address. In a neighborhood, each house has a unique address; on a
network each computer must have a unique address. An IP address is a four-byte number, usually written
in dotted-decimal notation with periods separating the bytes (for example, 192.168.0.100). There are two
types of IP addresses: static and DCHP. A static address is assigned when someone physically connects
to a computer and defines the IP address for that computer. A static address does not change unless
someone physically changes it. A DHCP (Dynamic Host Configuration Protocol) address is assigned
dynamically from a server that contains a pool of addresses. The server leases the computer one of the
available addresses for a specified amount of time. Once the time has expired, the computer renews the
lease or requests a new IP address.
IP camera
An IP camera is a digital video camera that outputs IP packets over Ethernet cabling. An IP camera may
use TCP protocol, as well as UDP or RTP.
IP header
An IP packet can be divided into two main parts: the payload and the header. The header is the part of the
packet that contains the routing information, and is is comprised of many parts. The header contains all IP
and MAC addressing information. The header is the only part of the packet that a router examines when
trying to determine where to send a packet.
Iris
The iris is a means of controlling the size of a lens aperture and therefore the amount of light passing
through the lens.
marshalling
Marshalling is synonymous with serialization.
MPEG-4
Developed by Moving Picture Experts Group (MPEG), MPEG-4 expands the MPEG-1 specification to
support AV ‘objects’, 3D content, low bit-rate encoding, and Digital Right Management (DRM).
Multicast
A single device sends information across a network and that stream is received by all listening devices on
the network. A special IP address range has been reserved for this purpose: 224.0.0.1-239.255.255.255
with a sub-net mask of 255.255.0.0. Each multicast transmitting device sends a data stream to an address
from the above range. Any device on the network can then listen for transmissions to that IP address and
receive the stream. Multicast offers a reduction of bandwidth consumption over the unicast and broadcast
delivery methods. Multicast also offers control over which devices on a network can receive a multicast
stream. In an Endura system, only Endura devices can receive Endura multicast streams. Multicast traffic
is not routable across the Internet without a specially reserved address or encapsulation.
137
Multicast server
A multicast server is any server that takes a unicast transmission on behalf of a client and converts it to a
multicast transmission on the network.
Namespace
Namespace is an identifier that denotes a group of names. It is used to prevent resource identifier conflicts.
Network Time Protocol (NTP)

NTP is a protocol designed to synchronize the clocks of computers over a network. On systems that
have an NTP server, you may use the WS5050 to configure the NTP settings (NTP server IP and renew
interval). By default, time and date information is included with video streams and other device data. The
software relies on the PC system clock for other needed time information.
National Television System Committee (NTSC)

NTSC developed the U.S. color TV specifications. It specifies 525 lines/screen. It also specifies 59.94
fields per second, although most people refer to this frame rate as 30 frames per second. NTSC now
describes the American system of color telecasting. It is used in North America, Japan, and some parts of
South America.
Network Storage Manager (NSM)

A combination of high performance, scalable hardware and advanced software for managing pooled
storage of recorded video and audio streams.
Phase Alternation by Line (PAL)

PAL is the European (50 Hz) color TV standard. It is used by most foreign countries around the world. It
specifies 625 lines/screen, and 25 frames per second.
Parity
Parity is a method of checking the accuracy of data to identify whether the bits being moved arrived
successfully. Parity bit checking can be based on odd or even bits. No parity means that a parity bit is not
transmitted or checked.
P-frame
In a compressed digital image, a P-frame (predicted frame) is a frame calculated based on the change
from one frame to the next. An area of the display that does not change from one frame to the next does
not need to be contained in the P-frame. If an area of the display does not change but does move on the
screen, then only the vector describing this movement is contained in the P-frame. This allows a reduction
in overall file size.
138
PIN
Personal Identification Number. PIN is used to provide security in a system.
Power over Ethernet (PoE)

PoE enables both power and video to transmit on a single cable.
Protocol
Protocol is a set of rules governing the transmission of data between equipment:
D Pelco protocol that uses 7 bytes to send a command.
M Pelco protocol for communicating with M devices (KBD960/KBR960 keyboards, ALM2064 alarm
interface units, and REL2064 relay interface units).
P Pelco protocol that uses a variable number of bytes to send a command. Eight bytes are used to send
commands to dome systems.
Relay group
A relay group is a defined set of relays acting in a coordinated pattern.
Remote Procedure Calls (RPCs)

RPC is a protocol that allows a computer program running on one host to cause code to be executed on
another host.
Real-time Transport Protocol (RTP)

A protocol that uses a standardized packet format for delivering data over networks.
Real Time Streaming Protocol (RTSP)

A protocol for streaming data, which allows clients to remotely control the server streaming the data.
Saturation
Saturation is the intensity of the colors in the active picture: the degree by which the eye perceives a color
as departing from a gray or white scale of the same brightness. A 100% saturated color does not contain
any white; adding white reduces saturation. In NTSC and PAL video signals, the color saturation at any
particular instant in the picture is conveyed by the corresponding instantaneous amplitude of the active
video subcarrier.
Sequence
To view a group of cameras, one after the other, either manually or automatically.
139
Server
A server is a computer and its software that provides some service for other computers connected to it
through a network.
Service
Service is the ability of a device within the Endura system to perform such functions as pan/tilt/zoom,
record video, and playback video. When a device comes online, these services are automatically
advertised to other devices on the network. For a user to access these services, the user must be assigned
a role with the proper permissions.
Sharpness
Sharpness refers to a function that allows a user to adjust the image between a “soft” look and a sharp
look.
SIF
Source Input Format. Resolution depends on the source: NTSC SIF equals 352 x 240 pixels. Also refer to
CIF.
System Manager (SM)

A piece of software that authenticates devices on the Endura network. This software runs on an Endura
DVR or NVR or as a standalone device.
TCP/IP connection
Transmission Control Protocol/Internet Protocol. TCP/IP is the standard way of communicating over a
network that ensures all devices on a network can communicate and information is passed without any
errors.
UDN
Universal Device Number.
UDP
User Data-gram Protocol is a connectionless protocol that, like TCP, runs on top of IP networks. Unlike
TCP/IP, UDP/IP provides very few error recovery services, offering instead a direct way to send and
receive data-grams over an IP network. It is used primarily for broadcasting messages over a network.
UID
Universal Identification Number.
140
Unicast
The standard method to transport IP traffic. In a unicast transmission, information is sent from one
computer directly to another computer on the network.
UPnP
UPnP is a family of networking protocols used to create a “hands off” network. In a Universal Plug and
Play network, objects are plugged into a network and automatically recognized and configured. All IP
addresses in a UPnP network are assigned dynamically through DHCP. If DHCP becomes unavailable in a
UPnP network, devices will default to Auto IP. Endura devices use the UPnP process when plugged into an
Endura network.
Uniform Resource Identifier (URI)

URI is used to identify a resource over a network.
Uniform Resource Name (URN)

A URN identifies, or more specifically, names a resource within a namespace.
Varifocal
Varifocal refers to a lens with a variable focal length. Varifocal lenses are low cost zoom lenses that can be
adjusted (zoomed) over a range of focal lengths. These lenses are much lower in cost than normal zoom
lenses because they have fewer elements in them.
Disadvantage: Unlike a zoom lens, a varifocal lens does not maintain focus when zoomed. It is practical
only for use with cameras where the zoom is set once at installation.
Advantage: The installer can adjust a varifocal lens for optimum field of view without changing the lens.
WSDL
Web Services Description Languages (WSDLs).
141
3500 Pelco Way
Clovis, California 93612-5699
United States
USA & Canada Tel (800) 289-9100
International Tel +1 (559) 292-1981
www.pelco.com

Pelco, the Pelco logo, and other trademarks associated with Pelco products referred to in this publication are trademarks of Pelco, Inc. or its affiliates.
All other product names and services are the property of their respective companies.
Product specifications and availability are subject to change without notice.

© 2012 Schneider Electric. All Rights Reserved.

Pelco API Programming Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Pelco API Programming Manual

Uploaded by

Copyright:

Available Formats

Pelco SDK 3.

Chapter 2: Object Model........................................................................... 16

Chapter 3: Displaying and Controlling Video Streams.......................... 21

Chapter 4: Pan, Tilt, Zoom (PTZ) Control................................................36

Chapter 5: Events and Alarms................................................................. 50

Chapter 6: Extracting Audio and Video Metadata.................................. 66

Retrieving the Current Timestamp Metadata.....................................................................................70

Chapter 7: Exporting Video...................................................................... 73

Chapter 8: Web Service Proxies.............................................................. 87

Appendix A: Logging.............................................................................. 104

Appendix B: Product Compatibility....................................................... 106

Appendix C: Endura................................................................................ 108

Appendix D: General Event Messages.................................................. 112

Appendix E: Hardware Diagnostics Event Messsages........................ 114

Appendix F: Software Diagnostics Event Messsages..........................124

Appendix G: Glossary............................................................................. 133

Getting Started with the Pelco SDK

What Does the Pelco SDK Contain?

System Manager Wrapper Device discovery

PTZ Control Wrapper Pan and tilt control

Subscribe to events from all instances of a particular web

Metadata Parser Parses Pelco Video Elementary Stream (VES) metadata:

Exporter Export video streams into a variety of popular video formats:

Code Sample Default Location

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

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

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

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

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

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

Installing the Pelco SDK

File Folder Path Description

C:\Program Files\Pelco\API Contains an application called LoggingSetup.exe which

System Environment Settings for the Pelco SDK

Including Required SDK Components For Your Application

Setting Up Sample Projects

Registering the ActiveX Control

Adding References to Managed Libraries for C#

Table 1: Object Model Public Classes

Table 2: Database Location

Operating System Directory

• Windows XP C:\Documents and Settings\All Users\Application Data

• Windows Vista C:\ProgramData\Pelco\SDK

Display the Devices

int _tmain(int argc, _TCHAR* argv[])

// Create a device collection object and populate it with the devices

// Display the device name

// Display the number of devices

The following sections describe the sample details.

Table 4: URL Scheme Components

Component Description Example

Component Description Example

Retrieving a Device Collection

Displaying Device Information

// Display the device name

In the sample, deviceCollection.Current() returns an object of type PelcoSDK::Device(). The

Table 5: Iteration Methods

Where Does the Pelco SDK Fit?

Initializing the Pelco API Viewer (C++)

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

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

// Set example parameters

// Check if authentication is enabled

HWND _hWndParent = NULL;