Pelcosdk c5617m H

Pelco SDK 3.
4 Programming Guide
C5617M-H
04 / 2014
Contents
Contents
Chapter 1: Introduction to the Pelco SDK........................................ 7

Pelco SDK Features.......................................................................................... 7
Pelco SDK Components and Classes...............................................................8
Overview of the Pelco SDK Object Model........................................................ 9
Chapter 2: Using Systems and Devices..........................................12

System Class................................................................................................... 12
System Providers and Schemes..................................................................... 12
Device Cache...................................................................................................14
Device Class.................................................................................................... 17
Using the Pelco SDK Runtime in your Application..........................................17
Creating a Pelco System.................................................................................18
Creating a Pelco Aggregation Direct System.................................................. 20
Creating a Pelco Edge System....................................................................... 21
Iterating Over Collections................................................................................ 23
Chapter 3: Viewing and Recording Video Streams........................ 25

Camera, Display, and Stream Classes........................................................... 25
Sample Code for Video Streams.....................................................................26
Initializing a Stream Object..............................................................................26
Playing Back Recorded Video.........................................................................27
Playing a Stream Forward...............................................................................28
Playing a Stream in Reverse.......................................................................... 29
Pausing a Stream............................................................................................ 30
Resuming Playback of a Paused Stream........................................................30
Switching From Playback to Live.................................................................... 30
Stepping Through a Video Stream..................................................................30
Taking a Snapshot...........................................................................................31
Setting the Stream Volume............................................................................. 31
Getting the Stream State.................................................................................31
Getting the Stream Mode................................................................................ 32
Using a Timestamp Event............................................................................... 32
Working With Stream Configurations.............................................................. 33
Constructing a New Stream Configuration...................................................... 34
Changing a Stream Configuration................................................................... 35
Chapter 4: Exporting Video with Clip and Exporter Classes......... 36

Clip and Exporter Classes...............................................................................36
Exporting Video................................................................................................37
Chapter 5: Exporting Video on Endura Systems............................39

Exporting Video with the Exporter Component............................................... 39
Custom Application Development....................................................................39
Getting Started.................................................................................................39
2 C5617M-H
Contents
Initializing the Exporter.................................................................................... 40

Setting Up Overlay Data on Video to Be Exported......................................... 41
OverlayData Parameters................................................................................. 42
Resetting Overlay Data................................................................................... 45
Exporting Video................................................................................................45
Exporting a Single Video Clip...............................................................45
Exporting Video Using a Playlist (PPX)................................................47
Stitching Multiple Clips into a Single Video Export............................... 48
Polling a Video Export.....................................................................................50
Stopping a Video Export................................................................................. 51
Exporting A JPEG Snapshot........................................................................... 51
Chapter 6: Using Network Displays and Channels........................ 53

What is a network display?............................................................................. 53
Using the Network Display Class.................................................................... 53
Chapter 7: Managing Systems with the Administrator Class........ 56

The Administrator Class.................................................................................. 56
Changing the Administrator Password............................................................ 56
Removing a System........................................................................................ 57
Removing All Systems.....................................................................................57
Administrator Class Code Examples............................................................... 58
Chapter 8: Using Event Classes...................................................... 60

SDK Event Classes......................................................................................... 60
Event Types..................................................................................................... 60
General Steps to Handling Events.................................................................. 62
Subscribing and Unsubscribing to Events.......................................................62
Writing Event Handlers....................................................................................64
Chapter 9: Events and Alarms......................................................... 66

Event Arbiter and Event Manager................................................................... 66
Event Arbiter Library........................................................................................68
Event Manager.................................................................................................68
General Steps To Handle Events....................................................................69
Creating an Event Agent................................................................................. 69
Returning the Event Subscription URL............................................................72
Initializing the Event Manager......................................................................... 73
Using the Event Manager to Subscribe to All Services...................................74
Using the Event Manager to Unsubscribe from All Services........................... 75
Initializing the Event Arbiter Library for C++................................................... 75
Initializing the Event Arbiter Library for C#......................................................76
When a System Manager Is Available on Your Network...................... 76
When a System Manager Is NOT Available on Your Network..............76
Using the Event Arbiter Library to Subscribe Using the Device’s IP Address...77
Using the Event Arbiter Library to Subscribe to a Device's Web Service...... 77
Using the Event Arbiter Library to Subscribe to All Instances of a Service..... 78
Using the Event Arbiter Library to Unsubscribe from a Service...................... 79
Handling Incoming Events............................................................................... 79
Polling Events.................................................................................................. 81
C5617M-H 3
Contents
Chapter 10: Viewing Video Streams with Pelco API Viewer

