...

https://[IP address or hostname]:[port]/video/

WILL BE DEPRECATED IN NEXT RELEASE, USE /channels

Returns stored video from the camera with the given camera number and options (start time, end time, length, framerate, and/or resolution). Note: Datetime values are formatted according to the ISO 8601 specification: YYYY-MM-DDTHH:MM:SS For example, 2012-12-05T13:40:27. For more information, see this article from the W3C W3.org: Date and Time Formats.

...

https://[IP address or hostname]:[port]/channel

...

/time

https://[IP address or hostname]:[port]/time

...

/version

https://[IP address or hostname]:[port]/version

...

/views

https://[IP address or hostname]:[port]/views

...

Input for POST/views

{
"Id":null,
"Name":"1 Channel",
"Shared":false,
"UserName":"user",
"UserId":null,
"Channels":[
{
"Id":9,
"Name":"Camera 9",
"ChannelDrive":null,
"IsActive":true,
"ChannelType":"IPNetworkCamera",
"ThumbnailUrl":null,
"LocalId":0,
"Appliance":{
"Id":1,
"Name":"Developer Workstation",
"Address":null,
"MachineType":"Integrated",
"TimeZoneKey":"Pacific Standard Time",
"TimeZoneOffset":480,
"Created":"/Date(1351818098000)/",
"Updated":"/Date(1353442448000)/",
"VideoStart":"/Date(1352497452000)/",
"SyncDate":"/Date(1351818098000)/"
},
"selected":false,
"isEnterprised":false,
"Number":9,
"ChannelDriver":"GenericIPCameraDriver",
"ImageUrl":"https:///channels/9/image",
"hostname":""
}
],
}

Input for PUT/views

{
"Id":15,
"Name":"Single Channel View",
"Shared":false,
"UserName":"techrep",
"UserId":2,
"Channels":[
{
"Id":9,
"Name":"Camera 9",
"ChannelDrive":null,
"IsActive":true,
"ChannelType":"IPNetworkCamera",
"ThumbnailUrl":null,
"LocalId":0,
"Appliance":{
"Id":1,
"Name":"Developer Workstation",
"Address":null,
"MachineType":"Integrated",
"TimeZoneKey":"Pacific Standard Time",
"TimeZoneOffset":480,
"Created":"/Date(1351818098000)/",
"Updated":"/Date(1353442448000)/",
"VideoStart":"/Date(1352497452000)/",
"SyncDate":"/Date(1351818098000)/"
},
"selected":false,
"isEnterprised":false,
"Number":9,
"ChannelDriver":"GenericIPCameraDriver",
"ImageUrl":"https:///channels/9/image",
"hostname":""
}
],
}

/rtsp

https://[IP address or hostname]:[port]/rtsp

...

Sample XML Response

<RestRTSPResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Message>OK</Message>
<Uri>rtsp://10.10.10.10:554/Stream3</Uri>
</RestRTSPResponse>

Sample JSON Response

{
"Message": "OK",
"Uri": "rtsp:\/\/10.10.10.10:554\/Stream3"
}

3VR External System Activity API - SOAP

Overivew

The 3VR External System Activity API allows third parties to define their own event types for the 3VR system and add instances of these events to the 3VR system. These events can then be displayed and searched for using 3VR's OpCenter application. In OpCenter, these events can be correlated with other event types using the "Search for related events" option in the Search panel.

The 3VR External System Activity API is built on the Simple Object Access Protocol (SOAP) using HTTP, a standard web services protocol accessible from a wide variety of platforms and languages. Since SOAP is based on XML, it is easy to build requests and process replies.

To support custom events, 3VR has a framework called generic events. These events are similar to internally defined events, but their structure can be defined by external agents. A given 3VR system can have an arbitrary number of defined generic event types. However, for usability reasons, we recommend that a given vendor use a single event type and differentiate using metadata. However, this is not a hard rule. Generic events will be displayed alongside the other event types, such as Motion and Face, in the Monitor, Search, and Cases panels of OpCenter.

Generic events appear in the software using individually defined names, displayed on each generic event card. When the user chooses to view smaller event cards, the short name is displayed. For example, in the event card below, the generic event name is "Bank Teller"

Generic events can integrate custom field data. The API name for a custom field is a metadata field. The generic event definition specifies the event type name, short name, help text, metadata fields, and a globally unique identifier (GUID). The generic event definition GUID identifies the generic event type and metadata fields across different 3VR servers.

Each metadata field has name, description, type, display position, display format and GUID.

• Name appears in the event details and may appear on the event card depending on the display format.

• Type specifies the kind of data stored in the field. The type can be String, Number, DateTime, or EnumeratedType.

• Description is a text string that describes the field.

• Display position controls the order in which the metadata fields are displayed.

• Display format controls the way the data is displayed on the large event cards.

When you define a new generic event type, you will have to create GUIDs for the event type itself and each of the metadata fields that you are defining. It is important to use the same GUIDs for every server on which you use your application. GUIDs can be generated in a number of ways.

• At the time of this writing, GUIDs could be generated on the following sites:

  • GUID Generator

  • GUID Gen

• Microsoft Visual Studio includes a GUID generating tool called GUIDGen.exe. This program is located in \Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Binin Visual Studio 2010.

• When the generic event definition is created, if a GUID has not been specified, a GUID will be generated automatically and returned in the response. Incorporate the response GUID into your code whenever you create the definition.

A typical application of the External System Activity API will:

1. Authenticate the user of the application. The user needs to be defined in 3VR System Manager. The authenticate call returns an authentication token that is used in SOAP Header for all subsequent requests.

2. Create the generic event definition if it does not already exist.