(Legacy).......................................................................................... 83
Legacy Component..........................................................................................83
Initializing the Pelco API Viewer (C#)............................................................. 83
Using the PelcoAPIViewer Component................................................ 83
Using the PelcoAPIMPFViewerControl Component............................. 84
Initializing the Pelco API Viewer (C++)........................................................... 85
Setting Size and Position of Video Display Area............................................ 86
Querying an RTP Stream................................................................................ 87
Opening, Playing, and Displaying a Live or Playback RTP Stream.................88
Opening, Playing, and Displaying an RTSP Stream....................................... 90
Forward Playback of RTP and RTSP Streams............................................... 91
Reverse Playback of RTP and RTSP Streams............................................... 91
Fast Forward / Reverse Playback of RTP and RTSP Streams....................... 92
Pausing RTP and RTSP Playback Streams................................................... 92
Frame Forward Playback of the RTP Stream................................................. 93
Frame Reverse Playback of the RTP Stream................................................. 93
Resuming the RTP or RTSP Stream from a Paused State.............................93
Stopping the RTP and RTSP Stream............................................................. 94
Start Manual Recording of RTP Stream..........................................................94
Stop Manual Recording of RTP Stream..........................................................95
Setting Audio Volume of a Live or Playback RTP stream............................... 95
Displaying Analytic Events for an RTP Stream............................................... 95
Displaying Motion Events for an RTP Stream.................................................95
Displaying a Timestamp Overlay for RTP and RTSP Streams....................... 96
Taking a Snapshot of the Current Video Frame for RTP and RTSP Streams...97
Pan, Tilt, Zoom (PTZ) Control for Live Video Streaming (RTP)...................... 97
Chapter 11: Pan, Tilt, Zoom (PTZ) Control......................................98

What is PTZ Control?......................................................................................98
Initializing the PTZ Control Wrapper............................................................... 98
Continuous Panning.........................................................................................99
Continuous Tilting.......................................................................................... 100
Continuous Diagonal Movement....................................................................101
Stopping Continuous Movement....................................................................102
Enabling Continuous Pan/Tilt/Move and Zoom APIs by UDP Instead of
TCP........................................................................................................... 102
Panning to a Specific Position.......................................................................102
Tilting to a Specific Position.......................................................................... 103
Moving to a Specific Position........................................................................ 103
Moving to a Position Relative to the Current Location.................................. 104
Getting the Camera’s Current Position..........................................................104
Managing the Magnification (Zoom) Value....................................................105
Managing the Focus Value............................................................................105
Iris Control......................................................................................................106
Scripting......................................................................................................... 107
Creating a Preset...........................................................................................108
Updating an Existing Preset.......................................................................... 108
Creating a Pattern......................................................................................... 108
Going to an Existing Preset.......................................................................... 109
Removing an Existing Preset........................................................................ 109
Updating an Existing Pattern.........................................................................110
Executing an Existing Pattern....................................................................... 110
Stopping a Pattern Currently Being Executed...............................................110
4 C5617M-H
Contents
Chapter 12: Extracting Audio and Video Metadata...................... 111

Processing Metadata..................................................................................... 111
Motion Detection Metadata............................................................................111
Pelco Analytics Drawing Primitives............................................................... 112
Timestamps....................................................................................................112
Getting Started...............................................................................................113
Initializing the Metadata Parser Class........................................................... 113
Creating a Metadata Renderer Class............................................................113
Retrieving the Current Timestamp Metadata.................................................114
Motion Detection Metadata............................................................................115
Retrieving Motion Detection Metadata................................................115
Rendering Motion Detection Metadata............................................... 115
Drawing Metadata..........................................................................................116
Retrieving Drawing Metadata..............................................................116
Rendering Drawing Metadata............................................................. 116
Chapter 13: Web Service Proxies (Legacy)...................................118

PelcoGSoap................................................................................................... 118
General Usage...............................................................................................118
Chapter 14: Discovery (Legacy).....................................................120

Device and Service Discovery Overview.......................................................120
Initializing the Pelco SDK System Manager Wrapper................................... 121
Automatically Determining the System Manager’s IP Address and Port
Number......................................................................................................122
Logging In and Logging Out..........................................................................122
Querying Available Devices from the System Manager................................ 122
Retrieving the System Manager’s Time Zone.....................................124
Retrieving the Network Time Server Address.....................................124
Retrieving a Web Service’s ID............................................................125
Retrieving a Specific Web Service’s Control URL.............................. 125
Retrieving the NVR Associated with the Device................................. 126
Retrieving the Device’s Friendly Name...............................................127
Retrieving the Device’s Device Description File (DDF) URL...............128
Retrieving All Web Services Available on a Device............................128
Retrieving Device Attributes.......................................................................... 129
Retrieving a System Manager’s Attribute........................................... 130
Retrieving a Web Service’s Attribute.................................................. 132
Creating an IDeviceStorage Class................................................................ 132
Appendix A: Logging...................................................................... 135
Appendix B: Product Compatibility............................................... 136
Appendix C: About Endura Video Management System..............138
Appendix D: General Event Messages.......................................... 141
C5617M-H 5
Contents
Appendix E: Hardware Diagnostics Event Messages.................. 143

ConfigurationButton (20180)..........................................................................143
DriverFailure (20150)..................................................................................... 144
Fans (20020)..................................................................................................144
HardDrives (20060)........................................................................................146
ImproperShutdown (20070)........................................................................... 148
LinkSpeed (20200).........................................................................................149
PowerSupply (20120).................................................................................... 150
UPS (20170).................................................................................................. 151
Appendix F: Software Diagnostics Event Messages....................153

DataLoss 20040.............................................................................................153
InputStreams 20160.......................................................................................153
PacketLoss 20080......................................................................................... 155
SEBs 20210................................................................................................... 156
StorageFull 20190..........................................................................................157
StorageTime 20130....................................................................................... 158
Temperature 20140....................................................................................... 159
Appendix G: Video Streaming and Exporting Performance........ 161

Glossary.........................................................................................
A..................................................................................................................... 164
B..................................................................................................................... 164
C.....................................................................................................................164
D.....................................................................................................................165
E..................................................................................................................... 165
F..................................................................................................................... 166
G.....................................................................................................................166
H.....................................................................................................................166
I...................................................................................................................... 166
M.................................................................................................................... 167
N.....................................................................................................................167
P..................................................................................................................... 168
R.....................................................................................................................168
S..................................................................................................................... 168
T..................................................................................................................... 169
U.....................................................................................................................169
V..................................................................................................................... 169
W.................................................................................................................... 170
6 C5617M-H
Introduction to the Pelco SDK

Pelco SDK Features
Pelco by Schneider Electric offers the Pelco SDK to help our development partners
write applications for controlling Pelco products and for integrating with non-
Pelco products and software. The Pelco SDK handles direct communication to
various Pelco devices, which reduces the size and complexity of your applications.
Specifically, the Pelco SDK takes care of making the API calls to the devices on
behalf of your application so that your applications don't need to include messaging
details.
With the Pelco SDK, your applications can:
• Determine what devices and services are available on your Pelco network
• Display live and recorded video
• Control a camera's viewing position including pan, tilt, and zoom (PTZ) actions
• Export video and save in PEF, AVI, MP4, 3GP, MOV, or PPX format
• Handle events and alarms
• Parse audio and video metadata
The Pelco SDK simplifies application development by providing fully-functioning
"building blocks" that you can include in your Pelco applications. The SDK consists of
two types of building blocks:
• Objects
• Components
The Pelco SDK Object Model encapsulates Pelco products and functionality in a set
of classes that represent the following:
• Pelco video management systems such as Endura, Pelco Aggregation, Digital
Sentry, and DX 47/4800 Series
• Sarix ® or Spectra® cameras
• Other Pelco devices, such as digital video recorders (DVRs), network video
recorders (NVRs), encoders, decoders, or monitors
• The ability to display and record video
• The ability to export video to disk
Before the Object Model, the Pelco SDK provided a set of prebuilt components to
obtain a list of devices on a system, display video, exporting video to disk, and more.
Eventually, all SDK functionality will be available through the Object Model while
components will be phased out. But during this transitional phase, your applications
will likely include a combination of components and classes.
Sample Programs
This programming guide contains C# and C++ code examples to illustrate how to
use the Pelco SDK. Most are snippets of complete C# and C++ sample programs
that are located in the subdirectory where the Pelco SDK is installed: \Pelco\API
\SampleCode\. These sample programs illustrate specific coding techniques
required to incorporate the Pelco SDK capabilities in your applications.
NOTICE
The set of sample programs provided with the Pelco SDK is considered a
reference implementation for educational purposes. In general, Pelco sample
programs are not intended for immediate production use without modification. For
details, see About Sample Code on PDN.
C5617M-H 7
For More Information

The Pelco SDK 3.4 Quick Start Guide provides a detailed overview of the Pelco SDK.
It's available on Pelco Developer Network (PDN). PDN also contains several articles
and coding samples that go into greater detail on specific aspects of the SDK.
Pelco SDK Components and Classes

During the transitional phase when the Pelco SDK consists of both classes and
components, as a general rule, you should use classes if they exist. Use components
when the functionality is not available through Object Model classes.
Objects are simpler to insert into your applications and much easier to use. For
example, when creating an instance of a Stream object, the stream uses default
values based on internal parameters according to the common use. You can easily
change the default values with the StreamConfiguration class. In contrast, when
creating a stream with the PelcoAPIViewer, you must specify a long list of parameters
to set up the stream.
Some components provide functionality that is not yet available with the Object
Model. To distinguish between valid and outdated components, this guide labels
components "legacy" when their functionality has been replaced by classes.
NOTE: Do not use legacy components, if you can avoid it, when writing new
applications with the Pelco SDK.
Components To Use
At this point, continue to use the following components when developing your
applications.
Exporter Component Exports video streams and stores on disk; available only
for Pelco Endura video management systems. For Pelco
Aggregation systems, you can use the Clip and Exporter
classes instead.
Metadata Parser Extracts audio and video metadata.
Event Arbiter Library Handles device events such as motion and analytics.
and Event Manager For events that are related to the SDK process or for
determining whether devices are on line or off line, use the
Event and Events classes.
Pan, Tilt, Zoom (PTZ) Controls a camera's viewing position, for example, pan, tilt,
Control Wrapper zoom, iris, and focus.
Legacy Components
We use the term "legacy" to refer to the components whose functionality has been
replaced by Pelco SDK classes. Do not use the following components in new Pelco
applications as they will become obsolete soon.
PelcoAPIViewer Captures live and recorded video from Pelco cameras,

(Legacy) DVRs/NVRs and NSMs. This functionality is now available
through the combination of Camera, Display, and Stream
classes.
System Manager Initializes a System Manager and queries available
Wrapper (Legacy) Pelco devices. This functionality is available through the
SystemCollection, System, Device Collection, and Device
classes.
Pelco SDK versus Pelco API
8 C5617M-H
Another way to communicate directly with Pelco devices is through the Pelco API,
bypassing the Pelco SDK altogether. Pelco API is a set of SOAP-based web services
which you access through WSDL files. The Pelco API is a public interface and can
be used in the same way as other web-service interfaces. For integration developers
who have previously created web service-based applications, working with the Pelco
API is straightforward. For details on the Pelco API, refer to Introduction to the Pelco
APIon Pelco Developer Network (PDN).
Overview of the Pelco SDK Object Model

The Pelco SDK introduced the Object Model to define classes to represent
components of a Pelco video management system. Classes represent systems and
all connected devices, such cameras, recorders, encoders, decoders, and monitors.
This topic provides a brief overview of the Object Model. Also, for a more in-depth
introduction to the Pelco SDK Object Model, refer to the Pelco SDK 3.4 Quick Start
Guide available on PDN.
Classes of the SDK 3.4 Object Model
The class diagram below introduces the Pelco SDK classes as of SDK 3.4 and shows
how they interact. Collection classes indicate those classes that exist in containers so
that you can manage them as one entity.
Orange arrows indicate an "is a" relationship where the class is derived from the
parent class. For example, a Camera is a kind of Device. Green arrows indicate a
"has a" relationship where the class is contained in the parent class. For example, a
System contains Devices.
The following illustration shows additional Object Model classes. For event handling,
you can use the Event class to declare the types of events to handle and the Events
class to subscribe to listeners (shown above). You can use the Exception class to
handle exceptions for error conditions in the Object Model. You can use PString,
PList, and PTime classes for ease in handling lists, strings, and time values.
C5617M-H 9
The Pelco SDK 3.4 Object Model

The following table summarizes the classes defined in the Pelco SDK Object Model
as of 3.4.
Table 1: List of the Pelco SDK Classes
Class Function
Administrator Manages all systems without requiring the user name and
password of any single system. The Administrator class
represents a "superuser" whose credentials supersede the
admin credentials of all individual systems. For details, see
Administrator Class Overview.
Camera Manages an IP camera such as a Sarix ® or Spectra® model. See
Viewing and Recording Video Streams.
Channel Transmits a single channel of video to a multichannel remote
monitor. The Channel class represents video that appears in a
rectangle on the network display. See Using Network Displays.
Clip Creates an excerpt of recorded video by specifying the start and
stop time. Used with the Exporter class to export video to disk.
Device Manages a physical device contained in the video management
system. The Device class can represent a camera, encoder,
decoder, digital video recorder (DVR), or network video recorder
(NVR). See Using System and Device Objects.
Display Displays video streams in a window on a monitor. Multiple
streams appear in separate windows. The Display class
represents a local monitor attached to the computer on which the
SDK is running. See Viewing and Recording Video Streams.
Event Defines the type of events to listen for, such as whether a device
is online or if its properties change, or whether a Stream fails.
See Using the Event Objects.
EventListener Listens for events and calls the event handler when an event
is fired. The GlobalEventListener class listens for global events
across the entire system collection, such as the SDK state. The
SystemEventListener class listens for events on a specific system
and its associated devices. See Using the Event Objects.
Events Subscribes and unsubscribes to events. See Using the Event
Objects.
Exception Handles exceptions on Try and Catch execution. The Exception
class can return error codes and messages.
Exporter Exports recorded video and saves it to PEF format. Available for
Pelco Aggregation systems only.
10 C5617M-H
Class Function
NetworkDisplay Displays video on a remote monitor, where each video channel
appears in a rectangle on the monitor. The NetworkDisplay class
allows an operator to manage monitors residing elsewhere on
the network from a local computer running the SDK. See Using
Network Displays.
Property Defines and manages arbitrary name/value pairs used in your
application.
PString Defines and manages character strings.
PTime Retrieves and sets time by day, hour, minute, month, year, and
so on.
Stream Plays live or recorded video. If recorded, makes available the
typical video controls such as pause and rewind. See Viewing
and Recording Video Streams.
Stream Changes how the Stream class behaves, for example, its frame
Configuration rate, format (MJPEG or MPEG-4/H.264), protocol (RTP, RTSP,
or HTTP), delivery mode (unicast or multicast) or whether it
contains audio. See Working with Stream Configurations.
System Creates and manages systems and devices. The System class
represents a system manager (SM) or a Pelco Edge system,
which is a collection of cameras or other devices without an
SM to manage it. It can also represent a system that allows
applications to send calls directly to a Pelco Aggregation System.
See Using System and Device Objects.
Multiple Enables iterating over a collection. The collection can consist of
Collection one of these classes: Channel, Device, Property, and System.
classes See Collection Objects.
Object Model Libraries

The Object Model functionality is contained in a dynamic link library file (.dll). There's
one for .NET and one for C++.
• PelcoSDK.dll, for C++
• Pelco.SDK.dll, for any .NET language
C5617M-H 11
Using Systems and Devices

System Class
The System class represents a system on a Pelco video management system (VMS).
With the System class you can
• Retrieve a system manager (SM) by its display name, alias, UUID, IP address and
port number.
• Retrieve the devices connected to the System, such as cameras, encoders,
decoders, and network video recorders (NVRs).
• Retrieve information about a device including its type, UUID, model name,
manufacturer, and so on.
• Remove systems.
The System class can also represent a Pelco Edge system, which is a special type of
"virtual" system that consists of a set of devices without an SM.
The SystemCollection class represents a collection of systems that comprise a Pelco
network.
Here's a picture that illustrates a video management system, represented by a
SystemCollection. It contains an Endura system, represented by a System class with
connected cameras, two NVRs, and a System Manager. It also contains a Pelco
Edge system, also represented by a System class but with only cameras attached.
Currently, the System class can represent the following Pelco video management
system products:
• Endura, the Pelco video management system that is managed by a system
manager (SM) appliance such as an SM5200 or SM5000.
• Pelco Aggregation Software, which allows Endura customers to monitor multiple
Endura installation sites through a common user interface.
• Pelco Edge system, which is a Pelco SDK "virtual" system that enables SDK
applications to connect to cameras without using a system manager.
• Digital Sentry products: Network Video Recorder and Analog Encoder.
• DX 47/4800 Series.
To initialize an instance of a System, you specify its System provider and Scheme.
System Providers and Schemes

When you initialize a system, you specify the system provider. Each system provider
has its own capabilities but all can be accessed through the System class.
12 C5617M-H
Table 2: Pelco System Providers
System Provider Video Management Capabilities

System
Pelco System Pelco Aggregation • Local device cache
(pelcosystem) populated through
device discovery
• MJPEG video format
• Export video with
Exporter component
SM5200 • Local device cache

populated through
device discovery
• MJPEG and MPEG-4/
H.264 video format
Exporter component
SM5000, Digital Sentry, • Local device cache

DX 47/4800 Series populated through
device discovery
• MPEG-4/H.264 video
format
Exporter component
Pelco Aggregation Direct Pelco Aggregation • Direct access to

(pelcoaggregationdirect) devices
• No device cache
• MJPEG video format
• Exporter class used to
export video to file
Pelco Edge None • Local device cache

(pelcoedgedevices) populated manually
• No system manager
• MPEG-4/H264 video
format
• Supports live streaming
only
• Does not work on a
network display
TIP
The above table shows that Pelco Aggregation can be implemented using
either the pelcosystem or pelcoaggregationdirect provider. To enable
the Pelco SDK device cache mechanism, you must use the pelcosystem
when creating the Pelco Aggregation system. If you don't want to use the
Pelco SDK device cache, create the Pelco Aggregation system with the
pelcoaggregationdirect provider.
System Scheme
C5617M-H 13
When you initialize a system, you specify the type of system provider in its system
scheme. A system scheme resembles a Web address, more specifically, the top level
of the URI naming structure. The system scheme format is as follows:
[user:pass@]provider_name://[ipaddress:port][?alias=System Name]
where
user:pass The user name and password for the

System. Required for the pelcosystem and
pelcoaggregationdirect providers. Optional
for pelcoedgedevices.
provider_name:// The system provider which can be
pelcosystem, pelcoedgedevices, or
pelcoaggregationdirect. Required.
ipaddress:port The IP address and port number of the System.

Required for the pelcoaggregationdirect
provider and any Pelco Aggregation-based system.
Optional for pelcosystem if using autodiscovery.
Do not use for pelcoedgedevices.
?alias=MySystem A query string to define another name for the
System. Set this to any unique value for a particular
System. An alias enables the developer to assign a
key to the System so that it can be retrieved easily
in the future. Required for the pelcosystem and
pelcoaggregationdirect providers. Optional
for pelcoedgedevices.
The following example creates a Pelco System with "admin" as a user name and
password and "PelcoSystem" as an alias.
PelcoSDK::System system("admin:admin@pelcosystem://1.2.3.4:80?
alias=PelcoSystem");
For details on creating systems for each system provider, see:

• Creating a Pelco System
• Creating a Pelco Aggregation Direct System
• Creating a Pelco Edge System
Device Cache
To improve Pelco SDK runtime performance, the SDK stores device information
locally on the computer where it is running. This is called the device cache. Once
the device cache is populated with device information from devices on the network,
subsequent requests for the information go to the local cache instead of over the
network.
NOTE: The system providers pelcosystem and pelcoedgedevices make use of
the device cache. The pelcoaggregationdirect system provider does not. For
more on system providers, see System Providers and Schemes.
The device cache maintains information about devices (cameras, encoders, and
so on) that are connected to the Pelco system. If the Pelco network is configured
with multiple systems, a device can be associated with multiple systems. If the
pelcosystem provider is connected only to a Pelco Aggregation system, only
cameras and encoders are collected.
14 C5617M-H
Device information is defined by the Device class. It includes the Device type, UUID,
model number, and so on. For a list of all Device properties, refer to the Device Class.
During program execution, the Pelco SDK runs a background process to
query the network and updates the device cache with the latest information
on systems and devices. By default, the background process refreshes the
device cache database every five minutes. You can change the interval with the
System.SetRefreshSeconds() method.
How Device Information Is Collected
How the device cache is populated depends on the system provider:
Pelco System: The SDK queries the devices over the network,
pelcosystem which is called Discovery. Discovery can be
automatic or direct. If the IP address is not provided
when the system is created, the SDK searches
the network for a System Manager (SM) and
automatically adds the devices associated with
that SM to the device cache. This process is called
autodiscovery. Alternatively, when an IP address
is provided, the SDK queries the specified SM
to discover the devices associated with it. This
is called direct discovery. See Creating a Pelco
System.
Pelco Edge System: Devices are added manually by the application.
pelcoedgedevices Without a system manager, the Pelco SDK
cannot discover devices. Instead, you add the
Pelco system and its associated devices to the
device cache directly using Add() method of
SystemCollection and DeviceCollection
classes, respectively. Once cached, the Pelco Edge
Systems are handled the same way as systems
containing a system manager. See Creating a Pelco
Edge System.
Pelco Aggregation Does not use the device cache. See Creating a
Direct System: Pelco Aggregation Direct System.
pelcoaggregationdirect
Retrieving Devices
Your application gets device information from the device cache using the
DeviceCollection class. How you retrieve the information depends on whether
this is a Pelco or Pelco Edge System.
To retrieve the information from the device cache, you perform these steps:
1. If this is a pelcosystem, retrieve the DeviceCollection. It is already
populated with information from the device cache.
2. If this is a pelcoedgedevices, retrieve the DeviceCollection
and populate it with information about devices on the network using the
Device.Collection.Add() method.
3. Loop over the DeviceCollection.
4. Retrieve the current device.
5. Move on to the next device in the collection.
Once you have created a Pelco System or Pelco Edge system, iterate over the
returned DeviceCollection object to locate a specific device. These devices are
stored in the system's DeviceCollection (device cache), in memory, and on disk.
NOTE: For information on iterating over collections, see Iterating Over Collections.
C5617M-H 15
Code Example
Here's a code example of retrieving a list of a devices connected to the system and
displaying the name of each device.
int _tmain(int argc, _TCHAR* argv[])

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

// from the system object
PelcoSDK::DeviceCollection
deviceCollection(system.GetDeviceCollection());
// Loop over the device collection object and

// display each device name
printf("\n\n> DEVICES =================================\n");
for (deviceCollection.Reset(); deviceCollection.MoveNext(); )
{
// Retrieve the current device object
PelcoSDK::Device device(deviceCollection.Current());
// Display the device name

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

printf("=========================================\n");
printf("Total Devices: %d", deviceCollection.GetCount());
}
catch (PelcoSDK::Exception ex)
{
printf("An error occurred\nError: %s", ex.Message().c_str());
}
return 0;
}
Managing the Device Cache

The device cache is a database file called PelcoDeviceCache.db. It was created
as part of the SDK installation process but remains empty until the Pelco SDK is
initialized. The database is located in the program data directory, C:\ProgramData
\Pelco\SDK.
When an application starts the Pelco SDK runtime for the first time, it can take some
time to collect the device information for the entire Pelco network. The application
is blocked until the device collection is complete. Since the device cache persists,
there's no delay when the SDK runtime is started afterward. When the Pelco SDK
starts up again, it runs an integrity check and verifies the cache contents against the
systems and devices on the network. It then makes the cache available to the running
application. Applications can determine whether device collection is complete using
the SDK_State event type. See Event Types.
Changes to the device cache require administrator access. The administrator is
represented by the Administrator class, and its methods allow you to perform tasks on
the device cache, such as removing a system or all systems from the database. For
details, refer to Using the Administrator Class.
16 C5617M-H
Some integration developers, particularly on extremely large systems, might

determine that the device cache does not improve performance. In this case, use the
pelcoaggregationdirect system provider, which does not use a device cache.
This is available on Pelco Aggregation systems only. For details, see Creating a
Pelco Aggregation System.
Device Class
The Device class defines the following information for devices. Most properties are
shared across all devices. The Camera and Network Display classes are derived from
Device and contain additional information specific to the device type.
DeviceType Type of device, which can be a Camera object,

NetworkDisplay object, Encoder, Decoder,
Recorder, Monitor, Controller, or Unknown.
FriendlyName A more human-readable device name. Developers
can use this to display the device name in the user
interface and administrators can change the name.
UDN A Pelco device’s Unique Device Name (UDN);
a special device identifier for networks. This
is also referred to as its UUID. For example,
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15".
Ip The device IP address, for example,
10.220.196.187.
Port The device port number of an IP address. For
example, given the address 10.220.196.187:6001,
the port number is 6001.
ModelName The device model name. Users can customize
the model name, so the model name might not be
unique.
ModelNumber The device model number.
Manufacturer The device manufacturer.
Version The device version number.
SerialNumber The device serial number.
Online Determines whether device is on line. True if the
device is on line. False if the device is unavailable.
How to Retrieve Device Information

How device information is received from a system depends on the system provider.
Pelco System and Pelco Edge System providers retrieve device information from
a device cache stored on the computer running the Pelco SDK. For information on
retrieving device information from the device cache, see Device Cache.
The Pelco Aggregation Direct system provider retrieves information directly from the
device on the netwok. For details, see Creating a Pelco Aggregation Direct system.
Using the Pelco SDK Runtime in your Application

Applications using the Pelco SDK Object Model must start up the Pelco SDK runtime
before using it. When the application completes, it must explicitly shut down the SDK
for a clean exit. To do so, call the Startup method before making any calls to the
SDK, and call the Shutdown method after the last call to the SDK.
Here's how to use the Startup and Shutdown methods Pelco SDK application in
C# .NET and C++.
C5617M-H 17
.NET
Pelco.SDK.Application.Startup();
Pelco.SDK.Application.Shutdown();
C++
PelcoSDK::Startup();
PelcoSDK::Shutdown();
Here is an example that shows how to start up the Pelco SDK runtime from a
C#/.NET application. This application takes advantage of .NET features including
Windows® Forms.
namespace ViewVideo
{
static class Program
{
// Main entry point to the application
static void Main()

{
try
{
// Start the SDK runtime

Pelco.SDK.Application.Startup();
// .NET
Application.EnableVisualStyles();
// .NET
Application.Run(new LoginForm());
}
catch(Exception ex)
{
MessageBox.Show(ex.Message, "Error", MessageBoxButtons.OK,
MessageBoxIcon.Error);
}
finally
{
// Stop the SDK runtime
Pelco.SDK.Application.Shutdown();
}
}
}
}
Creating a Pelco System

You can use the Pelco System provider, pelcosystem, to create a system that uses
the device cache. It is available for Endura, Pelco Aggregation System, Digital Sentry,
and DX 47/4800 Series video management systems. For details on how the device
cache works, see Device Cache.
Currently, the Pelco SDK enables you to create systems using one of three system
providers. For a comparison of all Pelco SDK system providers, see System
Providers and Schemes.
18 C5617M-H
Creating a Pelco System

To create a Pelco System, specify pelcosystem for the provider in the system
scheme. Here's an example:
alias=MySystem");
where
admin:admin@ The user name and password for the System. If you
do not supply credentials, the System is readonly
until you log in. See the note below.
pelcosystem:// The system provider, in this case, the Pelco
System, which can represent one of these video
management systems: Endura system, Pelco
Aggregation, Digital Sentry, and DX 47/4800 Series.
Required.
ipaddress:port The IP address and port number of the system.
For Endura systems, if you do not specify the IP
address, the Pelco SDK runtime automatically
queries the network for a system manager and its
associated devices; if an IP address is specified,
Pelco SDK discovers the devices on the specified
SM.
?alias=MySystem A query string to define another name
for the System. Set this to any unique
value for the System. Then, use the
SystemCollection.GetItemByKey method to
retrieve the system at a later time. Optional.
NOTE:
If the user name and password are not provided, you do not have full access
to the system. You can retrieve basic properties of a system such as the
display name, IP address, port, alias, and system refresh time. However, any
attempt to call the following methods throws an exception with an error code of
PelcoSDK::NotAuthenticated:
• GetDeviceCollection()
• GetDevice()
• SetRefreshTime()
• SetAlias()
• Remove()
Once you log in to the system you have full access.
NOTE: If you have multiple systems on different subnets, you must supply the IP
address for the SM. This is because the Pelco SDK cannot detect system managers
outside the subnet on which it is running.
Creating a Pelco system takes the following steps.
1. Construct a system specifying pelcosystem as the provider in the system
scheme. Pelco SDK discovers the devices on the network and creates a
DeviceCollection of existing devices and stores it in the device cache.
2. Iterate over the device collection to retrieve the desired device.
Code Example
C5617M-H 19
Here's a complete code example that creates a PelcoSystem object, displays the
model name of each device, and gives the number of devices in the device collection.
int _tmain(int argc, _TCHAR* argv[])

{
try
{
// Create a system object
alias=Sample");
// Create a DeviceCollection object and populate it with the devices

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

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

printf("=========================================\n");
printf("Total Devices: %d", deviceCollection.GetCount());
}
catch (PelcoSDK::Exception ex)
{
printf("An error occurred\nError: %s", ex.Message().c_str());
}
return 0;
}
Creating a Pelco Aggregation Direct System

Create a system using the Pelco Aggregation Direct provider,
pelcoaggregationdirect, if you do not require the Pelco SDK to manage a
device cache on your local machine. This provider retrieves device information
directly from the Pelco Aggregation Server.
NOTE: The Pelco Aggregation Direct provider is available on Pelco Aggregation
systems only.
Some integration developers dealing with extremely large systems might determine
that the device cache does not improve performance. In this case, developers can
use the pelcoaggregationdirect system provider, which does not use a device
cache.
NOTE: The Pelco Aggregation Direct provider serves a special purpose and is not
expected to be used frequently. Since the Pelco SDK runtime is not keeping track of
device information, your application would likely require its own device database.
20 C5617M-H
To create a Pelco Aggregation Direct system, specify the

pelcoaggregationdirect provider in the system scheme. Here's an example:
PelcoSDK::System system(“admin:admin@pelcoaggregationdirect://
10.220.196.187?alias=PelcoDirect”);
NOTE: Do not specify a port number here. Pelco Aggregation uses SSL and the
default SSL port is supplied by default (443).
Retrieving Device Information Directly
Once the System instance is created, retrieve device information directly from a
specific device using the System.GetDeviceByAttribute method.
The System.GetDeviceByAttribute method takes as parameters an attribute
and its value. Attribute is an enum value, which can be either camera number or
device UUID. Value is a string. The following example retrieves a camera with a
camera number is 2.
PelcoSDK::System s2(SDKVxPelcoDirect);
PelcoSDK::Device dev = s2.GetDeviceByAttribute(PelcoSDK::kCAMERA_NUMBER, "2");
NOTE: If you don't specify a user name and password with the scheme, you will
receive authentication exceptions until you log in to the system.
Creating a Pelco Edge System

Create a system using the Pelco Edge provider, pelcoedgedevices, when you do
not want it to use a system manager (SM). The Pelco Edge System simply consists
of an arbitrary set of devices that is a "virtual" system. The Pelco SDK uses the
Pelco Edge system to perform device caching even though a system manager is not
present.
A Pelco Edge System is useful in the following situations:
• In smaller installations consisting of a few cameras or other devices that do not
require a physical system manager appliance
• In cases where you want to access cameras that require camera-level
authentication , such as a Sarix ® 1.8.2 (or later)
• In ad hoc situations to meet a specific need without requiring a change in network
topology or hardware reconfiguration
NOTE: Devices on a Pelco Edge System have some limitations. With a Pelco Edge
device, you can stream video to a local display attached to a computer; but you
cannot stream video from a camera to a NetworkDisplay. Additionally, Pelco Edge
devices can stream live video only.
NOTE: The Pelco SDK supports Sarix cameras as Pelco Edge devices, not including
IL10 cameras.
Once populated, the Pelco SDK manages the device cache the same way.
Creating a Pelco Edge System
To create a Pelco Edge System you are essentially "building" your system by adding
the cameras to be contained in the Pelco Edge system. The steps to create a Pelco
Edge system are
C5617M-H 21
1. Construct a system specifying pelcoedgedevices as the provider on the system

scheme. You can include an alias and credentials, but not an IP address since this
is a virtual system residing only in the local device cache.
2. Add devices to the system manually using the DeviceCollection.Add method.
Supply a user name and password for those devices that require authentication.
3. Iterate over the device collection to retrieve the desired device. See Iterating Over
Collections.
// Create a Pelco Edge System with credentials

// and an alias, "EdgeDeviceSystem"
System system(“admin:admin@pelcoedgedevices://?alias=EdgeDeviceSystem”);
// Create a device collection for the system

DeviceCollection dc = system.DeviceCollection;
// Add a device. Credentials are specified because

// the device requires authentication.
DeviceCollection devicesAdded =
dc.Add(“admin:admin@pelcoedgedevices://123.456.789:9001”);
NOTE: The Pelco SDK throws exceptions in the following instances:

• "Device already exists" exception if the specified device already exists in the
device collection
• "Device not found" exception if the SDK cannot contact the specified device
• "Device unrecognized" exception if the SDK can find the specified device but it is
not supported
NOTE: Multiple logical devices can exist at the same IP address and port. For
example, a multichannel encoder can have multiple cameras at the same IP address
and port. The DeviceCollection.Add method can add all of them.
Removing a Device from a Pelco Edge System
Just as you manually add devices to a Pelco Edge device collection and add the
Pelco Edge System to the system collection, you must manually remove devices and
Pelco Edge Systems. Use the DeviceCollection.Remove method to remove a
device, which takes the Device object that you want to remove as the parameter.
1. Retrieve the system's device collection.
2. Loop through the devices within the collection to find the device to remove.
3. Retrieve the current device within the device collection.
4. Determine if this is the device to remove.
5. Check if this device has the appropriate characteristic for deletion.
6. Use the DeviceCollection.Remove() method to remove the device.
7. Move on to the next device in the device collection.
Here's a code example demonstrating the above steps:
// Iterate through the device collection

for (deviceCollection.Reset(); deviceCollection.MoveNext(); ) {
// Retrieve a device from the device collection

// Check if this device has the appropriate characteristic

// for deletion, in this case, the model name
if (device.GetModelName() == "DeleteMe")
{
//Remove device
22 C5617M-H
deviceCollection.Remove(device);
}
}
NOTE: The Remove() method also removes any devices associated with the
removed device.
Removing a Pelco Edge System from the System Collection
A Pelco Edge System is listed in the same device cache as all other devices in the
Pelco network (once the devices have been added manually). You can delete a Pelco
Edge system from the device cache using the SystemCollection class.
Here are the steps to remove the Pelco Edge system:
1. Retrieve the system that you want to remove.
2. Remove the system.
Here's a code example of removing a Pelco Edge system.
// Retrieve the system to remove. In this example,

// remove the first system in the collection.
System sys = systemCollection.GetItem(0);
// Remove the system.

sys.Remove();
NOTE: Removing a System object through System.Remove() does not remove

the object immediately. It is removed only after all references to that System object
have been released.
Iterating Over Collections

The Pelco SDK contains several collection classes that enables iteration over a
collection of a particular type. A typical use is to iterate over a device collection and
display each device. The SDK contains several Collection classes that act on a set of
objects:
• ChannelCollection
• DeviceCollection
• PropertyCollection
• SystemCollection
Use the following methods to iterate over collections.
Reset() Resets the counter to its initial position, which is

before the first object in the collection.
MoveNext() Moves to the next item in the collection. This
method must be called before Current(). It
returns true to indicate the end of the collection has
not been reached; false indicates that the end has
been reached.
Current() Retrieves the current item in the collection.
Use the following methods to directly access items in a collection.
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,
use the system alias as the key.
C5617M-H 23
Some collections provide additional operations based on the type of object. For
example, a SystemCollection contains methods to add and remove systems from the
collection; this is for use with Pelco Edge systems.
24 C5617M-H
Viewing and Recording Video Streams

Camera, Display, and Stream Classes
The Pelco SDK Object Model makes it easy to start and view a video stream using a
small number of method calls from these classes:
Camera Represents any IP camera such as a Sarix ® or

Spectra® model.
Display Represents a window on a local monitor that
displays a video stream. The monitor might have
several windows where each window displays a
separate video stream.
Stream Represents live or recorded video. Live and
recorded streams are treated as a single entity so
the operator does not have to manage separate live
and playback video stream instances. Both live and
playback video can be managed through a single
instance of a Stream object.
The following figure shows that it takes Camera, Display, and Stream classes to
display a video.
IMPORTANT
These Object Model classes replace the Pelco API Viewer functionality and
provide a simpler, cleaner way to process video streams. Pelco API Viewer should
not be used in active development.
The StreamConfiguration class gives you the ability to change stream settings. For
example, changing:
• Delivery mode
• Video format
• Frame rate
Stream Events
You can check for failures on streams with the StreamEvent class. For details on
handling events for the Pelco SDK Object Model classes, see Using Stream Events.
Supported Video Formats
C5617M-H 25
The type of video format supported by a Stream depends on which video

management system and system provider is used as per the following table.
Table 3: Supported Video Formats for Streams Based on VMS
System Provider Video Management Supported Video Format

System
Pelco System • SM5000, Digital • MPEG-4/H264 video
(pelcosystem) Sentry, DX 47/4800 format.
Series
• Pelco Aggregation • MJPEG video format.
• SM5200 • MPEG-4/H264 video

format by default. Can
also stream MJPEG.
Pelco Aggregation Direct • Pelco Aggregation • MJPEG video format.

(pelcoaggregationdirect)
Pelco Edge • None • MPEG-4/H264 video
(pelcoedgedevices) format.
Sample Code for Video Streams

C# and C++ sample programs are supplied with the Pelco SDK in the directory where
Pelco API is installed: Pelco\API\SampleCode. You can find a C# program to view
video at Pelco\API\SampleCode\dotNet\ViewVideo.
Initializing a Stream Object

Initializing a Stream requires getting a Camera from the DeviceCollection and then
constructing a Camera when it is acquired. The Stream can initialize itself using the
given Camera.
The sequence for viewing live video is as follows:
1. Create a System object.
2. If this is a Pelco Edge system, add a Camera to the system.
3. Select a Camera from available devices contained in the System's
DeviceCollection.
4. Create a Stream object from the Camera.
5. Create a Display object.
6. Start the stream.
More specifically:
1. Find the Camera that needs to be displayed.
// Get a Camera from the DeviceCollection by its UUID

Pelco.SDK.Camera cam = deviceColl.GetItemByKey(camUUID);
2. Create a Stream after a Camera is acquired.
// Create a Stream instance from a camera

Pelco.SDK.Stream stream = new Pelco.SDK.Stream(cam);
3. Create a Display to view the Stream.
26 C5617M-H
The Display class represents a viewable area for an application. The Display
object requires only an HWND reference for its initialization so a stream image can
be shown in almost any Windows® window, including the console.
// Create a Display using the Handle to a predefined "videoPanel."

Pelco.SDK.Display disp = new Pelco.SDK.Display((IntPtr)videoPanel.Handle);
4. Bind the Stream to the Display object so it can be viewed.

With the Camera, Stream and Display Objects created, all the pieces required
to display the Stream are present. Class member variables must be declared for
_stream and _display to proceed with creating a stream instance and display the
stream. The following example program:
• Creates a new Stream
• Creates a new Display that binds the videoPanel's Handle to the display
• Calls Play on the Stream (kFWD_1X in the call means to play live forward at
standard speed)
• Displays video on the user interface
private void CreateStreamAndPlay(Camera camera)

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

local monitor used to view the streams. You
create a Display object using a WIN32 HWND.
Camera class A Camera class represents an individual camera
device. It is derived from the Device class. The
Camera.CreateStream() method is used to
retrieve a Stream from a particular camera.
NOTE: You can get and set a camera number for the camera. However,
Endura systems (pelcosystem) allow multiple cameras to have the same camera
number. Therefore, you cannot count on a camera's number being unique. Pelco
Aggregation systems (pelcoaggragationdirect) do not allow multiple cameras to
have the same camera number.
Playing Back Recorded Video

This section describes how the Stream object is used for playback and how a specific
date or time can be specified for the start date/time of the stream. Recorded video
can be played back in the forward direction or in reverse by using either a positive or
negative speed constant respectively. Refer to the sections Play a Stream Forward
and Play a Stream in Reverse for predefined speed constant definitions.
C5617M-H 27
1. After initializing a Stream object, call the Stream Play() method to playback
recorded video. In this example, the playback is requested in reverse direction
using a negative speed value. The speed constant kREV_2X specifies reverse
direction at two times standard speed.
// Start playing the stream in reverse at 2x standard speed.

_stream.Play(Pelco.SDK.kREV_2X);
If the camera associated with the stream has an associated recorder (NVR/NSM)
with recorded video, the stream starts playing in reverse at two times normal
speed. If the associated recorder does not contain recorded video, there is no
playback stream. This causes an exception of type Pelco.SDK.Exception() to
occur providing the following error code and message:
• Error code: NoRecordingFound
• Error message: "No recording found on NVR or failed to connect"
The error occurs when the Play() method is called. Following the error, the next
call of the Play() method jumps the stream to the dateTime that was previously set
by Seek(dateTime).
2. Playback of a stream can be jumped to a specific date, or time, by calling the
Seek() method with a System.DateTime. The following example creates a
dateTime that is 24-hours in the past and calls Seek on the Stream.
// Seek the stream to yesterday

DateTime yesterday = dateTime.UtcNow.AddDays(-1);
_stream.Seek(yesterday);
The stream is automatically put into a paused state following the _stream.Seek
call.
NOTE: The stream can restart by calling Play with a desired direction and
speed, for example, kFWD_1X or kREV_1X for forward or reverse respectively,
at standard speed (1X). If the 'DateTime yesterday' location does not contain
recorded video, there is no playback stream. This causes an exception as
explained in the previous step.
Playing a Stream Forward

A Stream can be played forward or in reverse. Use the Play() method with a
positive value to play a Stream forward.
Use Play() with a positive value to play a Stream forward. Positive value speed
constants contain kFWD indicating forward direction.
// Play the stream forward at 1x (standard speed)

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

There are predefined speed value constants for typical use described in the
following table. Their use is demonstrated in the above examples.
28 C5617M-H
Table 4: Forward stream speed constants
Speed constant Value Resultant speed

(forward direction)
kFWD_QUARTER 0.25 0.25x standard speed
kFWD_HALF 0.50 0.50x standard speed
kFWD_1X 1.0 1x standard speed =
standard speed
kFWD_2X 2.0 2x standard speed
Playing a Stream in Reverse

A Stream can be played forward or in reverse. This section describes how to play it in
reverse.
Use the method Play with a negative value to play a Stream in reverse. Negative
value speed constants contain kREV indicating reverse direction.
// Play the stream in reverse at 2x (two times standard speed)

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

There are predefined speed value constants for typical use described in the
following table. Their use is demonstrated in the above examples. Note that a
negative value results in reverse stream direction.
Table 5: Reverse stream speed constants

(reverse direction)
kREV_QUARTER -0.25 0.25x standard speed
kREV_HALF -0.50 0.50x standard speed
kREV_1X -1.0 1x standard speed =
standard speed
kREV_2X -2.0 2x standard speed
C5617M-H 29

(reverse direction)
Pausing a Stream
Use the Pause() method to pause a stream.
// Pause the stream

_stream.Pause();
NOTE: When a stream is paused, it switches to playback automatically. Calling

Play(Pelco.SDK.kFWD_1X) continues playing the playback stream forward at
standard speed. If the stream was paused in reverse direction playback, calling
Play(Pelco.SDK.kREV_1X) continues playing the playback stream in reverse at
standard speed.
Resuming Playback of a Paused Stream

Use the Stream.Play() method to resume playback of a paused stream.
Use the Play() method to resume playback of a stream.
// Play the stream forward at 1x standard speed

// Play the stream in reverse at 2x standard speed

NOTE: Playback of a stream can be in reverse using

_stream.Play(Pelco.SDK.kREV_2X) for two times standard speed. Speed
constants containing kFWD play the stream forward whereas speed constants
containing kREV play the stream in reverse. Refer to the sections Play a Stream
Forward and Play a Stream in Reverse for forward and reverse speed constant
definitions.
Switching From Playback to Live

When a Stream is in playback mode, either by calling Seek to a time in the past or by
calling the Pause() method, the Stream can be returned to live mode by calling the
GotoLive() method.
Use the GotoLive() method to return to live mode.
// Return the stream to live mode

_stream.GotoLive();
Stepping Through a Video Stream

Step through the video stream one frame at a time by calling the FrameForward() or
FrameReverse() method.
1. To step forward one frame:
// Step forward one frame
30 C5617M-H
_stream.FrameForward();
2. To step back one frame:
// Step back one frame

_stream.FrameReverse();
Taking a Snapshot
This section describes how to capture a snapshot of a single frame of video.
Use the Snapshot() method to take a snapshot of a single frame of video.
// Create a snapshot of a single frame of video

_stream.Snapshot(fileName);
NOTE: The Snapshot() method call requires a fully qualified path and file name
for saving the snapshot.
Setting the Stream Volume

Use the Stream.SetVolume() method to set the volume of a stream.
Use the SetVolume() method to provide a volume level.
// Set the audio volume of a stream; in this case, it is set to 10.

_stream.SetVolume(10);
NOTE: The valid levels for volume are "0" to "100"; the higher the number, the
higher the volume.
Table 6: Stream volume level values
Value Description
0 Mute
1-100 Low volume (1); high volume (100); any
level in between
Getting the Stream State

This section describes how to identify the current state of a stream.
Knowing the current state of a stream before performing an action can be helpful.
Use the following call to identify the current stream state.
// Get the state of the stream

PelcoSDK::STREAM_STATE GetState()
The stream state value returned can be "0", "1", "2" or "3." These values are
defined in the following table.
Table 7: Stream state values
Value Stream state

0 Stopped
1 Forward
C5617M-H 31
Value Stream state

2 Reverse
3 Paused
Getting the Stream Mode

Stream Mode returns a value that identifies whether the stream is in live mode or
playback mode.
Knowing the current mode of a stream before performing an action can be helpful.
Use the following call to identify the current stream mode.
// Get the mode of the stream

PelcoSDK::STREAM_STATE GetMode()
The stream state value returned can be "0", "1", "2" or "3." These values are
defined in the following table.
Table 8: Stream mode values
Value Stream mode

0 Unknown
1 Live; the live stream is active and
displayed
2 Playback Seek; all streams (live and
playback) are paused, the Seek()
method was invoked and when Play() is
called, the stream is in playback mode
3 Playback; the playback stream is active
and displayed
Using a Timestamp Event

The Pelco SDK supports timestamps. You might want to use a timestamp, for
example, if you were implementing a track bar for a video recorder application. You
could give the user the ability to traverse the video clip and return a frame based on
its timestamp.
In .NET, a timestamp is a .NET event. It returns a timestamp, as a DateTime, every
time a new timestamp is processed in the video stream. In C++, you get a timestamp
by subscribing (and unsubscribing) to the timestamp on a Stream object.
Timestamps are measured ticks where ticks are int_64 integers that represent the
number of 0.1-microsecond-intervals that have elapsed since AD 1. A timestamp
event occurs every time a new timestamp is processed in the video stream.
To get timestamps you perform these steps:
1. Register your timestamp handler to be notified of timestamp events (in C#) or
subscribe to timestamp callbacks (in C++).
2. Write a handler to perform the desired action when a timestamp is received.
3. Unregister the timestamp handler when done or unsubscribe.
In the following examples, assume that you have a Pelco.SDK.Stream called
"stream".
Register a Timestamp
32 C5617M-H
In C#, to get timestamps, you register a timestamp handler:
// Register the timestamp event.

stream.Timestamp += TimestampHandler;
In C++, to get timestamps, you subscribe for timestamp callbacks:
//Subscribe
stream.SubscribeTimestamp( < &handler );
Write a Timestamp Handler in C#

Write a timestamp handler to get the timestamp. In the following C# example, the
handler gets the timestamp, a .NET DateTime, converts it to the local time of the
machine running the SDK and in a format that is suitable for display.
private void TimestampHandler( DateTime timestamp )

{
BeginInvoke( (MethodInvoker) delegate
{
lblTimestamp.Text = timestamp.ToLocalTime().ToString();
} );
}
Write a Timestamp Handler in C++

Write a timestamp handler to get the timestamp. In the following C++ example, the
handler is derived from ITimestampDelegate, timestampTicks is an int64, and Notify
is the callback.
class ITimestampDelegate
{
public:
virtual ~ITimestampDelegate()
{
}
virtual void Notify(const __int64 timestampTicks) = 0;
};
Unregister a Timestamp
In C#, to stop receiving timestamps:
// Unregister a timestamp handler.

stream.Timestamp -= TimestampHandler;
In C++, to stop receiving timestamps:
//Unsubscribe
stream.UnsubscribeTimestamp();
Working With Stream Configurations
C5617M-H 33
The SDK uses a set of defaults for the Stream class which should work for most
situations. However, you can use the Stream Configuration class to change these
defaults. To do so, you can request StreamConfiguration information from a Stream
object, create a new StreamConfiguration object, or modify an existing one.
The default values for streams are as follows:
Video format Auto. The system chooses the preferred type of

video format. For SM5200 systems, default is
MPEG4/H264 but can be changed to MJPEG.
Pelco Aggregation systems support MJPEG only.
SM5000, Digital Sentry and DX 47/4800 Series
support MPEG4/H264 only.
Stream protocol RTP. However, video format takes precedence. If
the video format is MJPEG, the Stream protocol
is HTTP. If the video format is MPEG4/H264, the
Stream protocol is RTP.
Frame rate 1.0f. Frame rate at which Stream is delivered, which
can be between 1.0f and 30.0f. If video format is
MPEG4/H264, frame rate is ignored.
Delivery mode Auto. The system chooses the most appropriate
mode. In most cases, this is multicast. Applies to
RTP and RTPS streams. Ignored for HTTP and
MJPEG.
StreamAudio True. If true, default is to include audio with video
if it is available. False excludes audio from stream.
Ignored for MJPEG.
NOTE: See the StreamTypes.h file for Stream constant values.
Constructing a New Stream Configuration

In this example, the software connects to an SM5200 system. By default, a SM5200
system Stream object uses StreamFormatMPEG4h264. To display the stream as
MJPEG, create a new instance of StreamConfiguration and change the VideoFormat
field. This change causes the object to become properly configured internally for
MJPEG automatically.
1. Retrieve a camera, and create a Stream from the camera.
// Retrieve the camera.

Pelco.SDK.Camera camera = GetCameraByModel("IX10DN");
// Retrieve the display.

Pelco.SDK.Display display = new
Pelco.SDK.Display((MSSys.IntPtr)videoPanel.Handle);
// Retrieve the stream.

Pelco.SDK.Stream stream = new Pelco.SDK.Stream(camera);
2. Create a new StreamConfiguration object and change the configuration to

MJPEG.
// Create a new StreamConfiguration object.

StreamConfiguration sc = new StreamConfiguration();
// Set VideoFormat of the new configuration to be MJPEG.

sc.videoFormat = StreamVideoFormat.StreamFormatMJPEG;
34 C5617M-H
// Set the camera stream to the new configuration.

stream.StreamConfig = sc;
3. Bind the stream to the display and play it.
// Use Show to bind the stream.

display.Show(stream);
// Play the stream.

stream.Play(kFWD_1X);
Changing a Stream Configuration

To change a current Stream's StreamConfiguration, retrieve and change the
StreamConfig property.
1. Retrieve a system, look up a camera, and create a Stream from the camera.
// Retrieve a system.
System system = new System("admin:admin@pelcosystem://10.11.12.13");
// Get a camera through whatever means available.

Camera camera = GetCamera(system);
// Create the stream from the camera.

Stream stream = new Pelco.SDK.Stream(camera);
2. Get the current stream configuration and change it as necessary.
StreamConfiguration streamConfig = stream.StreamConfig;
// If the video format is not already MJPEG, set it to be MJPEG in the Stream
instance.
if (streamVideoFormat.StreamFormatMJPEG != streamConfig.videoFormat)
{
streamConfig.videoFormat = StreamVideoFormat.StreamFormatMJPEG;
stream.StreamConfig = streamConfig;
}
3. Use the stream as you would any other Stream object.
// Play the stream

stream.Play(1.0f);
NOTE: There are three possible video format types, one for motion JPEG (MJPEG),
one for MPEG4 or H.264, and a system default. See example below:
public enum class StreamVideoFormat

{
StreamFormatAuto = 0, // choose default for system
StreamFormatMJPEG = 1, // Motion JPEG
StreamFormatMPEG4h264 = 2, // MPEG4 or H264, Pelco API based stream.
};
C5617M-H 35
Exporting Video with Clip and Exporter
Classes
Exporting Video with Clip and Exporter Classes

Clip and Exporter Classes
The Clip and Exporter classes of the Pelco SDK Object Model make it easy to export
video from a camera to disk. You can create a clip and export it using the two classes
and just a few methods.
NOTE: Currently, the Clip and Exporter classes can only be used with Pelco
Aggregation systems. To export video from Endura systems, use the Exporter
component described in Exporting Video on Endura Systems.
Currently, video clips can be exported only in PEF format. Audio is not supported at
this time.
Clip Class
The Clip class represents the excerpt of recorded video to export. The following
methods of the Clip class allow you to retrieve information about an existing clip.
GetCameraID Retrieves the camera ID of the camera

from which to export video. For example,
"uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15".
GetStartTime Retrieves the start time of the recorded video Clip.
GetStopTime Retrieves the stop time of the recorded video Clip.
GetSystemID Retrieves the system-generated ID of the system
with the camera from which you are exporting the
video Clip.
IncludeAudio Retrieves whether audio should be included in the
video clip. Currently, audio is not supported.
Exporter Class
The Exporter class represents the export process. Exported video is in PEF format.
By default, it exports video without audio. In fact, currently, PEF is the only format
supported and audio is not supported.
The following methods of the Export class allow you to control the export process.
Start Begins the export process.

Stop Forces the active export process to stop.
SubscribeProgress Subscribes to the IExportStausDelegate event,
where the parameter is the callback to its event
handler.
SubscribeCompleted Subscribes to the IExportCompletedDelegate event,
handler.
SubscribeFailed Subscribes to the IExportFailedDelegate event,
handler.
Export Process Events

The Export process is asynchronous. To be informed of its progress, use the
following Exporter events:
• IExportCompletedDelgate
• IExportFailedDelgate
36 C5617M-H
Classes
• IExportStatusDelegate
Exporting Video
To export video from a camera, follow these steps:
1. Create a System instance that references an existing Pelco Aggregation system.
2. Query the System for available devices.
3. Select a camera.
4. Create a Clip object from the Camera.
5. Create an Exporter object that references the Clip.
6. Export the Clip.
NOTICE
This example creates a System using the pelcosystem:// provider because
it assumes that it is a normal Pelco Aggregation system. Typically, Pelco
Aggregation systems use the pelcosystem:// provider because it has the Pelco
SDK maintain its device collection.
You might think that you would use the pelcoaggregationdirect provider,
but that's not intended for general use. For details, see System Providers and
Schemes for more on the provider types.
Retrieve a Camera from the System

The following code example shows how to perform the first few steps required to
export video: Create the System instance, get the collection of devices connected to
the system, and select the camera from which to export video.
NOTE: The pelcosystem:// provider is used in the system constructor.
// Create an instance of existing Pelco Aggregation system called "MyAggSys"

PelcoSDK::System system( PelcoSDK::PString(
"admin:admin@pelcosystem://10.220.198.146?alias=MyAggSys") );
// Query the system for available cameras

PelcoSDK::DeviceCollection collection = system.GetDeviceCollection();
unsigned int numDevices = collection.GetCount();
bool found = false;

unsigned int index = 0;
for (index = 0; index<numDevices && found==false; index++ )
{
// Select a device from the list
PelcoSDK::Device device = collection.GetItem( index );
// Make sure this is a camera

if ( device.GetDeviceType() == CAMERA )
{
found = true;
}
}
Create a Video Clip and Export It

The following example generates a 15-second clip. It uses the PTime class to specify
the time span. The false parameter indicates that audio is not included. The
C5617M-H 37
Classes
example gets a camera from the system and creates a video clip from the camera,
then exports it with an Exporter object.
if ( found == true )
{
PelcoSDK::Camera camera = system.GetDeviceCollection().GetItem( index );
// Request time one hour ago, of a 15-second duration.

time_t tempStartTime = PelcoSDK::PTime::Now().GetUnixTime() - 3600;
PelcoSDK::PTime startTime( tempStartTime );
PelcoSDK::PTime endTime( tempStartTime + 15 );
PelcoSDK::Clip clip = PelcoSDK::Clip( camera, startTime, endTime, false );
PelcoSDK::Exporter exporter( PelcoSDK::PString( "c:\\clip.pef" ), clip );
exporter.Start();
}
38 C5617M-H
Exporting Video on Endura Systems

Exporting Video with the Exporter Component
Use the Exporter component to export video from Endura video management
systems. The Exporter is a Pelco SDK component that can export playback video,
and save it in either AVI, MP4, 3GP, MOV, PPX, or PEF format.
NOTE: To export video on Pelco Aggregation systems, you use the Exporter and
Clip objects. See Exporting Video on Pelco Aggregation Systems.
Exporter is multithreaded to help ensure good performance and to export as many
streams as possible at any given time. Moreover, users can export or playback saved
streams without having to initialize the stream. Consequently, Exporter provides
the flexibility to specify the camera, the start time and an end time value. You can
also embed metadata into streams. Embedding requires transcoding which affects
performance and authentication. When available, audio is included in the export in
either PEF or AVI format.
Exporter Sample Code
This topic uses sample C# and C++ code to illustrate how to perform exports.
Complete C# and C++ sample programs are contained in the subdirectory where the
Pelco SDK is installed Pelco\API\SampleCode\ExporterSample.
Custom Application Development

Using the Exporter, you can write a simple application 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.
Recoding 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 theWindows
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 generally uses MPEG-4 as well. No re-coding is necessary unless you
add overlays to the export. If the video stream coming from the camera is encoded
using H.264, the exported file can use H.264 or MPEG-4, depending on the container
format (3GP, AVI, MP4, PEF) and whether you add overlays to 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 complete
ISO MPEG-4 standard (or at least the ISO MPEG-4 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 does 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
C5617M-H 39
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.
NOTE: In release mode, you need to select the Enable unmanaged code
debugging check box in the project settings to view console output.
Create the EnduraExporter instance, and then call its Setup() method,
passing the following:
The location of the plugins The plugin directory contains components

directory. that are key to the SDK’s encoding, decoding,
and transcoding capabilities. Without a proper
reference, key features of the Pelco SDK could
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 For details on the importance of the System

address. Manager for the Exporter, refer to Video Exports
in the Appendix.
The IP Address to use for The client machine using the Pelco SDK.
receiving incoming streams
(Optional) The name of the
user that is performing the
export.
(Optional) The initial local NOTE: If you are running simultaneous exports,
port to use for the export. you must provide different port values.
(Optional) The end port to The exporter keeps increasing port numbers
use if initial port is in use. starting with the initial port number until the end
port is reached.
PelcoAPI::EnduraExporter exporter;
exporter.Setup("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins",
"10.220.196.187", "10.220.196.189", USERNAME, 8000, -1);
PelcoAPI.EnduraExporterNet pEnduraExporterNet = new

PelcoAPI.EnduraExporterNet();
40 C5617M-H
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 is in MPEG-4 format.
1. First decide on what type of overlay that you would like to create.
There are several types as defined in the EnduraExporterDefines header file:
enum OverlayType
{
OVERLAY_TYPE_TIMESTAMP = 0,
OVERLAY_TYPE_CAMERANAME = 1,
OVERLAY_TYPE_TEXTSTRING = 2,
OVERLAY_TYPE_PICTURE = 3
};
2. Next, create the overlay structure.

• If performing a single video clip export as described in Exporting A Single
Video Clip, the user must use the OverlayData() method for each desired
overlay type before starting the export.
exporter.OverlayData(PelcoAPI::OVERLAY_TYPE_TIMESTAMP,
PelcoAPI::OVERLAY_LOCATION_BOTTOM_LEFT, NULL, FONTNAME, 10,
fontColor, fontBgColor, 0);
pEnduraExporterNet.OverlayData(PelcoAPI.OverlayTypeNet.OVERLAY_TYPE_TIMESTAMP,
PelcoAPI.OverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT, "",
FONTNAME, 10, FONTCOLOR, FONTBGCOLOR, 0, DATEFORMAT,
TIMEFORMAT);
• If performing a stitched video clip export described in Stitching
Multiple Clips Into a Single Video Export, 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;
C5617M-H 41
// 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 can 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 The overlay does not appear on the screen.

top_left The overlay appears in the top left corner of the
screen.
top_middle The overlay appears in the top of the screen.
top_right The overlay appears in the top right corner of the
screen.
center The overlay appears in the center of the screen.
bottom_left The overlay appears in the bottom left corner of
the screen.
bottom_middle The overlay appears in the bottom of the screen.
bottom_right The overlay appears in the bottom right corner of
the screen.
coordinate This is a system reserved value.
42 C5617M-H
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 Name of an available font to use for displaying
overlays. (This does not apply to picture
overlays. )
fontSize Size of a font. (This does not apply to picture
overlays .)
fontColor Color of a font. (This does not apply to picture
overlays.)
fontBgColor Font’s color. (This does not apply to picture
overlays.)
pictureOpacity Opacity of the overlay. This ranges from
transparent (0% opacity) to solid (100% opacity).
(This is only relevant for picture overlays.)
dateFormat Format of date if this is a timestamp overlay.
enum DateFormat
{
DATE_FORMAT_MDYYYY = 0,
DATE_FORMAT_MDYY = 1,
DATE_FORMAT_MMDDYY = 2,
DATE_FORMAT_MMDDYYYY = 3,
DATE_FORMAT_YYMMDD = 4,
DATE_FORMAT_YYYY_MM_DD = 5,
DATE_FORMAT_DD_MM_YY = 6,
DATE_FORMAT_DMYY = 7,
DATE_FORMAT_DDMMYY = 8,
DATE_FORMAT_DMYYYY = 9,
DATE_FORMAT_DDMMYYYY = 10,
DATE_FORMAT_YYMD = 11,
DATE_FORMAT_YYYYMD = 12,
DATE_FORMAT_YYYYMMDD = 13,
DATE_FORMAT_YYYY_M_D = 14,
};
mdyyy This date format conforms to the following

structure: m/d/yyyy (month/day/year), where both
'm' and 'd' could be either one or two digits, for
example, 12/8/2001 or 2/23/2001
mdyy This date format conforms to the following
structure: m/d/yy (month/day/year), where both
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
C5617M-H 43
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
example, 23/2/01 or 8/12/01
ddmmyy This date format conforms to the following
structure: dd/mm/yy (day/month/year), for
example, 08/12/01 or 23/02/01
dmyyyy This date format conforms to the following
structure: d/m/yyyy (day/month/year), where both
example, 23/2/2001 or 8/12/2001
ddmmyyyy This date format conforms to the following
structure: dd/mm/yyyy (day/month/year), for
example, 21/03/2001
yymd This date format conforms to the following
structure: yy/m/d (year/month/day), where both
example, 54/1/31 or 73/12/1
yyyymd This date format conforms to the following
structure: yyyy/m/d (year/month/day), where both
example, 1954/1/31 or 1973/12/1
yyyymmdd This date format conforms to the following
structure: yyyy/mm/dd (year/month/day), for
example, 2001/02/23
yyyy_m_d This date format conforms to the following
structure: yyyy_m_d (year_month_day), where
both 'm' and 'd' could be either one or two digits,
for example, 1954-1-31 or 1973-12-1
timeFormat This is only relevant to the timestamp overlay.
enum TimeFormat
{
TIME_FORMAT_HHMMSSTT = 10,
TIME_FORMAT_HMMSSTT = 11,
TIME_FORMAT_HMMSS = 12,
TIME_FORMAT_HHMMSS = 13,
TIME_FORMAT_HMSTT = 14,
TIME_FORMAT_TTHMS = 15,
TIME_FORMAT_TTHHMMSS = 16,
TIME_FORMAT_HMS = 17,
};
44 C5617M-H
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
Resetting Overlay Data

To reset overlay data to default values for the video being exported, call the
ResetData() method.
bool bSuccess = exporter.ResetData();
Boolean bSuccess = pEnduraExporterNet.ResetData();
Exporting Video
This section describes various video export methods and scenarios.
Exporting a Single Video Clip
C5617M-H 45
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:
Path Path to resulting exported video, including file

name. Path format depends on whether this is a
Windows® or Linux® operating system.
UUID The UUID of the camera from which to export
video.
Codec video format The desired codec video stream format for the
exported file which can be CODEC_ID_MPEG1,
CODEC_ID_MPEG2, CODEC_ID_MJPEG,
CODEC_ID_MPEG4, CODEC_ID_H264 , or
none. Refer to 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
};
Start time The starting time of the recorded video to export

in UTC (GMT), not local time, using the format
yyyy-mm-ddThh:mm:ss.
End time The ending time of the recorded video to export
in UTC (GMT), not local time, using the format
yyyy-mm-ddThh:mm:ss.
videoOnly Set to true to export video only; set to false
to include audio (if it is available). If audio is
included, it is in either PEF or AVI format.
Audio source The UUID of the stream to export’s audio source,
if separate from the video source of the export.
bool bSuccess = exporter.StartExport("D:\\Video\\test123.avi",

"uuid:691fd745-006c-4fc9-9262-23c13e977ce4",
PelcoAPI::CODEC_ID_MPEG4,
"2010-01-11T22:10:35", "2010-01-11T22:11:15", false,
46 C5617M-H
"uuid:691fd745-006c-4fc9-9822-23c13e977ce4");
Boolean bSuccess =
exporter.StartExport("D:\\Video\\test123.avi",
"uuid:691fd745-006c-4fc9-9262-23c13e977ce4",
PelcoAPI::CODEC_ID_MPEG4,
"2010-01-11T22:10:35", "2010-01-11T22:11:15", false,
"uuid:691fd745-006c-4fc9-9822-23c13e977ce4");
5. Poll the status of the video export repeatedly, for example, once per second, until
it is finished. For more information, refer to 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; There is a system
with nine cameras, named “camera_x”, where “x” is the spelling of a number from
zero to eight. The files are to play in the following order. 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 the cameras play as follows. Camera_four from 9:20 to 9:30,
then camera_two, camera_six, and camera_seven from 9:30 to 9:45, assume that
camera_two’s video for 9:31-9:33 has been deleted, and that its video from 9:42 to
9:44 has been deleted. Finally, the last activity is to view camera_eight from 9:42 to
10:00. The following diagram illustrates the view flow.

3. Call the PlaylistExportInfo() method to set up the clip groups to be played
sequentially in the specified order.
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
C5617M-H 47
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 is also
included.
ClipGroup An integer representing the sequential order in
which to play video clips. Up to four clips can be
in the same clip group which plays in sync within
the export player.
PelcoAPI::PlaylistExportInfo playlistExportInfo[ NUM_CLIPS ];

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

playlistExportInfo.Add( new PelcoAPI.PlaylistExportInfoNet( CAMERA_1,
"", START_TIME_1, END_TIME_1, false, 1 ) );
exportFolder The path of the folder for exports. (The format

changes based on operating system.)
playlistName The name of the playlist. This should be a simple
name with no extensions
playlistExportInfo An array of playlist information for export.
exportInfoCount The number of export info entries
bool bSuccess = exporter.StartExport("D:\\Video\\test123",

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

“PlaylistName”, PlaylistExportInfo, exportInfoCount);
it is finished.
For more information, refer to Polling a Video Export.
Stitching Multiple Clips into a Single Video Export

NOTE: This stitching procedure is DEPRECATED. Stitched video clips do not play
correctly with Pelco Export Player. Please use Exporting Video Using a Playlist
(PPX).
NOTE: Enabling sequential stitching can be much slower than exporting a single
video clip, depending on whether any of the clips need to be transcoded.
There are occasions where you may need to export a single video from multiple video
clips.
48 C5617M-H
• First initialize as many video clip export settings (ExportInfo) instances as

you 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, four previously created OverlayInfo instances are
associated with two ExportInfo instances.
3. Optional: If you would like to overlay data onto the resulting export, do so now.
Refer to Setting Up Overlay Data on Video to Be Exported for details.
Path to exported video Including file name. The format changes based
on operating system, Windows® or Linux® .
Video format 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
};
ExportInfo array An array of the ExportInfo instances,

containing instances of OverlayInfo.
ExportInfo number The number of ExportInfo instances, one for
each clip to stitch.
Below is a stitched video export 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
C5617M-H 49
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);
PelcoAPI.ExportInfoNet exportInfo_0 = new

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

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

exportInfo_0.overlayInfo.Add(overlayInfo_0);
// add any other overlay settings here
exportInfo_1.overlayInfo = new ArrayList();
exportInfo_1.overlayInfo.Add(overlayInfo_0);
// add any other overlay settings here
ArrayList exportInfo = new ArrayList(2);
exportInfo.Add(exportInfo_0);
exportInfo.Add(exportInfo_1);
Boolean bSuccess = pEnduraExporterNet.StartExport("C:\\test456.avi",

PelcoAPI.VideoCodecTypeNet.CODEC_ID_MPEG4, exportInfo, 2);
it is finished.
For more information, refer to Polling a Video Export.
Polling a Video Export

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

)
{
int status = 0;
while( status < 100 && status != -1 )
50 C5617M-H
{
int temp = exporter.PollStatus();
if (temp != status)
{
status = temp;
TRACE_INFO("Polling status %d\n", status);
}
}
}
Int32 clipCounter = 0;
while (clipCounter < num_clips)
{
Int32 status = 0;
Int32 temp = 0;
while (status < 100 && status != -1)
{
temp = pEnduraExporterNet.PollStatus(60);
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.
bool bSuccess = exporter.StopExport();
Boolean bSuccess = exporter.StopExport();
Exporting A JPEG Snapshot

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

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

"uuid:00047D01-8994-5370-6563-747261495605", "NOW");
C5617M-H 51
The following is an example of a recorded snapshot.
bool bSuccess = exporter.ExportSnapshot("testSnapShot.jpeg",

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

"uuid:00047D01-8994-5370-6563-747261495605", "2011-11-07T19:30:00");
52 C5617M-H
Using Network Displays and Channels

What is a network display?
The Network Display class represents a network monitor that can be located
anywhere on the network but managed on the local computer that is running the SDK.
For example, a collection of network monitors can be used as a video wall, where
the monitors display video from several locations but are managed from a single
keyboard.
Displaying video from a remote location requires the combination of three classes:
Network Display Class Represents a network monitor that can be located

anywhere on the network but managed on the local
computer that is running the SDK.
Channel Class Represents the channel through which video
is transmitted from the camera to display in a
rectangular area of the network monitor. This could
be a single video channel displayed across the
entire monitor area, called the 1x1 layout or:
• Four video channels playing simultaneously, the
2x2 layout
• Nine video channels playing simultaneously, the
3x3 layout
• Sixteen video channels playing simultaneously,
the 4x4 layout
Camera Class Represents an individual camera that is taking the

video to display on a monitor.
The following figure shows how channels transmit video from a camera to a network
display.
Using the Network Display Class

To use a Network Display, you create a Network Display object, initialize a Camera
object, and bind it to a Channel object that will display the video data. It takes the
combination of these objects to start the flow of video to the Network Display.
Briefly, the process for using a Network Display entails:
1. Retrieving the Camera that you want to display.
2. Creating a Network Display to view the camera.
3. Retrieving a Channel from the collection of Network Display channels.
4. Binding the Camera to the Channel to view it.
C5617M-H 53
Specifically, these are the steps to perform to set up a Network Display window for
viewing video data and determine which camera to display.
1. Retrieve the Camera from the Device Collection by its UUID.
// Get a Camera from the DeviceCollection by its UUID

PelcoSDK::Camera cam = deviceColl.GetItemByKey(camUUID);
2. Create a Network Display to view the Camera.

A Network Display class represents a device on a network which can contain
channels that can display video data.
// Create a Network Display

PelcoSDK::NetworkDisplay* pNetworkDisplay = NULL;
// Retrieve the device collection.
PelcoSDK::DeviceCollection deviceCollection =
system->GetDeviceCollection();
deviceCollection.Reset();
// Retrieve the first network display found
while (deviceCollection.MoveNext())
{
try
{
// Check if there is a network display. If not, create one.
if (NETWORK_DISPLAY == device.GetDeviceType())
{
pNetworkDisplay = new PelcoSDK::NetworkDisplay(device);
break;
}
}
catch (PelcoSDK::Exception x1)
{
REPORT_FAIL("NetworkDisplaySample failed to get Device\n");
}
}
3. Retrieve a channel from the Network Display's channel collection. Bind the camera
to the channel to view it. With the Camera, Network Display, and Channel Objects
created, all the pieces required to display the Camera on a Network Display
are present. The following example shows how to retrieve a channel and bind a
camera to it.
// Check if there is a Network Display from step 2

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

delete pNetworkDisplay;
pNetworkDisplay = NULL;
}
}
NOTE: You can get and set a camera number for the camera. However, Endura
systems allow multiple cameras to have the same camera number. Therefore, you
cannot count on a camera's number being unique. However, camera numbers are
unique in Pelco Aggregation systems because multiple cameras are prohibited
from having the same camera number.
TIP
Use Identify() to detect the active network display. Use GetLayout() to
determine how many channels are displaying video.
C5617M-H 55
Managing Systems with the
Administrator Class
Managing Systems with the Administrator Class

The Administrator Class
An Administrator class represents the administrator who has the credentials to access
the device cache database, which maintains information about all systems and
devices on your Pelco network. The administrator is a "super-user" whose credentials
supersede the admin credentials of all individual systems. This way, the administrator
can make changes to all systems contained in the system collection at once, without
having to know the credentials of any individual system.
With the Administrator class, you can:
• Change the administrator password
• Remove a system
• Remove all systems
NOTE: Even though the Administrator class is limited to performing the above
listed tasks, future versions of the Pelco SDK may expand the functionality of the
Administrator class.
Changing the Administrator Password

The first time you create the Administrator object you must specify the
default password, "admin". Then, you can change the default using the
ChangePasswordTo() method to whatever you prefer. Make sure that you
remember the password, though, because you must supply the existing password to
change it. Specifying the wrong password raises an exception.
The process to change a password is as follows:
1. Create an Administrator object using the current password. If this is the first time
an Administrator object is created, specify the default password, "admin".
// Create an Administrator object with the default password 'admin'

Pelco.SDK.Administrator admin = new Pelco.SDK.Administrator("admin");
2. Change the password.
// Change the Administrator password to the given newPassword

admin.ChangePasswordTo(newPassword);
3. Handle the exception. This is how the exception would appear in context.
private void ApplicationSetup(string newPassword) {

// Create a System object
Pelco.SDK.System system = new Pelco.SDK.System("admin:admin@pelcosystem://?
alias=SampleSystem");
try
{

}
catch (Pelco.SDK.Exception)
{
56 C5617M-H
Administrator Class
System.Console.WriteLine("Failed to create Administrator object with

default password. ApplicationSetup has already been run");
return;
}
}
Removing a System
Remove a system from the system collection using the RemoveSystem() method.
By removing the system, all the system's devices are removed as well. However,
if the device belongs to another system in the system collection, the device is not
deleted from the other system. In other words, a device is never entirely removed
from the system collection until all systems containing the device are removed.
Removing a system removes its entry from the device cache database, which is a
database that maintains the current status of all systems and devices in the system
collection. For details on the device cache database, refer to Device Cache.
Even though the Administrator class enables you to remove a system, it's expected
to be a rare occurrence. One case might be that you want to remove a Pelco Edge
system to create a new one.
WARNING
Perform this task with great caution. Removing a system removes all its devices.
1. Create an Administrator object with the current password. If the password hasn't
been changed, it is "admin".
// Create an Administrator object with the default password "admin".

NOTE: You can change the default password with the ChangePasswordTo()
method.
2. Retrieve the system you that want to remove. This example removes the first
system in the system collection. Note that removing a system removes all devices
related to the system as well.
//Locate the system to remove.

Pelco.SDK.System system = systemCollection.GetItem(0);
3. Remove the system from the system collection.
//Remove the system.

admin.RemoveSystem(system);
NOTE: Removing the system object using the RemoveSystem() method does
not remove the object immediately. It is removed after all references to the object
have been released.
Removing All Systems

You can remove all systems from a system collection using the
RemoveAllSystems() method. Removing all systems removes all entries in the
device cache database, completely emptying it. This database maintains the current
status of the systems and devices in the system collection. For more information on
the device cache database, see Device Cache.
C5617M-H 57
Administrator Class
You would rarely want to remove all systems except for, perhaps, in a test
environment where you want to wipe the database clean before reconfiguring the
systems.
WARNING
Perform this task with great caution. Removing all systems empties the device
cache database.
1. Create an Administrator object with the current password.
// Create an Administrator object with the given password

Pelco.SDK.Administrator admin = new Pelco.SDK.Administrator(password);
NOTE: You can change the default password with the ChangePasswordTo()
method.
2. Remove all systems from the system collection, emptying the database.
// Remove all Systems

admin.RemoveAllSystems();
Administrator Class Code Examples

The following C# code examples show how to use the methods of the Administrator
class.
The first example shows how to change the Administrator password. For simplicity,
the example creates a System object to change its password. In reality, the System
would already exist . A try/catch block throws an exception if the default password
has been changed already. Then it uses the ChangePasswordTo() method to
create an Administrator object using a new password.
private void ApplicationSetup(string newPassword)

{
// Create a System object
Pelco.SDK.System system = new Pelco.SDK.System("admin:admin@pelcosystem://?
alias=SampleSystem");
try
{

}
catch (Pelco.SDK.Exception)
{
System.Console.WriteLine("Failed to create Administrator object with
default password. The default password has already been changed.");
return;
}
}
58 C5617M-H
Administrator Class
In the following example, one system is removed from the system collection using
the RemoveSystem() method. Note that deleting a system deletes all devices
associated with the system as well.
public void AdminRemoveSystem(string password, Pelco.SDK.System systemToRemove)

{
// Create an Administrator with the given password
// Remove a specific System

admin.RemoveSystem(systemToRemove);
}
In the following example, all systems are removed using the RemoveAllSystems()
method.
public void AdminRemoveAllSystems(string password)

{
// Create an Administrator with the given password
// Remove all Systems

admin.RemoveAllSystems();
}
C5617M-H 59
Using Event Classes
Using Event Classes

SDK Event Classes
The Pelco SDK Object Model supports event handling with the following three Event
classes:
Event Type of event that you want to handle. Currently,

you can handle events that determine whether
a device is on line, whether a property value
has changed, and the current SDK state, for
example, whether the SDK has started or completed
collecting devices. For details on event types, refer
to Event Types.
EventListener The base class used to derive your event
listener. This is the callback that is called when
an event occurs. You need to implement the
"Handle"method. For details on handlers, refer to
Writing Event Handlers.
Events Static class that contains the Subscribe() and
Unsubscribe() methods for global events, such
as ET_SDK_STATE. For details on the Subscribe()
method, refer to Subscribing to Events.
NOTE:
Currently, Event classes handle a small set of events and they are only available from
C++ programs. Future versions of the Pelco SDK will expand event functionality. In
the meantime, continue to use the components, Event Manager and Event Arbiter
Library to handle alarms, diagnostics, video analytics, and motion detection. Refer to
Events and Alarms for details.
Event Types
An Event is a data type that contains information about state changes of systems,
devices, or the SDK itself. Events are fired when certain system actions occur on
your network systems and devices. For example, these common system activities
generate events:
ET_ONLINE When a device, such as a camera, online or offline

status has changed.
ET_PROPERTY_CHANGED When a device property has changed, for example,
a video format or a camera's name.
ET_SDK_STATE The SDK state changes, for example, when the
SDK finishes collecting information about all
available devices and systems in the system
collection. SDK states are considered "global"
events because they do not refer to a specific
system; rather they refer to events across all
systems.
ET_STREAM Lifetime and status events of streams.
The following code examines the event type (eventType) and sets a string value
(typeStr).
switch (eventType)
60 C5617M-H
Using Event Classes
{
case Event::ET_ONLINE:
typeStr = "Device is on line";
break;
case Event::ET_PROPERTY_CHANGED:
typeStr = "Property changed";
break;
case Event::ET_SDK_STATE:
typeStr = "SDK state";
case Event::ET_STREAM:
typeStr = "SDK state";
break;
}
The following code shows how a Handler might handle events:
switch (eventType)
{
case Event::ET_ONLINE:
HandleOnlineEvent(ev);
break;
case Event::ET_PROPERTY_CHANGED:
HandlePropertyEvent(ev);
break;
case Event::ET_SDK_STATE:
HandleSdkStateEvent(ev);
break;
case Event::ET_STREAM:
HandleStreamEvent(ev);
break;
}
SDK States
The Pelco SDK defines a set of SDK states that can occur as a result of specific SDK
actions, such as when the SDK process goes down. Most of these states apply to the
SDK system collection process. When the SDK starts up, if a device cache collection
does not exist, the SDK starts the process of collecting information about available
systems and devices from the network. The collected information is then stored in the
local device cache database. While the SDK is collecting the information, it can fire
events to notify the application.
Possible SDK states are as follows:
TERMINATING SDK process is terminating.

COLLECTION_STARTED SDK started system collection.
COLLECTION_COMPLETED SDK completed system collection.
COLLECTION_FAILED SDK failed to complete system collection.
SYSTEM_REMOVED SDK removed a system from the system collection.
Note that removing a system removes all devices
related to the system.
The following code shows how the StateChangedEvent() method can be used
where stateToReport is the SDK state that caused the event to be fired.
class StateChangedEvent : public Event

{
public:
enum State
{
C5617M-H 61
Using Event Classes
TERMINATING,
COLLECTION_STARTED,
COLLECTION_COMPLETED,
COLLECTION_FAILED,
SYSTEM_REMOVED,
COLLECTION_REMOVED = SYSTEM_REMOVED,
};
PSDK_API StateChangedEvent(State stateToReport, unsigned int systemId,

const char* extraInfoToReport = 0);
const State state;

const PString extraInfo;
Event* Clone() const

{
return new StateChangedEvent(*this);
}
};/*StateChangedEvent*/
General Steps to Handling Events

The steps to take to handle events using the Event objects are as follows:
1. Create a listener class derived from SystemEventListener (for system specific
events) or GlobalEventListener (for global events). This class needs to implement
the “Handle” method, which is the event callback. It will be called when the
event occurs. In the constructor, specify which event types you are interested in.
“Handle” will only be called for those events. Refer to Writing Event Handlers.
2. Subscribe() the event listener from (1) with a system (System::Subscribe) or with
the SDK (Events::Subscribe), depending of what type of listener it is.
3. When you are no longer interested in the events you subscribed to, call the
appropriate Unsubscribe() method (System or Events).
NOTE: You cannot subscribe to events from inside an event handler. The SDK
throws the exception, InvalidEventSubscription.
NOTE: Although it is not required, a best practice is to subscribe in your listener’s
constructor and unsubscribe in your listener’s destructor. This way, you can be sure
that the application does not have active subscriptions for an EventListener object
that no longer exists, which would cause a crash.
Subscribing and Unsubscribing to Events

You subscribe to the events that you want your application to listen for using the
Subscribe() method of a System object or a global static method in the Events
class. It returns a unique subscription number that you use later to Unsubscribe.
NOTE: Your application receives only those events that you subscribe to.
You have the option of two types of event listeners:
• Global, to listen for events across the entire system collection
• System, to listen for events on a specific system or the associated devices
Global Event Listeners Subscriptions
Here's an example of subscribing to a global event listener. This constructor
subscribes to global events, where the MyGlobalEventListener class is derived from
the base class, GlobalEventListener, and _subscription is the subscription.
NOTE: The only global event subscription available is SDK_STATE.
62 C5617M-H
Using Event Classes
This example includes code for an event handler, as described in Writing Event
Handlers. It also includes code for the Unsubscribe() method, which you should
use to unsubscribe to the event listener when done.
NOTE: It's important to unsubscribe to events to ensure that there are no active
subscriptions for an EventListener object that does not exist.
class MyGlobalEventListener : GlobalEventListener

{
public:
MyGlobalEventListener()
: GlobalEventListener()
{
_subscription = Events::Subscribe(this);
}
// event handler
virtual void Handle(const PelcoSDK::Event & ev)
{
HandleEvent(ev);
}
virtual ~MyGlobalEventListener()
{
// unsubscribe
Events::UnSubscribe(_subscription);
}
protected:
EventSubscription _subscription;
};
System Event Listeners Subscriptions

Here's an example of subscribing to an online event. This constructor subscribes to
the ET_ONLINE event from the specified system. Note that it uses GetMask to get
the ET_ONLINE event from the bit mask.
class OnlineEventListener : public SystemEventListener

{
public:
OnlineEventListener( PelcoSDK::System& system ) :

SystemEventListener( PelcoSDK::Event::GetMask( PelcoSDK::Event::ET_ONLINE) )
, _system( system )
{
_subscription = _system.Subscribe( this );
}
~OnlineEventListener()
{
_system.Unsubscribe( _subscription );
}
void Handle( const PelcoSDK::Event& ev )
{
// This is the callback for the online event
// We know this is an online event so we can safely cast it
PelcoSDK::OnlineEvent& onlineEvent = (PelcoSDK::OnlineEvent&) ev;
printf( "Device %s is %s\n", onlineEvent.GetDeviceUuid().c_str(),

onlineEvent.on ? "online" : "offline" );
}
C5617M-H 63
Using Event Classes
private:
PelcoSDK::System _system;
PelcoSDK::EventSubscription _subscription;
};
Removing a System With Active Event Listeners

You can remove a system while its event subscribers are active. They will silently
stop receiving events. Then when you destroy the event subscribers, unsubscribing
from the system that was removed will not cause any errors.
try
{
system.Remove();
}
CATCH_PELCO_SDK_EXCEPTION
Writing Event Handlers

To handle an event in your application, you add code to determine the type of event
that has fired, and then you specify what actions to perform when the event occurs.
For a description of the events that can be handled, refer to Event Types.
Handling an Event
Once the application determines the event type, the handler for the specific event is
called. The following code shows an example of handling an ET_ONLINE event.
NOTE: You must override the Handle() method. The event reference that is
passed is only valid during the call to Handle(). If you need to reference the event
afterward, make a copy using Event::Clone().
NOTE: Make sure that the Handle() method is succinct, as it is run on the SDK’s
event processing thread. If complex actions are required in response to an event, it is
best to have the handler record the event in application data and process the event
later, perhaps on a different thread.
The following example "Handle" is the callback for the ET_ONLINE event. It includes
the event subscription code for context.
class OnlineEventListener : public SystemEventListener

{
public:
OnlineEventListener( PelcoSDK::System& system ) :

SystemEventListener( PelcoSDK::Event::GetMask( PelcoSDK::Event::ET_ONLINE) )
, _system( system )
{
_subscription = _system.Subscribe( this );
}
~OnlineEventListener()
{
_system.Unsubscribe( _subscription );
}
void Handle( const PelcoSDK::Event& ev )
{
// This is the callback for the online event
64 C5617M-H
Using Event Classes
// We know this is an online event so we can safely cast it
PelcoSDK::OnlineEvent& onlineEvent = (PelcoSDK::OnlineEvent&) ev;
printf( "Device %s is %s\n", onlineEvent.GetDeviceUuid().c_str(),

onlineEvent.on ? "online" : "offline" );
}
private:
PelcoSDK::System _system;
PelcoSDK::EventSubscription _subscription;
};
C5617M-H 65
Events and Alarms
Events and Alarms

Event Arbiter and Event Manager
IMPORTANT
Prior to the introduction of the Pelco SDK Object Model, the Pelco SDK contained
the Event Arbiter Library and Event Manager components for handling events.
These components are described here. As of 3.4, the Pelco SDK added an
additional event handling mechanism that uses Event classes defined in the Object
Model. At this time, the Event classes do not replace the functionality of these
Event Arbiter and Event Manager components. The Event classes are used to
handle events specific to Object Model classes. For details, see Using Event
Classes for details.
Events and alarms are essentially XML formatted messages triggered by Pelco
products when some particular criteria is met. Specifically, Pelco products act as
event providers and send the events and alarms to their subscribers. In most cases,
event providers are web services while subscribers are software clients. For example,
if an IP camera’s MotionDetection service detects movement within a particular region
in the video frame, it can send an event to all of its subscribers such as a VMS.
The Pelco SDK provides you with two components for handling events: the Event
Arbiter Library and the Event Manager.
Event Categories
Events that you can listen for (subscribe to) are organized by categories. To
subscribe, you specify which event category (or categories) that you want to listen for.
Table 9: Event Categories
Event Category Description

Alarm Array Configuration Events related to the
AlarmArrayConfiguration web service.
These events are fired when a physical
alarm input on a device is triggered,
for example, when an alarm circuit
connected to a camera has been turned
on or off.
Diagnostic Reporting Events related to the Diagnostic
Reporting web service. These events
are fired when a hardware alarm on
a device is triggered, for example, a
temperature alarm or video loss alarm.
Motion Detection Events related to the MotionDetection
web service. These events are fired
when a motion alarm is triggered, for
example, when a camera started or
stopped detecting motion.
Video Analytics Events related to the VideoAnalytics web
service. These events are fired when a
video analytic alarm is triggered.
Relay Array Configuration Not available, no events are generated.
Listed for backward compatibility only.
66 C5617M-H
Events and Alarms
Event Manager versus Event Arbiter Library

Both Event Arbiter Library and Event Manager components allow you to subscribe
and unsubscribe to events; however, one is more robust while the other is easier
to use. The Event Arbiter Library is the primary component for dealing with events
and provides you with the most flexibility and control for handling events. The
Event Manager is designed to be simpler to use, but is also less flexible. The Event
Manager component sits on top of the Event Arbiter Library.
NOTE: As of Pelco SDK 3.4, a third event mechanism exists: Object Model Events.
For details, refer to Using Event Classes.
This table compares the two event components to help you determine which one to
use for a particular circumstance.
Table 10: Event Categories
Event Arbiter Event Manager

More complicated to use. Easier to use.
Provides you with more options and more Less flexible.
flexibility.
Does not require a System Manager Requires a System Manager network
network appliance. appliance.
Use to subscribe to a single device’s web Use to subscribe to system-wide events,
service using either an IP address or that is, to an event that is triggered from
UDN. any device on the system. You cannot
request events from specific devices
with the Event Manager.
Use to subscribe to all instances of a
particular web service. For example, you
can subscribe to all MotionDetection
web services for all devices with a single
request.
Sample Code
The C# and C++ code used here illustrate how to use events and alarms. You can
find complete C# and C++ sample programs in a folder where you installed the Pelco
SDK: Pelco\API\SampleCode\EventArbiterSample.
NOTE: As indicated, some code samples work only with an Endura VMS. For more
specific information on Endura, refer to the Appendix.
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
• Event Manager, visit http://pdn.pelco.com/content/event-manager-issues
NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com.
C5617M-H 67
Events and Alarms
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 without
modification.
Event Arbiter Library

The Event Arbiter Library allows you to either subscribe directly to a device’s web
service events or indirectly; so you can choose to subscribe to the particular web
service from all devices that the service.
Once a subscription is established, the software client waits for an event to fire. The
web service then directs the event to your software client through the Pelco SDK. The
Event Arbiter Library handles subscription renewals automatically, so you don't 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, you
specify the event category (or categories) that you want to handle. The categories are
as follows:
• Alarm Array Configuration events
• Diagnostic Reporting events
• Motion Detection events
• Video Analytics events
Environment SDK Consequence

System Manager is unavailable You can subscribe to a specific device's
web service, but you cannot subscribe to
all devices at once.
Not all event data is available.
System Manager is available and the You can subscribe to all devices at once
EventArbiter web service is active that provide a particular web service.
All event data is available and parsed.
System Manager is available but the You can subscribe to a specific device's
EventArbiter web service is NOT active web service, but you cannot subscribe to
all devices at once.
Event Manager
The Event Manager is a component for handling events designed to be a simpler
alternative to the Event Arbiter Library. The Event Manager provides another
abstraction on top of the Event Arbiter Library, thereby simplifying 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, you specify the event
category (or categories) that you want to handle. The categories are as follows:
• Alarm Array Configuration events
• Diagnostic Reporting events
• Motion Detection events
• Video Analytics events
68 C5617M-H
Events and Alarms
Environment SDK Consequence

System Manager is unavailable Does not apply -- the Event Manager
requires a System Manager.
System Manager is available and You can subscribe to all available web
EventArbiter web service is active services that are under a specified
category through the SM EventArbiter
web service with a single subscription.
System Manager is available and All event data is available and parsed.
EventArbiter web service is NOT active If the SM EventArbiter web service is
not active, however, or if you choose
not to use it, the EventManager library
automatically subscribes to each
individual device's web service in the
specified category, resulting in many
subscriptions.
General Steps To Handle Events

From a high level, here are the steps you perform to handle events:
1. Subscribe to the desired web service's events through the Event Arbiter Library or
the Event Manager.
2. Create the method to handle the event. Associate that method with the Event
Arbiter Library instance’s event handler.
3. Wait for an event to occur (or trigger an event to test), then handle it.
4. When no longer interested in receiving events (or when finished testing),
unsubscribe from the subscribed web service.
Creating an Event Agent

The main purpose of an EventAgent class is to handle any incoming events that
have been subscribed to by the Event Arbiter.
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.
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, the MyEventAgent
sample class demonstrates basic functionality for accessing event-related data.
#include "PelcoAPI/Trace.h"
#include "PelcoAPI/EventArbiterDefs.h"
#include "MyEventAgent.h"
//=======================================================
// Constructor
//=======================================================
MyEventAgent::MyEventAgent() : m_nCounter(0)
{
}
//=======================================================
// Destructor
C5617M-H 69
Events and Alarms
//=======================================================
MyEventAgent::~MyEventAgent()
{
}
//=======================================================
// NotifyEvent
//=======================================================
void MyEventAgent::NotifyEvent(const char * szResponse, const Event * pEvent)
{
TRACE_INFO("Notify EVENT %d: \n", ++m_nCounter);
// Record the event UDN

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

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

TRACE_INFO("\tUTC Time: %s\n", pEvent->m_strUtcEventTime.c_str());
// Record the event type

TRACE_INFO("\tType: %d\n", (int) pEvent->m_nType);
// Record the event friendly name

TRACE_INFO("\tFriendly Name: %s\n", pEvent-
>m_strDeviceFriendlyName.c_str());
// If the event is for the alarm array

if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION)
{
// Record the event's associated camera UDN
TRACE_INFO("\tAssociated Camera UDN: %s\n", pEvent-
>m_strAssociateCameraUdn.c_str());
for (size_t i = 0; i < pEvent ->m_alarmOrRelayInfo.size(); i++)
{
// Record the alarm identifier
TRACE_INFO("\tAlarm ID: %d\n", pEvent->m_alarmOrRelayInfo[i]-
>m_nId);
// Record the alarm severity

TRACE_INFO("\t\tSeverity: %d\n", pEvent->m_alarmOrRelayInfo[i]-
>m_nSeverity);
// Record whether the alarm was changed (m_bChanged is true or

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

false, depending on
// whether the alarm was on or off)
TRACE_INFO("\t\tState: %s\n", (pEvent->m_alarmOrRelayInfo[i]-
>m_bAlarmState ? "On" : "Off"));
}
}
// If the event is for the relay array
else if (pEvent->m_nType == PelcoAPI::EVENT_TYPE_RELAY_ARRAY_CONFIGURATION)
{
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size(); i++)
{
// Record the alarm identifier
TRACE_INFO("\tRelay ID: %d\n", pEvent->m_alarmOrRelayInfo[i]-
>m_nId);
70 C5617M-H
Events and Alarms
// Record whether the alarm was changed (m_bChanged is true or

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

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

TRACE_INFO("\tSeverity: %d\n", pEvent->m_nVideoAnalyticsSeverity);
}
TRACE_INFO("EVENT Details: \n%s\n", szResponse);

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

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

Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);
// Display the event time in UTC format

Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime);
// Display the event type

Console.Write("\tType: {0}\n", eventNet.m_nType);
// Display the event friendly name

Console.Write("\tFriendly Name: {0}\n", eventNet.m_sDeviceFriendlyName);
// If the event is for the alarm array

if (eventNet.m_nType == 1)
{
Console.Write("\tAssociated Camera UDN: {0}\n",
eventNet.m_sAssociateCameraUdn);
C5617M-H 71
Events and Alarms
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++)

{
// Display the alarm identifier
Console.Write("\tAlarm ID: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nId);
// Display the alarm severity

Console.Write("\t\tSeverity: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nSeverity);
// Display whether the alarm was on or off (m_bAlarmState is true or

false, depending on
Console.Write("\t\tState: {0}\n",
(eventNet.m_alarmOrRelayInfo[i].m_bAlarmState ? "On" : "Off"));
}
}
// If the event is for the relay array
else if (eventNet.m_nType == 2)
{
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0); i++)
{
// Display the alarm identifier

false, depending on
(eventNet.m_alarmOrRelayInfo[i].m_bAlarmState ? "On" : "Off"));
}
}
// If the event is for motion detection
{
false, depending on
Console.Write("\tAlarm State: {0}\n", (eventNet.m_bAlarmState ? "On" :
"Off"));
}
// If the event is for video analytics
{
false, depending on
"Off"));
// Display the alarm severity