3. Based on some external stimulus, create a generic event associated with a camera.

Authentication is accomplished using the IAuthenticateService. The IGenericEventService provides the rest of the API.

Browsing 3VR External System Activity API Services

Verify that the Web Services is running by pointing a browser at any of the following 3VR External System Activity API services

• https://hostaddress:8080/3vr/IAuthenticateService.asmx

• https://hostaddress:8080/3vr/IGenericEventService.asmx

Click on any of the asmx links to see the available services. The SOAP WSDL is available at the Service Description link. The service call XML specification is available on the operation link.

Authentication

• https://hostaddress:8080/3vr/IAuthenticateService.asmx?op=Authenticate

Authenticate against the 3VR users. The Soap Header can be blank. It will return the Token for use in the SOAP header for subsequent operations.

Create Events

Once authenticated you are ready to create events with the IGenericEventService. The WSDL is available by clicking the Service Description link.

https://hostaddress:8080/3vr/IGenericEventService.asmx:

The primary operations are:

• CreateGenericEventDefinition: Create a Generic Event Definition for new generic events. Values for Type = String, Number, DateTime, or EnumeratedType

• CreateGenericEvent: Create a Generic Event from the server.

The other operations are used in support of generic event creation.

• Channels: Get a list of channels.

• CustomFieldNames: Get a list of Custom Field Names associated with a person profile in the 3VR system. Used for FaceComparison events.

• DeleteGenericEvent: Delete a Generic Event.

• DeleteGenericEventDefinition: Delete a Generic Event Definition.

• GenericEvent: Get a Generic Event from the server.

• GenericEventDefinitionByGUID: Find an the Generic Event Definitions with the specified GUID.

• GenericEventDefinitionsAll: Get all Generic Event Definitions.

• GenericEventDefinitionsByName: Find all the Generic Event Definitions with the provided name.

• UpdateGenericEvent: Update a Generic Event.

• UpdateGenericEventDefinition: Update an existing Generic Event Definition GUIDs must match for existing elements

Developing Client Programs

3VR Web Services are design to work in various environments (.NET, Java, Python, etc.).

.NET

If you are working in .NET, the program wsdl.exe (in \Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin) will automatically generate client code. For example, to generate C#, run the following at the command line:

> wsdl /language:CS https://[IP or host name of 3VR appliance]:8080/3vr/IGenericEventService.asmx?WSDL

and WSDL.exe will generate client code to access Generic Event operations.

Java XML

For Java systems, 3VR provides an example using Apache.org's Axis package and WSDL2Java to generate the client code using JAX-RPC and JAWS API's. This sample uses Axis 1.4 from Apache.org and JAF activation.jar and mail.jar from java.sun.com

1. Set AXIS _ HOME to where you installed Axis, e.g. C:\java\axis-1 _ 4\lib.

2. Set up or copy the log4j properties from AXIS _ HOME, and set up AXIS _ HOME in the environment.

3. The CLASSPATH will look something like:
   

   Code Block
   CLASSPATH = .;%AXIS _ HOME%\axis.jar;%AXIS _ HOME%\commons-discovery-0.2.jar;%AXIS _ HOME%\commons- logging-1.0.4.jar;%AXIS _ HOME%\jaxrpc.jar;%AXIS _ HOME%\log4j-1.2.8.jar;%AXIS _ HOME%\saaj. jar;%AXIS _ HOME%\wsdl4j-1.5.1.jar;%AXIS _ HOME%\mail.jar;%AXIS _ HOME%\activation.jar

4. Run WSDL2Java at the command line to create the client library.
   

   Code Block
   > java org.apache.axis.wsdl.WSDL2Java --output src --package com. _ 3vr.Services http:// localhost/3vr/IAuthenticateService.asmx?WSDL>java org.apache.axis.wsdl.WSDL2Java --output src --package com. _ 3vr.Services http://localhost/3vr/IGenericEventService.asmx?WSDL

5. With the generated code, use of the Authenticate operation in Java becomes:
   

   Code Block
   language java
   try{ IAuthenticateServiceLocator locator = new IAuthenticateServiceLocator(); java.net.URL url = new java.net.URL(serverUrl + "IAuthenticateService.asmx"); IAuthenticateServiceSoap _ PortType port = locator.getIAuthenticateServiceSoap(url); AuthenticateToken token = port.authenticate("user", "password"); System.out.println("Status " + token.getStatus() + "Token " + token.getToken()); if(token.getStatus().equals("Success")) { return token.getToken(); } } catch(Exception e) { System.out.println(e.getMessage());

6. To use the generic operations, the token needs to be set in the header. The SoapHeaderInfo class 3VR uses to put the Service Token in the SoapHeader is not created by WSDL2Java. We created one to match the other classes generated. Putting the Service token in the SoapHeader becomes:

import javax.xml.namespace.QName;
import org.apache.axis.message.SOAPHeaderElement;
try
{
IGenericEventServiceLocator locator = new IGenericEventServiceLocator();
java.net.URL url = new java.net.URL(serverUrl + "IGenericEventService.asmx");
genericEventService = locator.getIGenericEventServiceSoap(url);
QName qname = new QName("http://3vr.com", "SoapHeaderInfo");
SoapHeaderInfo SoapHeaderInfo = new SoapHeaderInfo("", token);
SOAPHeaderElement header = new SOAPHeaderElement(qname, SoapHeaderInfo);
org.apache.axis.client.Stub stub = (org.apache.axis.client.Stub)genericEventService;
stub.setHeader(header);
}c
atch(Exception e)
{
System.out.println(e.getMessage());
}

For more details, see the source for the BankTeller Java sample.