Console.Write("\tSeverity: {0}\n",
eventNet.m_nVideoAnalyticsSeverity);
}
Console.Write("EVENT Details:\n{0}\n", sResponse);
}
}
Returning the Event Subscription URL

NOTE: The related source code for this entry can be found in main.cpp’s main
function (for C++), or Program.cs’s Main function (for C#), which belongs to the
System Manager Wrapper C++ and C# sample project.
72 C5617M-H
Events and Alarms
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 To retrieve a deviceUDN, cycle through the
Device Name (UDN) 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 Uniform Resource Name (URN) value found in
the web service’s corresponding WSDL file.
Attribute name of Pointer to the variable that holds the result.
SYS_UpnpEventSubUrl
PelcoAPI::xstring sEvntUrl;
bSuccess = sm.GetDeviceServiceAttribute(loginId,
"UUID:B11DBF247E984B9BB83B7E74497DE6CA",
"urn:schemas-pelco-com:service:MotionDetection:1",
"SYS_UpnpEventSubUrl", &sEvntUrl)
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.
An Event Manager requires that a System Manager exists on your network. To
initialize the event manager, you must have completed the steps outlined in the
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:
Network location and port The client machine where the Event Arbiter
number Library instance resides.
Event Agent Your implemented Event Agent to register.
System Manager’s IP Refer to Automatically Determining the System
address and port number Manager’s IP Address and Port Number for more
details.
C5617M-H 73
Events and Alarms
Boolean True to stop the EventArbiter library from

using the System Manager. False to start the
EventArbiter library using the System Manager.
MyEventAgent agent;
PelcoAPI::IEventManager * pEventManager = new PelcoAPI::EventManager(
"10.220.196.200", "9716", &agent, false, "10.220.196.187", "60001");
PelcoAPI.EventManagerNet pEventManager = new PelcoAPI.EventManagerNet(

"10.220.196.200", "9716", pAgent, false, "10.220.196.187", "60001");
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.
Follow these steps 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 now starts ‘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):
enum EventType
{
EVENT_TYPE_UNKNOW = 0x00000000,
EVENT_TYPE_ALARM_ARRAY_CONFIGURATION = 0x000000001,
EVENT_TYPE_RELAY_ARRAY_CONFIGURATION = 0x00000002,
EVENT_TYPE_MOTION_DETECTION = 0x00000004,
EVENT_TYPE_VIDEO_ANALYTICS = 0x00000008,
EVENT_TYPE_DIAGNOSTIC_REPORTING = 0x00000010,
EVENT_TYPE_MASK = 0x0000001F
};
enum REGISTER_EVENTS
{
ALARM_ARRAY_CONFIGURATION = 0x00000001,
RELAY_ARRAY_CONFIGURATION = 0x00000002,
MOTION_DETECTION = 0x00000004,
VIDEO_ANALYTICS = 0x00000008,
DIAGNOSTIC_REPORTING = 0x00000010
}
Alarm Array Configuration Events that are related to the

AlarmArrayConfiguration web service, such as
an alarm circuit connected to the camera has
been turned on or off.
74 C5617M-H
Events and Alarms
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.
Relay Array Configuration Not available. This web service generates
no events. The functionality is provided for
backward compatibility only.
NOTE: Refer to the EventArbiterDefs header file for the latest options. If the
request was successful, the method returns true; false otherwise.
bool ret = pEventManager->Start(PelcoAPI::EVENT_TYPE_MASK);
Boolean ret = pEventManager.Start(REGISTER_EVENTS.EVENT_TYPE_MASK);
NOTE: The Pelco SDK automatically handles subscription renewals.
Using the Event Manager to Unsubscribe from All Services

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 returns true, false otherwise. The following example unsubscribes
from all active event subscriptions at once.
bool ret = pEventManager->Stop();
Boolean ret = pEventManager.Stop();
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.
C5617M-H 75
Events and Alarms

Number for more details.
PelcoAPI::IEventArbiter * pEventArbiter = new

PelcoAPI::EventArbiter("10.220.196.187", "60001", true);
3. Set the Event Arbiter Library instance's network location and port number, using
the local host IP address and 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#

debugging checkbox in the project settings to view console output.
When a System Manager Is Available on Your Network

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.
MyEventAgentNet pAgent = new MyEventAgentNet();
System Manager’s IP Refer to Automatically Determining the System
address and port number 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);
When a System Manager Is NOT Available on Your Network

76 C5617M-H
Events and Alarms
System Manager's IP Use empty strings for parameters representing
address and port number the System Manager's IP address and port
number.
Boolean Set the last parameter to false to explicitly not
rely on the System Manager‘s EventArbiter
service.
PelcoAPI.EventArbiterNet pEventArbiter = new PelcoAPI.EventArbiterNet(

"10.220.196.200", "9716", pAgent, "", "", false);
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 returns the event subscription's unique ID which allows
users to unsubscribe the event subscription. If unsuccessful, the method returns
NULL.
const char * szSid_1 = pEventArbiter-

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

"http://10.220.196.184:80/event/AlarmArrayConfiguration-1”);
Using the Event Arbiter Library to Subscribe to a Device's Web Service

You can use the Event Arbiter Library to subscribe to a specific device’s particular
web service using the Event Subscription URL.
NOTE: This entry is ONLY relevant for users who use an Endura network,
specifically with an active System Manager and an enabled EventArbiter
service on the System Manager. The related source code for this entry
C5617M-H 77
Events and Alarms

2. Construct an event service ID.
It consists of the device’s Universal Device Number (UDN) and the web service’s
Uniform Resource Name (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.)
std::string strEventServiceId = "uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15/

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

urn:pelcocom:serviceId:VideoAnalytics-2";
3. Call the Event Arbiter Library instance's SubscribeToEvents() method

(SubscribeEvents in C#), passing the event service ID.
If the request was successful, the method returns the event subscription's unique
ID which allows users to unsubscribe the event subscription.
const char * szSid_1 = pEventArbiter-

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

NOTE: This entry is ONLY relevant for users who use an Endura network,
specifically with an active System Manager and an enabled EventArbiter
service on the System Manager. The related source code for this entry
If you want to subscribe to all devices that provide a specific web service such as
MotionDetection (or any other web service that has events), do the following:
2. Construct an event Uniform Resource Name (URN).
This 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).
std::string strEventUrn = "urn:schemas-pelco-com:service:MotionDetection:1";
String strEventUrn = "urn:schemas-pelco-com:service:MotionDetection:1";
3. Call the Event Arbiter wrapper instance's SubscribeToEvents() method

(SubscribeEvents in C#), passing the event URN.
If the request was successful, the method returns the event subscription's unique
ID which allows users to unsubscribe the event subscription.
78 C5617M-H
Events and Alarms
const char * szSid_1 = pEventArbiter->SubscribeToEvents(strEventUrn.c_str());
String strSid_2 = pEventArbiter.SubscribeEvents(strEventUrn);
Using the Event Arbiter Library to Unsubscribe from a Service

in EventArbiterSample.cpp’s main function (for C++) or
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 returns one (for C++) or true (for C#).
Otherwise it returns 0 (for C++) or false (for C#).
const char * szSid_1 = pEventArbiter->SubscribeToEvents(

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

"urn:schemas-pelco-com:service:MotionDetection:1");
// ... misc logic ...
Boolean ret = pEventArbiter.UnsubscribeEvents(strSid_1);
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. Note that if a System Manager is not on line, 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 process any incoming event notifications. Events are
represented by the Event struct as defined in the EventArbiterDefs header. (The
parameter encapsulates the raw event XML string data.)
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
C5617M-H 79
Events and Alarms
• The device’s friendly name
void MyEventAgent::NotifyEvent(const char * szResponse, const Event *

pEvent)
{
//... other logic ...
pEvent->m_strUdn.c_str();
pEvent->m_strServiceId.c_str();
pEvent->m_strUtcEventTime.c_str();
pEvent->m_nType;
pEvent->m_strDeviceFriendlyName.c_str();
Int32 nCounter = 0;
public void NotifyEvent(String sResponse, PelcoAPI.EventNet
eventNet)
{
Console.Write("\nNotify EVENT {0}:\n", ++nCounter);
Console.Write("\tUDN: {0}\n", eventNet.m_sUdn);
Console.Write("\tService ID: {0}\n", eventNet.m_sServiceId);
Console.Write("\tUTC Time: {0}\n", eventNet.m_sUtcTime);
Console.Write("\tType: {0}\n", eventNet.m_nType);
Console.Write("\tFriendly Name: {0}\n",
eventNet.m_sDeviceFriendlyName);
If the incoming event is an alarm from the AlarmArrayConfiguration web

service, it provides information about its associated camera as well as general
alarm data.
if (pEvent->m_nType ==
PelcoAPI::EVENT_TYPE_ALARM_ARRAY_CONFIGURATION)
{
//the camera associated to this event
pEvent->m_strAssociateCameraUdn.c_str();
for (size_t i = 0; i < pEvent->m_alarmOrRelayInfo.size();

i++)
{
//alarm ID
pEvent->m_alarmOrRelayInfo[i]->m_nId;
//alarm severity
pEvent->m_alarmOrRelayInfo[i]->m_nSeverity;
//the state of the alarm zero off one on
pEvent->m_alarmOrRelayInfo[i]->m_bState;
}
}
if (eventNet.m_nType == 1)
{
Console.Write("\tAssociated Camera UDN: {0}\n",
eventNet.m_sAssociateCameraUdn);
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
Console.Write("\t\tSeverity: {0}\n",
eventNet.m_alarmOrRelayInfo[i].m_nSeverity);
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
80 C5617M-H
Events and Alarms
The RelayArrayConfiguration web service does not generate events. The

functionality is provided for backwards compatibility only.
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;
}
}
{
for (Int32 i = 0; i < eventNet.m_alarmOrRelayInfo.GetLength(0);
i++)
{
(eventNet.m_alarmOrRelayInfo[i].m_bState ? "On" : "Off"));
}
}
If the incoming event is from the MotionDetection web service, it shows

whether the motion detection region is active or inactive.
PelcoAPI::EVENT_TYPE_MOTION_DETECTION)
{
pEvent->m_bAlarmState;
}
{
"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.
TRACE_INFO("EVENT Details: \n%s\n", szResponse);
Console.Write("EVENT Details:\n{0}\n", sResponse);
Polling Events
in EventArbiterSample.cpp's main function (for C++) or
C5617M-H 81
Events and Alarms
ManagedEventArbiterSample.cs's Main function (for C#), which belongs to the

Event Arbiter Library sample project. Note that if a System Manager is not online,
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.
pEventArbiter->RegisterEventAgent(NULL);
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))
// ...
82 C5617M-H
Viewing Video Streams with Pelco API
Viewer (Legacy)
Viewing Video Streams with Pelco API Viewer (Legacy)

Legacy Component
IMPORTANT
The Pelco API Viewer is a legacy component for displaying streams and
controlling playback. The SDK Object Model provides a simpler approach to
working with video streams. For details, see Viewing and Recording Video
Streams instead.
While the Pelco API Viewer provides a lot of flexibility, it requires more complicated
method calls and more set up before streaming can commence.
Pelco strongly encourages users of the Pelco API Viewer to migrate to the SDK
Object Model as soon as possible. The viewer will be deprecated in the future.
What is the Pelco API Viewer?

Use the Pelco API Viewer to display and control video streams. The Pelco API Viewer
is a 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.
Sample Code
You can find complete C# and C++ programs that show how to use the Pelco
APIViewer in the directory where the Pelco SDK is installed: \Pelco\API
\SampleCode\PelcoAPIViewerSample.
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. PelcoAPIMPFViewer contains two components:
PelcoAPIMPFViewerControl, a convenient, prebuilt control, or a managed version
of the PelcoAPIViewer library that enables the developer to control the video
stream programmatically. Both approaches are described below.
Using the PelcoAPIViewer Component
C5617M-H 83
Viewer (Legacy)
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);
2. If required, set the authentication credentials to log into the camera.

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

const String CAMERA_IP_ADDRESS = "10.220.196.179";
const int PORT_NUMBER = 80;
const int 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
AuthenticationCredentialsNet tmpAuthentication =
new AuthenticationCredentialsNet("admin", "admin_password",
PelcoAPI.AuthenticationSchemeTypeNet.Basic);
_pViewer.SetAuthenticationCredentials(tmpAuthentication);
}
NOTE: To manage the camera authentication and the users, use the Pelco Web
interface.
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 could 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)

{
try
{
this._pOpenFolder.ShowDialog(this);
84 C5617M-H
Viewer (Legacy)
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);
}
interface.
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*/) { }
}
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.
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.
C5617M-H 85
Viewer (Legacy)
The plug-in directory contains components that are key to the SDK’s encoding,
decoding, and transcoding capabilities. Without a proper reference, key features of
the Pelco SDK could not function properly. Please note that the plug-in directory is
dependent on where you installed the Pelco SDK.
function, which resides in the PelcoAPIViewer sample project.
_pViewer.SetPluginDir("C:\\Program Files\\Pelco\\API\\Libs\\Debug\\Plugins\\");


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

CAMERA_NUMBER))
{
PelcoAPI::AuthenticationCredentials authentication("admin", "admin_password",
PelcoAPI::AuthenticationCredentials::BASIC);
_pViewer.SetAuthenticationCredentials(&authentication);
}
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));
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.
86 C5617M-H
Viewer (Legacy)
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: YYYY-MM-DDTHH:MM:SS.
For play back of a live RTP stream, set the time to
the string "INFINITE".
szIpAddress Required. The IP address of the video stream
source device 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”, the
service ID must be set to 1.
C5617M-H 87
Viewer (Legacy)
szCameraServiceId The last number of the web service endpoint URL

of a camera. For example, if an endpoint URL ends
with “VideoOutput-4”, 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 enable low
bandwidth on the secondary stream. 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

function, which belongs to the PelcoAPIViewer sample project SampleConsole9.
When in debug mode, if the video playback is paused during program execution,
the RTCP messages are displayed in the console window. The messages provide
information about the RTCP packets.
Before being able to control a video stream, you must first open the stream, and
display it on 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
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: YYYY-MM-
DDTHH:MM:SS. For play back of a live RTP
stream, set the time to the string "INFINITE".
szIpAddress Required. The IP address of the video stream
source device 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.
88 C5617M-H
Viewer (Legacy)
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.
szServiceId The last number of the web service endpoint
URL. For example, when an endpoint URL ends
with “VideoOutput-4”, 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 connects 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, when an end point URL ends with
“VideoOutput-1”, the service ID must be set to 1.
ITimeStampDelegate Signals if you want the timestamp returned by
the API. If 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
C5617M-H 89
Viewer (Legacy)
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);
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 return a session ID, pszSesId, of the stream. This is
used throughout this document for tasks related to the Pelco API Viewer.
Opening, Playing, and Displaying an RTSP Stream

1. Initialize the Pelco API Viewer.
Refer to Initializing the Pelco API Viewer (C++) or Initializing the Pelco API Viewer
(C#) entry for details.
2. Start the video stream to display, by calling the StartStream() method, passing
Location The location of the RTSP stream.
User name The user name to use for authentication
(Optional)
Password The password to use for authentication
(Optional)
Boolean A boolean indicating whether or not the stream is
multicast
90 C5617M-H
Viewer (Legacy)
Timestamp 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 for example, setting up windows, and so on ...
//Live example:
pszSesId = _pViewer.StartStream(
"rtsp://10.220.196.169/?deviceid=uuid:d557efb9-3a2d-48a1-b2fa-b48231f62f15",
NULL, NULL,
false, &_pDelegate);
//Playback example:
pszSesId = _pViewer.StartStream(
"rtsp://10.221.224.35/?deviceid=uuid:01b766f9-9d87-4613-
a168-5e5d179d339d&starttime=2011-12-04T10:00:00&endtime=2011-12-04T11:00:00",
NULL, NULL,
false, &_pDelegate);
If successful, the method returns a session ID of the stream. Keep this in mind, as
this is 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:
Session ID The target video stream’s session ID. A

successful call to the StartStream() method
returns this value.
Playback speed A float value representing the desired playback
speed. Valid possible playback speeds can
range from 0-300, with zero representing a
paused state and one representing regular
playback speed. (Also, one 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:
C5617M-H 91
Viewer (Legacy)

returns this value.
Playback speed A float value representing the desired playback
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 might include multiple p-
frames), call the Pelco API Viewer instance’s PlayForward or PlayReverse()
method (as appropriate), passing in the following parameters:
Session ID The unique ID of the target video stream. A
returns this value.
Speed A float value representing the desired playback
range from -300 to 300, with speed higher than
one (regular playback speed). Slow motion is
supported where the speed is set at half-speed
(for example, -0.5 or 0.5).
Currently for RTP, PlayReverse only plays backward, and PlayForward only
plays forward, regardless of whether the speed parameter is negative or positive.
Therefore, call 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
92 C5617M-H
Viewer (Legacy)
WARNING
DO NOT pause live streams. Pausing a live stream could produce an
unpredictable result.
Opening, Playing, and Displaying an RTSP Stream entry.
To pause currently running video stream, call the Pelco API Viewer instance’s
Pause() method; passing in the 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:
ISession ID The target video stream’s session ID. A
successful call to the StartStream() method,
returns this value.

if(_pViewer.FrameForward(pszSesId) !=0 ){
}
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:
successful call to the StartStream() method,
returns this value.

if(_pViewer.FrameReverse(pszSesId) !=0 ){
}
Resuming the RTP or RTSP Stream from a Paused State
C5617M-H 93
Viewer (Legacy)
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

Opening, Playing, and 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 ){
}
Start Manual Recording of RTP Stream

Manual recording can only be done on a live RTP stream.
NOTE: The related source code for this entry can be found in the main.cpp
file’s main function, which belongs to the PelcoAPIViewer sample project
SampleConsole9.
To start manual recording of the RTP stream, call the Pelco API Viewer instance’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”, 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).
94 C5617M-H
Viewer (Legacy)
nvrId The NVR ID. For example, if an endpoint URL

ends with “VideoOutput-1”, the service ID is 1.
// Start a stream and obtain the session ID pszSesId

...
// Start manual recording, passing in the session ID 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, which belongs to the PelcoAPIViewer sample project
SampleConsole9.
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);
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 zero to 100, with zero 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
C5617M-H 95
Viewer (Legacy)
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 appears.
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
PelcoAPI::ViewerOverlayInfo overlay;
PelcoAPI::COLOR fontColor = {0xFF, 0xFF, 0xFF, 0xA0};
PelcoAPI::COLOR fontBgColor = {0x00, 0x00, 0x00, 0x00};
overlay.m_dateFormat = PelcoAPI::VIEWER_DATE_FORMAT_MMDDYY;
overlay.m_timeFormat = PelcoAPI::VIEWER_TIME_FORMAT_TTHHMMSS;
overlay.m_fontColor = fontColor;
overlay.m_fontBgColor = fontBgColor;
overlay.m_location = PelcoAPI::VIEWER_OVERLAY_LOCATION_TOP_LEFT;
overlay.m_nFontSize = 12;
overlay.m_fontNameStr = "Arial";
bool bSuccess = _pViewer.DisplayTimestampOverlay(pszSesId, true, &overlay);
System.Drawing.Color fontColor = System.Drawing.Color.FromArgb(0xFF, 0xFF,

0xFF, 0xA0);
System.Drawing.Color fontBgColor = System.Drawing.Color.FromArgb(0x00, 0x00,
0x00, 0x00);
ViewerOverlayInfoNet overlay = new ViewerOverlayInfoNet();
overlay.m_location =
PelcoAPI.ViewerOverlayLocationNet.OVERLAY_LOCATION_BOTTOM_LEFT;
overlay.m_dateFormat = PelcoAPI.ViewerDateFormatNet.DATE_FORMAT_MMDDYYYY;
overlay.m_timeFormat = PelcoAPI.ViewerTimeFormatNet.TIME_FORMAT_HHMMSSTT;
overlay.m_fontNameStr = "Arial";
overlay.m_nFontSize = 16;
overlay.m_fontColor = fontColor;
overlay.m_fontBgColor = fontBgColor;
Boolean bSuccess = _rtpViewer.DisplayTimestampOverlay(_rtpSessionId, true,
overlay);
96 C5617M-H
Viewer (Legacy)
NOTE: Live and playback RTSP streams from Sarix ® cameras are unable to display
timestamp information.
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 Live Video Streaming (RTP)
Cameras with PTZ functionality can also be controlled using the Stream class and
Pelco API Viewer. For more information, refer to Pan, Tilt, Zoom (PTZ) Control.
NOTE: Pan, Tilt, Zoom (PTZ) Control is for controlling active cameras so it applies to
live RTP video streams only.
C5617M-H 97
Pan, Tilt, Zoom (PTZ) Control

What is PTZ Control?
After you’ve found the IP camera on your network and displayed its live stream on
your display, you 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.
To do so, you can use the PTZ Control Wrapper component described here.
Sample Code
You can find complete C# and C++ programs that show how to use the PTZControl
in the directory where the Pelco SDK is installed: Pelco\API\SampleCode
\PTZControlWrapperSample.
Where Does the Pelco SDK Fit?
To move your IP camera’s current view, you need to start using the Pelco SDK’s
PTZ Control Wrapper. The PTZ Control Wrapper is an easy to use tool for controlling
various PTZ and lens related functionality. Here, we’ll how to focus on panning and
tilting the camera.
The PTZ control functionality is also available as part of the PelcoAPIViewer.
PTZ Control Sample Code
You can find complete C# and C++ programs that show how to use the PTZControl
in the directory where the Pelco SDK is installed: Pelco\API\SampleCode
\PTZControlWrapperSample.
Initializing the PTZ Control Wrapper

function (for C++) or Program.cs’s Main function (for C#), which belongs to the PTZ
Control Wrapper sample project.
NOTE: In release mode, select the Enable unmanaged code debugging check box
in the project settings to view console output.
To create an instance of the managed PTZ Control Wrapper, specify the following
parameters:
• Your IP camera’s current IP address
• Your IP camera’s port number
• Your IP camera’s service ID (usually one unless this number represents a channel
in a multichannel encoder)
C++ Example
PelcoAPI::PTZControlWrapper ptzControlWrapper("10.220.196.144”, 49152, 1);
Verify that authentication is enabled for the camera, and if so, set the authentication
credentials. 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",
ptzControlWrapper.SetAuthenticationCredentials(&credentials);
98 C5617M-H
interface.
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);
Verify that 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))
{
PelcoAPI::AuthenticationCredentials authentication("admin", "admin_password",
managedPTZControl.SetAuthenticationCredentials(&authentication);
}
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
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.
C5617M-H 99
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.
//panning left
bool bSuccess = ptzControlWrapper.ContinuousPan(-10000);
//panning right
bool bSuccess = ptzControlWrapper.ContinuousPan(10000);
//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
zero to the ContinuousPan method as shown in the following example.
bool bSuccess = ptzControlWrapper.ContinuousPan(0);
Boolean bSuccess = managedPTZControl.ContinuousPan(0);
Continuous Tilting
Control Wrapper C++ sample project.
PelcoAPIViewer API.
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 reference documentation.
//tilting down
bool bSuccess = ptzControlWrapper.ContinuousTilt(-9000);
100 C5617M-H
//tilting up
bool bSuccess = ptzControlWrapper.ContinuousTilt(9000);
//tilting down
Boolean bSuccess = managedPTZControl.ContinuousTilt(-9000);
//tilting up
Boolean bSuccess = managedPTZControl.ContinuousTilt(9000);
StopContinuous() method (refer to Continuous Stop for details), or pass zero
to the ContinuousTilt method as shown in the following example.
bool bSuccess = ptzControlWrapper.ContinuousTilt(0);
Boolean bSuccess = managedPTZControl.ContinuousTilt(0);
Continuous Diagonal Movement

Control Wrapper C++ sample project.
PelcoAPIViewer API.
This entry covers the portion of the sample project that deals with continuously
moving the camera in a diagonal manner.
2. Call the ContinuousMove method.
The first parameter represents both speed and direction on the X plane. Use
a negative integer to pan left and 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.
//tilting down
bool bSuccess = ptzControlWrapper.ContinuousMove(10000, -10000);
//tilting up
bool bSuccess = ptzControlWrapper.ContinuousMove(10000, 10000);
//tilting down
Boolean bSuccess = managedPTZControl.ContinuousMove(10000, -10000);
//tilting up
Boolean bSuccess = managedPTZControl.ContinuousMove(10000, 10000);
C5617M-H 101
StopContinuous() method (refer to Continuous Stop for details), or pass in a 0
value to the ContinuousMove method as shown in the following example.
bool bSuccess = ptzControlWrapper.ContinuousMove(0,0);
Boolean bSuccess = managedPTZControl.ContinuousMove(0,0);
Stopping Continuous Movement

The StopContinuous method is available to stop the camera from continually
moving, while the Stop call is available to stop Lens control (zoom, iris, and focus)
actions. To stop continuous positioning calls, pass in a zero value. For example, after
executing ContinuousMove, call ContinuousMove(0, 0) to stop moving.
To stop the camera from continually moving, call the StopContinuous method.
bool bSuccess = ptzControlWrapper.StopContinuous();
Boolean bSuccess = managedPTZControl.StopContinuous();
Enabling Continuous Pan/Tilt/Move and Zoom APIs by UDP Instead of TCP

Call the PTZ Control Wrapper's SetLowLatencyMode method, passing in true as
an argument. This sends the subsequent ContinuousMove, ContinuousTilt,
ContinuousPan, StopContinuous and Zoom calls using UDP.
bool bSuccess = ptzControlWrapper.SetLowLatencyMode(true);
Boolean bSuccess = managedPTZControl.SetLowLatencyMode(true);
Zoom API calls over UDP currently work on Sarix® firmware 1.7.41 and higher.
Panning to a Specific Position

PelcoAPIViewer API.
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.
102 C5617M-H
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.
bool bSuccess = ptzControlWrapper.AbsolutePan(36000);
Boolean bSuccess = managedPTZControl.AbsolutePan(36000);
Tilting to a Specific Position

PelcoAPIViewer API.
degree).
2. Call the PTZ Control Wrapper’s AbsoluteTilt method, passing in the desired
position on the rotational X plane.
• Passing a negative value moves down from horizontal..
• Passing a positive value moves up from horizontal..
For more details on the AbsoluteTilt method, refer to the PTZ Control Wrapper
API reference documentation.
Generally, the tilting range is limited to 0 to -90 degrees (0 to -9000 centidegrees).
This limit might differ, depending on the type of camera used.
bool bSuccess = ptzControlWrapper.AbsoluteTilt(-9000);
Boolean bSuccess = managedPTZControl.AbsoluteTilt(-9000);
Moving to a Specific Position

PelcoAPIViewer API.
degree).
C5617M-H 103
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.
bool bSuccess = ptzControlWrapper.AbsoluteMove(20, 40);
Boolean bSuccess = managedPTZControl.AbsoluteMove(20, 40);
Moving to a Position Relative to the Current Location

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

PelcoAPIViewer API.
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
int positionX = 0;
int positionY = 0;
bool bSuccess = ptzControlWrapper.GetAbsolutePosition(&positionX, &positionY);
int positionX = 0;
int positionY = 0;
Boolean bSuccess = managedPTZControl.GetAbsolutePosition(ref positionX,
ref positionY);
104 C5617M-H
Managing the Magnification (Zoom) Value

PelcoAPIViewer API.
This section describes how to change the camera’s current magnification level.
Magnification refers to the camera’s zoom level, which in turn describes the focal
length for which the camera's lens is currently set. Zoom level is expressed as
100 times the level of magnification that you want. For example, 1x magnification
becomes 100, and 18x magnification becomes 1800.
To change the current magnification level, and to later retrieve the current
magnification value, do the following:
2. Call the PTZ Control Wrapper’s AbsoluteZoom method passing in the desired
zoom level.
If the request was successful, your camera’s magnification level should now
be changed. For more details on the AbsoluteZoom method, refer to the PTZ
bool bSuccess = ptzControlWrapper.AbsoluteZoom(150);
Boolean bSuccess = managedPTZControl.AbsoluteZoom(150);
3. Call the GetAbsoluteZoom method to return the camera’s current magnification

setting.
If the request was successful, your camera’s magnification level should be
returned. For more details on the GetAbsoluteZoom method, refer to the PTZ
int magnification = 0;
bool bSuccess = ptzControlWrapper.GetAbsoluteZoom(magnification);
int magnification = 0;
Boolean bSuccess = managedPTZControl.GetAbsoluteZoom(ref magnification);
Managing the Focus Value

PelcoAPIViewer API.
NOTE: It is best practice to let your IP camera manage focus automatically.
This portion of the documentation covers how to focus near the IP camera or focus
far away from the IP camera.
C5617M-H 105

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 in a 0). This does not stop until a SetFocus request is made
with a different value, or if you call the Stop method, which stops movement or
lens related action that the camera is currently doing.
bool bSuccess = ptzControlWrapper.SetFocus(1);

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.
bool bSuccess = ptzControlWrapper.AutoFocus(true);
Boolean bSuccess = managedPTZControl.AutoFocus(true);
Iris Control
PelcoAPIViewer API.
NOTE: It is best practice to let your IP camera manage its iris automatically.
This section demonstrates how to open and close your camera’s iris.
2. Call the SetIris method, passing in the desired iris command.
For a little background, the SetIris method takes only following values:
0 To stop all iris related operations.

1 To start closing the iris.
2 To start opening the iris.
If the request was successful, your camera’s iris should now be changing (unless
you passed in a 0). This does not stop until the SetIris request is made with
106 C5617M-H
a different value, or if you call the Stop method, which stops movement or lens
related action that the camera is currently doing.
bool bSuccess = ptzControlWrapper.SetIris(1);

bool bSuccess = ptzControlWrapper.SetIris(2);
Boolean bSuccess = managedPTZControl.Iris(1);

Boolean bSuccess = managedPTZControl.Iris(2);
3. Alternatively the recommended way of controlling the iris is to let your IP camera
manage it automatically. To enable this feature, call the AutoIris method and
pass a boolean value of true. To disable it, just pass a boolean value of false.
bool bSuccess = ptzControlWrapper.AutoIris(true)
Boolean bSuccess = managedPTZControl.AutoIris(true)
Scripting
One of Pelco’s most powerful features enables users to manage and run scripts.
Scripts allow you to extend the behavior of Pelco devices with little effort. Before
learning how to use the SDK’s scripting related features, it is important to know about
the different types of Pelco scripts:
Preset
A preset is a script that allows you to save a camera's stationary position, zoom, and
other settings such as auto iris and autofocus, 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 preconfigured 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
C5617M-H 107
A general script consists of a group of commands that run over a set period of time. It
is akin to a macro.
Creating a Preset
PelcoAPIViewer API.
These steps 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, it either creates a new one or
modifies an existing one by that name.
bool bSuccess = ptzControlWrapper.SetPreset("PRESET99");
Boolean bSuccess = managedPTZControl.SetPreset("PRESET99");
Updating an Existing Preset

To update an existing preset, just following the steps outlined in Creating a Preset,
ensuring that you use the name of the existing preset to modify as the parameter
for the SetPreset method.
Creating a Pattern
PelcoAPIViewer API.
This is just like creating a preset, except you are 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.
108 C5617M-H
Depending on whether the pattern already exists, it either creates a new one or
modifies an existing one by that name.
bool bSuccess = ptzControlWrapper.StartPatternRecording("PATTERN99");
Boolean bSuccess = managedPTZControl.StartPatternRecording("PATTERN99");
4. At this point start performing the actions that you’d want your camera to remember
as a pattern.
For example, if you have three points of interest you would first go to the first
point of interest 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.
bool bSuccess = ptzControlWrapper.EndPatternRecording("PATTERN99");
Boolean bSuccess = managedPTZControl.EndPatternRecording("PATTERN99");
Going to an Existing Preset

PelcoAPIViewer API.
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 moves to the preset and then stops.
bool bSuccess = ptzControlWrapper.GotoPreset("PRESET99");
Boolean bSuccess = managedPTZControl.GotoPreset("PRESET99");
Removing an Existing Preset

PelcoAPIViewer API.
To remove an existing preset, call the PTZ Control Wrapper’s RemovePreset
method, passing in the name of the preset.
C5617M-H 109
The preset is then deleted.
bool bSuccess = ptzControlWrapper.RemovePreset("PRESET99");
Boolean bSuccess = managedPTZControl.RemovePreset("PRESET99");
Updating an Existing Pattern

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

PelcoAPIViewer API.
To run a a script, call the PTZ Control Wrapper’s RunPattern method, passing in
the name of the script to run.
The script continues to run until stopped by the user using the HaltPattern
method, detailed Stopping a Pattern Currently Being Executed on page 110.
bool bSuccess = ptzControlWrapper.RunPattern("PATTERN99");
Boolean bSuccess = managedPTZControl.RunPattern("PATTERN99");
Stopping a Pattern Currently Being Executed

PelcoAPIViewer API.
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.
bool bSuccess = ptzControlWrapper.HaltPattern("PATTERN99");
Boolean bSuccess = managedPTZControl.HaltPattern("PATTERN99");
110 C5617M-H
Extracting Audio and Video Metadata

Processing Metadata
WARNING
modification.
WARNING
The content below assumes that the default target installation directory was
chosen during installation.
NOTE: For the latest Pelco documentation, visit http://pdn.pelco.com.

There are 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.
Motion Detection Metadata
C5617M-H 111
Motion detection involves computing the difference between two images. If the
difference between the compared images crosses a certain threshold value, 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;
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).
112 C5617M-H
• 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 1901.
• tv_wday -- The time interval in days since
Sunday (0-6).
• tv_yday -- The time interval in days since
January 1st (0-365).
• tv_isdst -- A boolean that is true if it is currently
daylight savings time, false otherwise.
typedef struct tm {
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
}
In addition to returning the data above, the Metadata Parser Library also returns the
daylight savings offset, the current timezone, and values in local time.
Getting Started
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.
\Pelco\API\Libs\Release.
What’s Ahead
This is a high level overview of possible tasks related to metadata:
1. Access the metadata from the stream.
2. Render metadata onto a video frame.
Initializing the Metadata Parser Class

function, which 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
C5617M-H 113
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 predrawing work.
virtual void BeginDraw() throw();

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

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

throw();
Retrieving the Current Timestamp Metadata

NOTE: The related source code for this entry can be found in main.cpp’s
ProcessTimestamp function, which belongs to the Metadata Parser C++ sample
project.
1. Initialize the MetaDataParser.
For details, refer to Initializing the Metadata Parser Class.
114 C5617M-H
2. Verify whether the parser has found a timestamp by calling the HasTimeStamp
method, which returns 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

ProcessMotionData function, which belongs to the Metadata Parser C++ sample
project.
1. Initialize the MetaDataParser. For details, refer to Initializing the Meta-Data Parser
Class.
2. Check if the parser has found motion detection data by calling the
HasMotionData method, which returns true if found, false otherwise.
if(true == parser.HasMotionData()){
3. If there is motion detection metadata, call the GetMotionData method and pull
the result into a new MotionData instance.
PelcoAPI::MotionData *data = parser.GetMotionData();
4. Parse the resulting data from the MotionData instance.
if(NULL != data){
unsigned int cols = data->Columns();
unsigned int rows = data->Rows();
unsigned char *mask = data->Bitmask();
// Do something with the data here
// Delete the motion data object
Rendering Motion Detection Metadata

ProcessMotionData function, which belongs to the Metadata Parser C++ sample
project.
NOTE: This entry assumes that the user has already completed the steps outlined in
Creating a Metadata Renderer Class.
1. Initialize the MetaDataParser. For details, refer to Initializing the Meta-Data
Parser 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()){
C5617M-H 115
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

ProcessDrawingData function, which belongs to the Metadata Parser C++ sample
project.
1. Initialize the MetaDataParser. For details, refer to Initializing the Meta-Data Parser
Class.
2. Determine if the parser has found drawing data by calling the HasDrawingData
method, which returns true if found, false otherwise.
if(true == parser.HasDrawingData()){
3. If drawing metadata is found, call the GetDrawingData method, pulling the result
into a DrawingData instance.
PelcoAPI::DrawingData *data = parser.GetDrawingData();
4. Parse the resulting data by iterating through the returned drawing primitives.
PelcoAPI::DrawingPrimitive *primitive = data->GetNextPrimitive();;

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

RenderDrawingData function, which belongs to the Metadata Parser C++ sample
project.
This entry assumes that the user has already completed the steps outlined in
Creating a Metadata Renderer Class.
116 C5617M-H
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();
C5617M-H 117
Web Service Proxies (Legacy)

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

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 use 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 is

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 holds your request parameters for the web service action
ResetConfiguration.
118 C5617M-H
6. Create a new web service action response instance. In the below

example, the software creates an instance of CameraConfiguration’s
ResetConfigurationResponse data type.
_CameraConfiguration__ResetConfigurationResponse * pResetConfigurationResponse
=
soap_new__CameraConfiguration__ResetConfigurationResponse(
&CameraConfiguration, -1);
This holds 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)
C5617M-H 119
Discovery (Legacy)
Discovery (Legacy)
Device and Service Discovery Overview
IMPORTANT
The System Manager Wrapper functionality described here has been replaced by
the Object Model introduced in the Pelco SDK 3.0. Prior to the introduction of the
Object Model, device and service discovery tasks were provided by this System
Manager Wrapper. Now discovery occurs when a System instance is created. The
device cache mechanism performs discovery. For details, see Device Cache.
Sample Code
You can find complete C# and C++ programs that show how to use the Pelco
System Wrapper under the directory 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 while reading this documentation.
NOTE: For more Endura specific information, refer to the Endura appendix.
Getting Started
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.
\Pelco\API\Libs\Release.
Next Steps
The following set of tasks are essential for using the Pelco SDK:
120 C5617M-H
Discovery (Legacy)
• 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

function (for C++) 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.
PelcoAPI::SystemManagerWrapper sm;
int nRet = sm.SetSMAddress((char *) sSMIPAddress);
PelcoAPI.SystemManagerWrapperNet sm = new PelcoAPI.SystemManagerWrapperNet();

int nRet = sm.SetSMAddress("192.168.1.1");
2. Log in to the System Manager with the proper credentials. Call the System
Manager Wrapper instance’s UserLogin() method, passing in the username
and password.
int loginId = sm.UserLogin("brian", "pelco");
Int32 loginId = sm.UserLogin("brian", "pelco");

If successful, this step should return an ID of your login session. Make a note
of this login ID, because it is used for many of the System Manager Wrapper’s
methods.
3. After you have logged in to System Manager, you will eventually have to log out.
When you 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.
sysMgr.UserLogout(loginId);
sm.UserLogout(loginId);
C5617M-H 121
Discovery (Legacy)
Automatically Determining the System Manager’s IP Address and Port Number

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

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
122 C5617M-H
Discovery (Legacy)
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. Refer to 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. Refer to 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 one larger than the one
before, for example, when the 1st call returns1, the subsequent call returns 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.
int seqNum = 0;
MyStorage storage; // ... You must define this class ...
sm.GetDevices(loginId, &seqNum, "Camera", &storage);
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
the IDeviceStorage class instance. Refer to 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.
int seqNum = 0;
C5617M-H 123
Discovery (Legacy)
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 ...
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

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
Your login ID This ID is returned after a successful login.

(Refer to Initializing the System Manager
SYS_CFG_TzInfo The time zone attribute’s ID.
sTimezoneInfo A pointer to your time zone variable.
PelcoAPI::xstring sTimezoneInfo;
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_TzInfo",
&sTimezoneInfo);

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

To your network’s network time server’s IP Address, do the following:
124 C5617M-H
Discovery (Legacy)
2. Call the System Manager Wrapper’s GetSystemAttribute method, passing in

the following parameters:

SYS_CFG_NtpAddr The network time server's attribute’s ID.
sNtpAddress A pointer to your NTP address variable.
PelcoAPI::xstring sNtpAddress;
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_NtpAddr",
&sNtpAddress);

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

NOTE: This entry assumes that you have already completed the steps outlined
in Querying Available Devices from the System Manager, which provides you with
UDNs for Pelco devices available on your network.
To determine your web service's ID, do the following:
2. Call the System Manager Wrapper’s GetServiceID() method, passing in the
following parameters:
The target device’s Unique To retrieve a deviceUDN, cycle through the
Device Name (UDN) value stored results of a GetDevices call within your
System Manager.
sServiceType The name of desired web service, such as
VideoOutput.
sServiceId The pointer to the variable that holds the result.
PelcoAPI::xstring sServiceId;
bool bSuccess = sm.GetServiceID(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605",
"VideoOutput", &sServiceId);
Retrieving a Specific Web Service’s Control URL
C5617M-H 125
Discovery (Legacy)
Obtaining a web service’s control URL is essential for many Pelco-related operations.
2. Call the System Manager Wrapper’s GetDeviceServiceAttribute() method,

System Manager.
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 holds the result of
the web service control URL.
PelcoAPI::xstring sCtrlUrl;
bool bSuccess = sm.GetDeviceServiceAttribute(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_UpnpControlUrl",
sCtrlUrl);
String sCtrlUrl = “”;

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

To determine to which NVR or NSM your camera is connected to record, complete
the following steps:
126 C5617M-H
Discovery (Legacy)
2. Call the System Manager Wrapper’s GetDeviceAttributeValue() method,


System Manager.
SYS_NvrAssoc The NVR association attribute’s ID.
sNvr The pointer to the variable that holds the result.
PelcoAPI::xstring sNvr;
bool bSuccess = sm.GetDeviceAttributeValue(loginId,
"uuid:00047D01-4CA5-5370-6563-747261495605", "SYS_NvrAssoc",&sNvr);
String sNvr = “”;

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

To determine a device’s friendly name, you can simply parse through the results
of a GetDevices() method call, which includes both the device UDN and its
accompanying attributes. Alternatively, you can complete the following steps:

System Manager.
SYS_UpnpFriendlyName The attribute name.
C5617M-H 127
Discovery (Legacy)
sFriendlyName The pointer to the variable that holds the result.
PelcoAPI::xstring sFriendlyName;
"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpFriendlyName", &sFriendlyName);
Retrieving the Device’s Device Description File (DDF) URL

What is DDF? The Device Descriptor File (DDF) is file containing device related data
such as manufacturer, model name, and so on, in XML format. To get the location of
a specific device’s DDF, do the following:
2. Call the System Manager Wrapper’s GetDeviceAttributeValue method,

System Manager.
SYS_UpnpDevDescUrl The attribute ID.
sDdfUrl The pointer to the variable that holds the result.
PelcoAPI::xstring sDdfUrl;
"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpDevDescUrl", &sDdfUrl);
String sDdfUrl = “”;

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

To show all available web services on a particular Pelco device, complete the
following steps:
128 C5617M-H
Discovery (Legacy)
2. Call the System Manager Wrapper’s GetServiceInfoSync() method, passing


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.
System Manager.
storage The pointer to the variable that holds the result.

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

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

Device attributes are values that describe the device in some way such as its model
number or 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, can be
present. Users can customize this attribute. When
present, friendlyName should be used in place of
SYS_UpnpFriendlyName for display purposes.
SYS_UpnpDeviceType Uniform Resource Name (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.
C5617M-H 129
Discovery (Legacy)
SYS_UpnpModelNumber The device’s model number.

SYS_UpnpModelDescriptionA 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:

Unique Device Name (UDN) The UDN of the target device. 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.
Attribute name The name of the device attribute to query.
Returned attribute The pointer to the variable that holds the result.
PelcoAPI::xstring sModelNumber;
"uuid:00047D01-4CA5-5370-6563-747261495605",
"SYS_UpnpModelNumber", &sModelNumber);
String sModelNumber = "";

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

A System Manager’s attributes are similar to a generic Pelco device’s attributes,
except in most 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.
130 C5617M-H
Discovery (Legacy)
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 needs to be done to support daylight
savings. If the value is nonzero, the time zone does
support daylight savings time. In this case, if the
value is negative, the time value is being used to
indicate the time to turn off daylight savings time.
If the value is positive, the value is being used to
indicate the time at which daylight savings time is to
be turned on.
DST Offset This number is the number of minutes to adjust the
time when daylight savings time is in affect. The
offset should be added to the GMT time after adding
the GMT offset (refer to GMT Offset).
GMT Offset This value indicate the number of minutes to adjust
the GMT time 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:

2. Call the System Manager Wrapper’s GetSystemAttribute() method, passing

systemAttribute The name of the System Manager attribute.
Parameter of type pointer to xstring, value
SYS_CFG_TzInfo.
A pointer to the variable that
holds the result.
int iUpnpRenewal;
bool bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL",
C5617M-H 131
Discovery (Legacy)
&iUpnpRenewal);
int iUpnpRenewal;
Boolean bSuccess = sm.GetSystemAttribute(loginId, "SYS_CFG_UPNP_RENEWAL",
ref iUpnpRenewal);
Retrieving a Web Service’s Attribute

2. Call the System Manager Wrapper’s GetDeviceServiceAttribute method,
System Manager.
The target web service’s ID Refer to Retrieving a Web Service’s ID for
details.
The ID of the web service For example, SYS_UpnpControlUrl or
attribute SYS_UpnpEventSubUrl
A pointer to the variable that holds the result.
PelcoAPI::xstring sCtrlUrl;
bool bSuccess = sm.GetDeviceServiceAttribute(loginId,
&sCtrlUrl);
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.
132 C5617M-H
Discovery (Legacy)
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 want 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)
The System Manager Wrapper uses these methods every time you call its
GetDevices() method, which in turn updates your IDeviceStorage instance
contents.
#ifndef PELCO_API_IDEVICE_STORAGE_H
#define PELCO_API_IDEVICE_STORAGE_H
#include <string>
namespace PelcoAPI
{
class IDeviceStorage
{
public:
virtual ~IDeviceStorage(){};
virtual bool AddDevice(const char* sUDN, const char* sXmlAttributes)=0;
virtual bool DeleteDevice(const char* sUDN)=0;
virtual bool UpdateDevice(const char* sUDN, const char* sXmlAttributes)=0;

};
#endif
using System;
using System.Collections.Generic;
using System.Text;
namespace SystemManagerWrapperNet
{
class DeviceInformation : PelcoAPI.IDeviceStorageNet
{
public void AddDevice(string sUDN, string sAttributes)
{
// ... User implemented logic here ...
}
public void DeleteDevice(string sUDN)
{
// ... User implemented logic here ...
C5617M-H 133
Discovery (Legacy)
}
}
}
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.
134 C5617M-H
Logging
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 are 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 not selected.
Info 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.
C5617M-H 135
Product Compatibility
The following table shows the compatibility of the Pelco SDK with Pelco products.
NOTE: These products are compatible with Pelco SDK only if the model supports
Pelco API:
• DX 47/4800 Series
• DSSRV
Product Event Event Exporter Meta- Pelco PTZ SM

Arbiter Manager data API Control Wrapper
Parser Viewer Wrapper
DX47/ Yes Yes No No Yes Yes Yes
4800
Series
DSSRV Yes Yes No No Yes Yes Yes
1
DVR5100 Yes Yes Yes Yes Yes Y Yes
2 2 2
Endura Yes Yes Yes Yes Yes No Yes
Express
2 2
IP110 Yes Yes No Yes Yes No Yes
2 2
IP3701 Yes Yes No Yes Yes No Yes
2 2
NET Yes Yes No Yes Yes No Yes
5301R
2 2
NET Yes Yes No Yes Yes No Yes
5402R-
HD
2 1 2
NET Yes Yes No Yes Yes Yes Yes
5301T
2 1 2
5308T
2 1 2
5301T-I
2 1 2
5400T-I
2 2 2
NSM5200 Yes Yes Yes Yes Yes No Yes
2 2
Sarix Yes Yes No Yes Yes No Yes
2 2
Pro
Series
2 2
Enhanced
Series
2 2
Spectra Yes Yes No Yes Yes Yes Yes
HD 720p
1
Active only if the attached IP camera is PTZ capable.
2
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.
136 C5617M-H
Product Event Event Exporter Meta- Pelco PTZ SM

Arbiter Manager data API Control Wrapper
Parser Viewer Wrapper
2 2
HD
1080p
2 2
IV IP
2 2
Mini
2 2
Esprit IP Yes Yes No Yes Yes Yes Yes
SM5000 Yes Yes No Yes No No Yes
SM5200 Yes Yes No Yes No No Yes
C5617M-H 137
About Endura Video Management
System
About Endura Video Management System

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 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?
138 C5617M-H
System
1. The System Manager constantly broadcasts its location on the Endura Network.
Once a device comes on line, it begins to listen for this broadcast. When the new
device finds the SM, it then registers 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 periodically updates the device’s
status. To be considered onl ine, 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 handle events
On later versions of 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
Figure 1: Subscribing to Events through Control URLs
C5617M-H 139
System
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 event-driven network
traffic.
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
a timestamp 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 can be instances where the API must ‘stitch’ the end
result from more than one NSM source of video clips to meet the filter.
Where Does the Pelco API SDK Fit Within Endura?
The Pelco API SDK is meant to make using Endura web services easier by providing
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.
140 C5617M-H
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.
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>
C5617M-H 141
paramId The parameter's unique identifier.

name The parameter's name.
value The parameter's value.
type The parameter's type identifier.
142 C5617M-H
Hardware Diagnostics Event
Messages
Hardware Diagnostics Event Messages

ConfigurationButton (20180)
This event triggers if the front panel configuration button has failed.
PdDiagnostic
This is the data subscribers 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
below.
previous The previous state of the button. Possible values
see below.
The possible values for the current and previous state of the button include the
following:
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.
<pdDiagnostic>
<objGuid>394af82c-2b05-4df8-b2a6-2caed9ad4fae</objGuid>
<objId>20180</objId>
<current>1</current>
<previous>3</previous>
</pdDiagnostic>
LoggableEvent Object
For more details, refer to LoggableEvent.
<deviceUdn>uuid:AK-2</deviceUdn>
<deviceUrn>urn:schemas-pelco-com:device:Pelco:1</deviceUrn>
<serviceUrn></serviceUrn>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>4</type>
C5617M-H 143
Messages
<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 multichannel 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
must be 20150
name The name of the device driver
<complexType name="DriverFailurePdDiagnostic">
<sequence>
</sequence>
</complexType>
<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 causes a LoggableEvent to be
fired.
PdDiagnostic
144 C5617M-H
Messages
<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
must be 20050
states A FanStates data type.
FanStates
This contains list of one or more FanState data types.
<complexType name="FanStates">
<sequence>
<element name="state" maxOccurs="unbounded" minOccurs="1"
type="tns:FanState"/>
</sequence>
</complexType>
state A FanState data type.
FanState
This represents the current and previous condition of a fan.
<complexType name="FanState">
<sequence>
<element name="cur" type="xs:int"/>
<element name="prev" type="xs:int"/>
</sequence>
</complexType>
cur The current state identifier. Possible values are the

following:
1. FAN_OK -- The fan is operating normally.
2. FAN_FAILED -- The fan has failed.
3. FAN_UNKNOWN -- The state of the fan is
currently unknown; this fan does not have an
initial state registered.
NOTE: This is 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>
C5617M-H 145
Messages
<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>
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>

a56c12d98d0e
must be 20060
states A HardDrivesStates data type.
HardDrivesStates
146 C5617M-H
Messages
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. HDS_READY -- Indicates that the hard disk is
currently in use.
NOTE: This could indicate a problem if the disk
is known to be currently NOT in use.
2. HDS_ONLINE -- Indicates that a disk is on line
and currently being used.
3. HDS_FAILED -- Indicates that a disk has failed.
4. HDS_HOTSPARE -- Indicates that a disk is
currently being used as a 'hot spare' within the
array.
5. HDS_REBUILD -- Indicates that a disk is
currently being rebuilt.
6. HDS_NONE -- Indicates that there is currently
no hard drive connected, and there is room for a
hard drive.
7. HDS_UNKNOWN -- Indicates that the hard
drive's state is currently unknown. This typically
means that the hard drive has yet to register any
state.
NOTE: This is always be the final stream 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>
C5617M-H 147
Messages
<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>
<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>

value must be set to a44945e0-fa54-4fb0-
a614-2e71886c508f
must be 20070
mode The mode of the shutdown.
<pdDiagnostic>
<objGuid>a44945e0-fa54-4fb0-a614-2e71886c508f</objGuid>
148 C5617M-H
Messages
<mode>4</mode>
</pdDiagnostic>
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>4</type>
<reason>4</reason>
LinkSpeed (20200)
This event triggers when the link speed changes. When this occurs, set the correct
major, minor, type, and reason for LoggableEvent. The current LinkSpeed is sent
as a parameter with the LoggableEvent object.
PdDiagnostic
<complexType name="LinkSpeedPdDiagnostic">
<sequence>
fixed="b9359885-711a-4d71-b908-4bdf8753dbe8"/>
<element name="min" type="xs:int"/>
</sequence>
</complexType>

value must be set to b9359885-711a-4d71-
b908-4bdf8753dbe8
objId The device's unique database identifier. The value
must be 20200
min The minimum link speed. For example: 100
cur The current state. For example: 10
<pdDiagnostic>
<objGuid>b9359885-711a-4d71-b908-4bdf8753dbe8</objGuid>
<min>100</min>
<cur>10</cur>
</pdDiagnostic>
C5617M-H 149
Messages
<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>
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>

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 Th
is o
pro
ala
1 Pro
pow
ala
<pdDiagnostic>
<objGuid>26f051aa-009b-4a5d-ab20-09b064a07a52</objGuid>
<inAlarm></inAlarm>
</pdDiagnostic>
150 C5617M-H
Messages
<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.
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>

value must be e746c2c8-0b97-402e-abc3-
c784890c8d99
must be 20170
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>
C5617M-H 151
Messages
<reason>0</reason>
<parameters>
<param>
<name>TimeRemaining</name>
<value>0</value>
<type>1</type>
</param>
</parameters>
152 C5617M-H
Software Diagnostics Event Messages

DataLoss 20040
When this is triggered by a data loss, set the correct major, minor, type, reason for
the LoggableEvent.
PdDiagnostic
<complexType name="DataLossPdDiagnostic">
<sequence>
</sequence>
</complexType>

The value must be set to 94b6d2d3-
c68e-4b13-974a-08f69f50cb67
must be: 20040
<complexType name="DataLossPdDiagnostic">
<sequence>
</sequence>
</complexType>
LoggableEvent object
<logId></logId>
<major>7</major>
<minor>0</minor>
<type>8</type>
<reason>0</reason>
InputStreams 20160
For each stream entry that has its state changed from previous state, the software
sends out a loggable event with appropriate major, minor, type and reason.
<complexType name="InputStreams">
<sequence>
<element name="states" type="tns:InputStreamsEntries"/>
C5617M-H 153
</sequence>
</complexType>

a56c12d98d0e
must be: 20160
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 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
154 C5617M-H
mediaType A media type identifier, for example: 0

hardwareId A hardware identifier, for example: hwidv1
stateCur The current state identifier. Possible values are
1. ISS_RECORDING -- Currently receiving a
stream and it is being recorded.
2. ISS_RECORD_ERROR -- Currently receiving a
stream, but it is unable to be recorded due to an
error.
3. ISS_RECEIVING -- Currently receiving a stream.
4. ISS_RECEIVE_ERROR -- Unable to receive a
stream.
5. ISS_MISSING -- Expecting a stream but there is
no available stream. In analog inputs, this means
the device is unable to detect a connection.
6. ISS_UNKNOWN -- The state of the stream is
currently unknown. This stream does not have
an initial state registered.
NOTE: This is always the final stream state.
statePrev The previous state identifier. Refer to stateCur for

possible valid values.
PacketLoss 20080
This event is fired when there is data loss during video data writing. Sets the
appropriate major, minor, type, and reason in Loggable Event.
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>

value must be: ddfa09d6-64f1-4b39-a7e7-
de0c5f7780cc
must be: 20080
max The maximum acceptable packet loss percentage,
for example: 1.1235
cur The current packet loss percentage, for example:
5.1235
C5617M-H 155
<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>
<element name="entries" type="tns:SEBSEntries"/>
</sequence>
</complexType>

value must be: 31e41907-53be-4f57-8ae2-
a56c12d98d0e
must be: 20210
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.
156 C5617M-H
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">
</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.
C5617M-H 157
PdDiagnostic
<complexType name="StorageFullPdDiagnostic">
<sequence>
<element name="objGuid" type="xs:string" fixed="94b6d2d3-
c68e-4b13-974a-08f69f50cb67"/>
<element name="inAlarm" type="xs:int"/>
</sequence>
</complexType>

The value must be: 94b6d2d3-
c68e-4b13-974a-08f69f50cb67
must be: 20190
inAlarm This represents whether or not a device is in a
problem state. Possible values are
• 0 -- Storage is not full, not in an alarm state.
• 1 -- Storage is full, in an alarm state.
<pdDiagnostic>
<objGuid>3df223ee-8041-4c1a-be77-2d140e5588aa</objGuid>
<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"/>
158 C5617M-H
</sequence>
</complexType>

value must be: e08fa1d1-9b30-4e62-
bc8b-16cca0f57cb0
must be: 20130
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>
<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° to 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"/>
C5617M-H 159
<element name="max" type="xs:int"/>

</sequence>
</complexType>

value must be: 26f051aa-009b-4a5d-
ab20-09b064a07a52
must be: 20140
min The minimum allowable temperature.
max The maximum allowable temperature.
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>
160 C5617M-H
Video Streaming and Exporting
Performance
Video Streaming and Exporting Performance

This section shows the maximum number of supported streams for video streaming
and video exporting operations using the Pelco SDK.
Video streaming and exporting performance testing was conducted on two separate
computers.
• One computer met the minimum hardware and network requirements shown in the
Endura Networking Guide; this is called the 'minimum specification computer'.
• The second computer exceeded the requirements; this computer is called the
'high-end computer'.
Both sets of test results are presented in this section for comparison. Because there
are many hardware configurations, conclusions should not be drawn about the
performance of any particular computer.
The following describes the specifications of both the minimum specification computer
and the high-end computer that were subjected to the testing.
Table 11: Specifications of test computers
Minimum Specification High-End Computer

Computer
Operating System Windows® Server 2008 R2 Windows XP SP3 32-bit
64-bit
CPU 2.4 GHz Intel Core 2 Duo 2.8 GHz Intel Xeon (Quad
Core)
RAM 2GB 3GB
HDD SATA HDD SATA HDD
Graphics card nVidia Quadro FX 550 PCI nVidia Quadro FX 580 PCI
Express-128 MB Express-512 MB
• Video streaming and video exporting are CPU intensive operations, and were
tested using various scenarios.
• Event monitoring and normal operations of the Pelco SDK are not CPU intensive
and were not measured.
• For the results shown in the following tables, each computer used no more than
60% of the available CPU capacity. This allows for other processes executing
concurrently during the test operations.
• Additional processes, especially CPU and GPU intensive processes, can
decrease the performance of the Pelco SDK applications.
NOTE:
• The test video streams were 30 IPS.
• Scene depicted is of medium complexity (the scene contained some motion).
Maximum Number of Concurrent Video Streams (Minimum
Specification Computer)
The maximum number of concurrent video streams supported by a computer with the
minimum specifications are shown in the following table.
Stream
Transport
C5617M-H 161
Performance
Stream Type RTP Live RTP Playback RTSP Live RTSP

Playback
MPEG-4, 1SIF 10 10 11 4
(352x240)
MPEG-4, 4SIF 3 5 4 4
(704x480)
H.264, 1SIF 4 10 8 4
(352x240)
H.264, 4SIF 3 5 3 3
(704x480)
H.264, 720P 1 1 1 1
(1280x720)
H.264, 1080P 1 1 1 1
(1920x1080)
Maximum Number of Concurrent Video Streams (High-End

Computer)
The maximum number of streams supported by a high-end computer that exceeds
the minimum specifications are shown in the following table.
Stream
Transport
Stream Type RTP Live RTP Playback RTSP Live RTSP
Playback
MPEG-4, 1SIF 32 32 16 21
(352x240)
MPEG-4, 4SIF 32 22 10 10
(704x480)
H.264, 1SIF 32 20 12 12
(352x240)
H.264, 4SIF 32 20 6 6
(704x480)
H.264, 720P 20 7 3 3
(1280x720)
H.264, 1080P 3 4 3 2
(1920x1080)
Maximum Number of Concurrent Export Streams

The exported video streams were 30 minutes in duration for single streams and
15 minutes for dual-stitched streams. The streams were PEF format, 30 IPS, and
depicted a scene of medium complexity (contained some motion).
Maximum Number of Export Streams From a Minimum
Specification Computer
The maximum number of concurrent export streams supported by a computer with
the minimum specifications are shown in the following table.
Export Type
162 C5617M-H
Performance
Stream Type Single Export (no Single Export Two-Clip Export

overlays) (overlays) (stitched,
overlays)
MPEG-4, 1SIF 6 1 1
(352x240)
MPEG-4, 4SIF 9 1 1
(704x480)
H.264, 1SIF 5 1 1
(352x240)
H.264, 4SIF 6 1 1
(704x480)
H.264, 720P 8 1 1
(1280x720)
H.264, 1080P 10 1 1
(1920x1080)
Maximum Number of Export Streams From a High-End Computer

The maximum number of export streams supported by a high-end computer that
exceeds the minimum specifications are shown in the following table.
Export Type
Stream Type Single Export (overlays) Two-Clip Export
(stitched, overlays)
MPEG-4, 1SIF (352x240) 4 5
MPEG-4, 4SIF (704x480) 3 4
H.264, 1SIF (352x240) 4 2
H.264, 4SIF (704x480) 3 2
H.264, 720P (1280x720) 2 1
H.264, 1080P (1920x1080) 2 1
C5617M-H 163
Glossary
A
ActiveX® : ActiveX® ActiveX® 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.
Autofocus : Autofocus is the ability of the lens to remain in focus during zoom-in,
zoom-out, and motion functions.
B
bit : Abbreviation for binary digit; the smallest unit of information a computer can use.
A bit is either one or zero (a high or low voltage state).
bit rate : Bit rate is the number of bits that are transferred between devices in a
specified amount of time, typically one second.
Brightness : In NTSC and PAL video signals, the brightness information at any
particular instant in a picture is conveyed by the corresponding instantaneous direct
current 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.
C
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 can be
164 C5617M-H
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 earlier technology uses 15 bits to send a command.
Extended: This later technology uses 32 bits to send a command.
codec : codec is an acronym for compression/decompression. This term is

commonly used in the context of multimedia compression and decompression, such
as video or audio.
Common Intermediate Format (CIF) :

A standard video and digital image size. Refer to SIF for NTSC resolutions.
CIF: 352 x 288 for PAL
2CIF: 704 x 288 for PAL
4CIF: 704 x 480 for PAL
QCIF: 176 x 144 for PAL
Compression : Compression is any algorithm used to reduce the size of a file.
Contrast : Contrast is a common term used in reference to the difference between

the darkest and the brightest parts of an image. Once brightness is set correctly,
contrast should be set for comfortable viewing brightness.
D
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.
E
Encoder : In an Endura system, the encoder is a high-performance MPEG-4 device
that takes analog video signals through a standard BNC coaxial cable and digitizes,
compresses, signs, and packetizes them for the network. It also provides an interface
for relays, alarms, and audio connections.
C5617M-H 165
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.
F
Firmware : Firmware is a software process 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.
G
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
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, and so forth. Hue is one of the three characteristics of
television color; the other two are saturation and luminance. In NTSC and PAL video
signals, the hue information at any particular point in the picture is conveyed by the
corresponding instantaneous phase of the active video subcarrier.
I
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.
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.
166 C5617M-H
IP camera : An IP camera is a digital video camera that outputs IP packets over
Ethernet cabling. An IP camera can 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.
M
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 subnet 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.
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.
N
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 can
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.
C5617M-H 167
P
Phase Alternation by Line (PAL) : PAL is the European (50 Hz) color TV standard.
It is used by most countries outside the US. 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,
only the vector describing this movement is contained in the P-frame. This allows a
reduction in overall file size.
PIN : Personal Identification Number. PIN is used to provide security in a system.
Power over Ethernet (PoE) : PoE enables both power and video to transmit on a
single cable.
Protocol :
Protocol is a set of rules governing the transmission of data between equipment:
D Pelco protocol that uses seven bytes to send a command.
M Pelco protocol for communicating with M devices (KBD960/KBR960 keyboards,
ALM2064 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.
R
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 software running
on one host to cause other software to be run 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.
S
Saturation : Saturation is the intensity of the colors in the active picture: the amount
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.
168 C5617M-H
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
on line, 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. Refer to CIF for PAL resolutions.
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.
T
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.
U
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.
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 default to AutoIP. 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.
V
Varifocal :
C5617M-H 169
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.
W
WSDL : Web Services Description Languages (WSDLs).
170 C5617M-H
Pelco by Schneider Electric
3500 Pelco Way
Clovis, California 93612-5699
USA
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.
© 2014 Schneider Electric. All Rights Reserved.
C5617M-H

Pelcosdk c5617m H

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Pelcosdk c5617m H

Încărcat de

Drepturi de autor:

Formate disponibile

Pelco SDK 3.

Chapter 1: Introduction to the Pelco SDK........................................ 7

Chapter 2: Using Systems and Devices..........................................12

Chapter 3: Viewing and Recording Video Streams........................ 25

Chapter 4: Exporting Video with Clip and Exporter Classes......... 36

Chapter 5: Exporting Video on Endura Systems............................39

Initializing the Exporter.................................................................................... 40

Chapter 6: Using Network Displays and Channels........................ 53

Chapter 7: Managing Systems with the Administrator Class........ 56

Chapter 8: Using Event Classes...................................................... 60

Chapter 9: Events and Alarms......................................................... 66

Chapter 10: Viewing Video Streams with Pelco API Viewer

Chapter 11: Pan, Tilt, Zoom (PTZ) Control......................................98

Chapter 12: Extracting Audio and Video Metadata...................... 111

Chapter 13: Web Service Proxies (Legacy)...................................118

Chapter 14: Discovery (Legacy).....................................................120

Appendix A: Logging...................................................................... 135

Appendix B: Product Compatibility............................................... 136

Appendix C: About Endura Video Management System..............138

Appendix D: General Event Messages.......................................... 141

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

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

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

Introduction to the Pelco SDK

For More Information

Pelco SDK Components and Classes

PelcoAPIViewer Captures live and recorded video from Pelco cameras,

Pelco SDK versus Pelco API

Overview of the Pelco SDK Object Model

The Pelco SDK 3.4 Object Model

Table 1: List of the Pelco SDK Classes

Object Model Libraries

Using Systems and Devices

System Providers and Schemes

Table 2: Pelco System Providers

System Provider Video Management Capabilities

SM5200 • Local device cache

SM5000, Digital Sentry, • Local device cache

Pelco Aggregation Direct Pelco Aggregation • Direct access to

Pelco Edge None • Local device cache

user:pass The user name and password for the

ipaddress:port The IP address and port number of the System.

For details on creating systems for each system provider, see:

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

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

// Loop over the device collection object and

// Display the device name

// Display the number of devices

Managing the Device Cache

Some integration developers, particularly on extremely large systems, might

DeviceType Type of device, which can be a Camera object,

How to Retrieve Device Information

Using the Pelco SDK Runtime in your Application

// Main entry point to the application

static void Main()

// Start the SDK runtime

Creating a Pelco System

Creating a Pelco System

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

// Create a DeviceCollection object and populate it with the devices

// Display the device name

// Display the number of devices

Creating a Pelco Aggregation Direct System