network camera server webview programmers guide ver....

Network Camera Server

WebView Programmers Guide

Ver. 1.0

BIE-7087-000

January 30, 2015

CANON INC.

033360draft

Revision History Version Release Date Location Changes

1.0 January 30, 2015 - First edition

Table of Contents

1 Introduction .......................................................................................................................... 1 1.1 Use of this Document ................................................................................................... 1 1.2 Supported Products...................................................................................................... 1 1.3 Notation ........................................................................................................................ 2 1.4 Trademarks .................................................................................................................. 2

2 Related Documents .............................................................................................................. 3

3 Protocol Overview ................................................................................................................ 4 3.1 Protocol Configuration ................................................................................................. 5

4 Development Environment ................................................................................................. 6 4.1 Development Environment for Sample Code ............................................................. 6 4.2 Operating Environment for Sample Code .................................................................. 6 4.3 Prerequisites for Sample Code .................................................................................... 6

5 Use Cases ............................................................................................................................. 7

6 Hello WebView ................................................................................................................... 11 6.1 Acquiring a Still Image from a Web Browser .......................................................... 11

6.1.1 Running the Scenario .................................................................................... 12 6.2 Controlling the Camera from a Web Browser .......................................................... 13

6.2.1 Running the Scenario .................................................................................... 14 6.3 First WebView Application ....................................................................................... 16

6.3.1 Initial Processing of the Application ............................................................ 19 6.3.2 Video Acquisition Processing ........................................................................ 23 6.3.3 Pan-Tilt-Zoom Processing [Absolute Positioning] ....................................... 25 6.3.4 Running the Scenario .................................................................................... 27

7 Sample Scenarios ............................................................................................................... 28 7.1 Installation ................................................................................................................. 28

7.1.1 Discovery ........................................................................................................ 28 7.2 Camera Control .......................................................................................................... 35

7.2.1 Operating the Camera [Acquiring Control] ................................................. 35 7.2.2 Operating the Camera [Pan-Tilt-Zoom] ....................................................... 55 7.2.3 Operating the Camera [Various Correction Settings] ................................. 72 7.2.4 Operating the Camera [Angle of View Linkage] ......................................... 86

7.3 Video Acquisition ....................................................................................................... 96 7.3.1 Video Stream Acquisition [HTTP] ................................................................ 96

7.3.2 Video Stream Acquisition [RTSP] .............................................................. 113 7.3.3 Video Stream Acquisition [Digital PTZ]..................................................... 123 7.3.4 Video Stream Acquisition [H.264] .............................................................. 134

7.4 Video Recording ....................................................................................................... 153 7.4.1 SD Card Manual Recording ........................................................................ 153

7.5 Events ....................................................................................................................... 173 7.5.1 Event Detection ........................................................................................... 173 7.5.2 Linked Event ................................................................................................ 180

7.6 Audio ......................................................................................................................... 198 7.6.1 Audio Reception [Camera→Client] ............................................................ 198 7.6.2 Audio Transmission [Client→Camera] ...................................................... 210

7.7 Camera Settings ....................................................................................................... 222 7.7.1 Using Presets ............................................................................................... 222 7.7.2 Using Extension Presets ............................................................................. 240

Appendix ................................................................................................................................... 256 A Command Index ....................................................................................................... 256

1

1 Introduction This document was created in order to help the user understand and learn to use the WebView protocol that works with the Canon Network Camera Server.

1.1 Use of this Document This document is for developers of applications using the Canon network camera. Use of this document requires knowledge of application development. The sample code in this document does not come with any guarantee of completeness or accuracy. Canon shall not be held responsible for any losses arising directly or indirectly from the use of the contents of this document.

1.2 Supported Products This document was designed for the following Canon network cameras. Canon Network Camera VB-S30D Canon Network Camera VB-S31D Canon Network Camera VB-S800D Canon Network Camera VB-S900F Canon Network Camera VB-S805D Canon Network Camera VB-S905F Canon Network Camera VB-H43 Canon Network Camera VB-H630VE Canon Network Camera VB-H630D Canon Network Camera VB-H730F Canon Network Camera VB-M42 Canon Network Camera VB-M620VE Canon Network Camera VB-M620D Canon Network Camera VB-M720F Canon Network Camera VB-R11VE Canon Network Camera VB-R11 Canon Network Camera VB-R10VE Canon Network Camera VB-M641VE Canon Network Camera VB-M641V Canon Network Camera VB-M640VE Canon Network Camera VB-M640V Canon Network Camera VB-M741LE Canon Network Camera VB-M740E

2

1.3 Notation The following notation and text formatting are used in this document.

“Courier New” Indicates a code sample.

“Italic” Indicates a parameter replaceable with an actual name or value.

“Verdana 0…50” Indicates a parameter or setting value.

“” Indicates a variable.

“Note:” Indicates a special note or precaution.

“!” Indicates an example of the occurrence of a phenomenon.

“XXXXXX ” Indicates a reference document.

‘XXXXXX ’ Indicates a reference chapter or section.

1.4 Trademarks Microsoft, Windows, Visual C# and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Other brands or product names in this guide are trademarks or registered trademarks of their respective companies.

3

2 Related Documents The Canon network camera server WebView protocol specifications include the following documents. - Protocol specifications ・Network Camera Server WebView Protocol Overview ・Network Camera Server WebView HTTP Protocol Specifications ・Network Camera Server WebView Settings Protocol Specifications ・Network Camera Server WebView Audio Protocol Specifications ・Network Camera Server WebView Data Protocol Specifications ・Network Camera Server WebView Memory Card Protocol Specifications ■ Tutorials ・Network Camera Server WebView Programmers Guide (this document)

4

3 Protocol Overview The WebView protocol is provided as an HTTP service on the network camera. WebView protocol commands can be used to create applications that control the network camera and use it to deliver video and audio.

Fig. 3-1 WebView Protocol Concept Diagram

HTTP server - WebView HTTP protocol

- WebView settings protocol

- WebView audio protocol

- WebView data protocol

- WebView memory card protocol

Canon network camera Client

Router/firewall

Client

- User application - Web browser

Internet

WAN

LAN

HTTP request →

← HTTP response

Client

- User application - Web browser

5

3.1 Protocol Configuration The WebView protocol consists of five protocols, each associated with a specific function, along with a device discovery protocol. The protocols and the functions they are responsible for are listed below.

VB-Discovery Device discovery protocol of the network camera. For details, see “Network Camera Server WebView HTTP Protocol Specifications Appendix. F VB-Discovery ”.

WebView HTTP Protocol Protocol that provides video transmission and camera control functions for the network camera. For details, see “Network Camera Server WebView HTTP Protocol Specifications ”.

WebView Settings Protocol Protocol for viewing and updating the settings of the network camera. For details, see “Network Camera Server WebView Settings Protocol Specifications ”.

WebView Audio Protocol Protocol that provides functions for transmitting audio to and from the network camera. For details, see “Network Camera Server WebView Audio Protocol Specifications ”.

WebView Data Protocol Protocol that provides internal and external memory access functions for the network camera. For details, see “Network Camera Server WebView Data Protocol Specifications ”.

WebView Memory Card Protocol Protocol that provides functions to control the network camera’s memory card. For details, see “Network Camera Server WebView Memory Card Protocol Specifications ”.

6

4 Development Environment 4.1 Development Environment for Sample Code Microsoft Visual Studio Professional 2012 Visual C# 2012 .NET Framework 4.5

4.2 Operating Environment for Sample Code Microsoft Windows 7 SP1 or later Windows Experience Index 5.0 or higher

4.3 Prerequisites for Sample Code In the examples, the IP address of the camera is “192.168.0.1”. When running the samples, please replace the IP address to fit the actual environment.

7

5 Use Cases Recognizing the camera on the network In an application, you want to display a list of cameras that is kept current. You want the ability to add a camera without changing the application settings.

Note: Applications can use the VB-Discovery protocol to find the camera on the local network. For a sample discovery scenario, refer to ‘7.1.1 Discovery ’.

Acquiring video from the camera [HTTP] You want to select a delivery method that allows video streaming to more clients

without requiring port and firewall settings.

Note: HTTP or RTSP can be selected as the video streaming protocol. The HTTP protocol is generally less constrained in terms of network routing. For a sample scenario that uses video streaming over HTTP, refer to ‘7.3.1 Video Stream Acquisition [HTTP] ’.

You want to select a video delivery method that minimizes the amount of data

transferred depending on environments such as narrow network bandwidth. You want to take a snapshot of the video being displayed in the application.

Note: JPEG or H.264 can be selected as the video delivery format. Within the JPEG video delivery method, in addition to video streaming, you can select pseudo-video streaming by continuous acquisition of still images. For a sample scenario that uses continuous JPEG still image acquisition, refer to ‘7.2.1 Operating the Camera [Acquiring Control] ’.

8

Acquiring video from the camera [RTSP] You want to select a video delivery method that suits your needs such as ensuring

stable video quality or enhancing the interactivity of your application. You want to create an application that saves delivered video in MP4 format.

Note: HTTP or RTSP can be selected as the video streaming protocol. RTSP offers better interactivity, including PLAY and PAUSE commands. For a sample scenario that uses video streaming over RTSP, refer to ‘7.3.2 Video Stream Acquisition [RTSP] ’.

Acquiring video from the camera [H.264] You want to use a video format with high compression when transmitting video

with network bandwidth restrictions.

Note: JPEG or H.264 can be selected as the video format. H.264 has higher compression efficiency than conventional methods, and it can be used widely, from low bitrate applications, such as 3G lines, to high bitrate applications including HDTV. For a sample scenario that uses video acquisition using H.264, refer to ‘7.3.4 Video Stream Acquisition [H.264] ’.

Operating the camera [pan-tilt-zoom] You want to change the direction of the camera. You want to enlarge the image.

Note: To control the pan, tilt, and zoom of the camera, you can choose to specify the absolute position or to specify the direction. You can also specify the speed of the pan, tilt, and zoom operations. For a sample scenario that specifies the absolute position of the pan, tilt, and zoom, refer to ‘6.3.3 Pan-Tilt-Zoom Processing [Absolute Positioning] ’. For a sample scenario that specifies the direction of the pan, tilt, and zoom, refer to ‘7.2.2 Operating the Camera [Pan-Tilt-Zoom] ’.

Operating the camera [various correction settings] You want to shoot at night or indoors with limited light. You want to clearly capture areas darkened under the shade of a building.

Note: The camera offers a variety of image correction features. You can shoot in night vision mode and correct parts that are in shadow. For a sample scenario that uses various correction settings, refer to ‘7.2.3.2 Correction Processing ’.

9

Operating the camera [when there are multiple clients] You want to allow multiple client applications to operate the camera on the

network without interrupting the administrator’s operations.

Note: To operate the camera, you must obtain “control privileges” that give authority to operate the camera. While the client has control privileges, other clients will not be able to operate the camera. For a sample scenario that uses control privileges, refer to ‘7.2.1 Operating the Camera [Acquiring Control] ’.

Recording camera video to an SD card You want to record to an SD card inserted in the camera when it finds an incident

in the video.

Note: You can insert an SD card into the camera and save the video that is being delivered. For a sample scenario that records manually to an SD card, refer to ‘7.4.1 SD Card Manual Recording ’.

Acquiring audio from the camera microphone Because strict privacy is required, at normal times you want to perform

monitoring of audio only. When an incident is found in the video, you want to acquire the audio from the

vicinity of the camera.

Note: If you have connected a microphone to the camera, it is possible to acquire the audio from the vicinity of the camera and play it back on the client. For a sample scenario that receives audio, refer to ‘7.6.1 Audio Reception [Camera→Client] ’.

Using events detected by the camera You want to record in response to sound generated in the vicinity of the camera. You want to be alerted when people pass through the location being monitored by

the camera.

Note: You can detect various events with the camera and use them in the application. For a sample scenario that uses event detection, refer to ‘7.5.1 Event Detection ’.

10

Registering the direction of the camera You want to register a monitoring location with multiple cameras and switch

quickly between them. You want to apply correction to the image associated with the registered location.

Note: You can preset a desired direction on the camera, and then easily change the camera direction to the preset location. For a sample scenario that uses presets, refer to ‘7.7.1 Using Presets ’.

Operating the camera [digital PTZ] You want to switch the view of a camera that does not support PTZ functionality.

Note: You can achieve pseudo-PTZ functionality on a camera that does not support it by performing image processing inside the camera. For a sample scenario that uses digital PTZ, refer to ‘7.3.3 Video Stream Acquisition [Digital PTZ] ’.

11

6 Hello WebView Let’s try actually using the WebView protocol. We will first use a Web browser to experiment with typical commands, and then create a simple application. We will use “192.168.0.1” as the IP address of the camera. Please replace this with the actual IP address when running the examples.

6.1 Acquiring a Still Image from a Web Browser Use the WebView HTTP protocol to display a still image from the camera on a Web browser.

Scenario and advance preparation

Scenario:

This scenario uses the still image acquisition command to display a JPEG image in the Web browser.

Advance preparation: [Check camera settings]

Before trying out the scenario, make sure the camera settings are configured as indicated below. Check the values of the camera settings on the Setting Page. [Access Control] User Authority

Guest User Video Distribution Yes

Advance preparation: [Check camera installation]

Before trying out the scenario, make sure the installation status is as indicated below. At least one camera is installed on the local network.

Keywords that appear in this scenario The WebView protocol keywords that appear in this scenario are described below. In the text, a mark such as †1 indicates an item that is explained in the corresponding line in the table below.

No.

Keyword Explanation

†1 image.cgi Still image acquisition command. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.2.1 Still Image Retrieval [image.cgi] ”

12

6.1.1 Running the Scenario Running the scenario [Still image acquisition command]

Step 1 Enter the following still image acquisition command (image.cgi†1) in the URL of the Web browser, and verify that the still image from the camera is displayed.

Command: [Still image acquisition command example] http://192.168.0.1/-wvhttp-01-/image.cgi

Note: Make sure the IP address used in this example, “192.168.0.1”, is replaced with the actual IP address in your environment.

Step 2 Refresh the page in the Web browser. Verify that the image is updated

whenever you refresh the page.

13

6.2 Controlling the Camera from a Web Browser Use the WebView HTTP protocol to control the camera from a Web browser.


Scenario:

This scenario uses the camera control commands to pan, tilt, and zoom the camera. It also uses the information acquisition commands to check the upper and lower limits on the values that can be specified in the pan, tilt, and zoom operations.



Guest User Camera Control Yes

Note: In setting the above user privileges, even if Camera Control is not checked, an administrator or authorized user can still operate the camera by authenticating in the authentication dialog box displayed by the Web browser.


Before trying out the scenario, make sure the installation status is as indicated below. At least one camera is installed on the local network. The camera is not being accessed by another application, such as the Admin

Viewer.


No.

Keyword Explanation

†1 control.cgi Camera control command. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.4.1 Camera Control [conrol.cgi] ”

†2 info.cgi Information acquisition command. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.3.1 Information Acquisition [info.cgi] ”

14

6.2.1 Running the Scenario Running the scenario [Camera control command]

Step 1 Enter the camera control command (control.cgi†1) in the URL of the Web browser. Verify that the PTZ positions change and that the Web browser displays the response shown below.

Command: [Camera control command example] http://192.168.0.1/-wvhttp-01-/control.cgi?pan=100&tilt=-10&zoom=3000

Note: Make sure the IP address used in this example, “192.168.0.1”, is replaced with the actual IP address in your environment. Note that specifying the parameter “pan=100” moves 1.00 degree to the right, “tilt=-10” moves down 0.10 degrees, and “zoom=3000” changes the angle of view to 30.00 degrees.

Response: [Camera control command example] c.1.zoom:=3000 c.1.pan:=100 c.1.tilt:=-10

Step 2 Try various changes to the pan, tilt, and zoom values in the camera control

command and verify that the camera works accordingly. Also verify that the image changes when you execute the still image acquisition command from ‘6.1 Acquiring a Still Image from a Web Browser ’.

Running the scenario [Information acquisition command example] Step 1 Enter the information acquisition command (info.cgi†2) in the URL of the

Web browser. Verify that the Web browser displays the response shown below.

Command: [Information acquisition command example] http://192.168.0.1/-wvhttp-01-/info.cgi

Note: Make sure the IP address used in this example, “192.168.0.1”, is replaced with the actual IP address in your environment.

15

Response: [Information acquisition command example] timestamp=76.460 realtime=1390268338.606 s.epoch:=Tue, 21 Jan 2014 10:38:09 +0900 s.hardware:=Canon VB-S30D ..... c.1.zoom.min:=2070 c.1.zoom.max:=7770 c.1.pan.min:=-17500 c.1.pan.max:=17500 c.1.tilt.min:=-9000 c.1.tilt.max:=0 .....

“c.1.xxxx.min/max” shows the upper and lower limits on the values that can be specified in the pan, tilt, and zoom operations. If you specify a value outside this range, the camera will operate at the upper and lower limit values only.

Note: The response above shows only information relevant to the example. Other information that normally appears has been omitted. For details, refer to the following. “Network Camera Server WebView HTTP Protocol Specifications 5.2.3.1 Information Acquisition [info.cgi] ”

16

6.3 First WebView Application Using the WebView HTTP protocol, create an application that displays video from the

camera. The application will also let you perform pan, tilt, and zoom operations using the

scroll bars.

□ Video Acquisition Methods To acquire video from the camera, there are two methods, still image acquisition and video stream acquisition, described below. This sample application uses still image acquisition. - Still image acquisition

JPEG images can be acquired as still images. They can be displayed as video by repeatedly acquiring and displaying them.

- Video stream acquisition JPEG images or H.264 video streams can be acquired.


Scenario:

This sample application illustrates using the still image acquisition command to display video by repeatedly acquiring and displaying JPEG images. It also lets you experiment with performing pan, tilt, and zoom operations using the scroll bars.


Before trying out the scenario, make sure the camera settings are configured as indicated below. Check the values of the camera settings on the Setting Page. [Camera] Installation Conditions

Image Flip Enable [Access Control] User Authority

Guest User Camera Control Yes Video Distribution Yes


Before trying out the scenario, make sure the installation status is as indicated below. At least one camera is installed on the local network. The camera is not being accessed by another application, such as the Admin

Viewer.

17

Sample application The following is an overview of a sample application for running the scenario.

Fig. 6-1 [First WebView Application] Sample Application

- When the application is started, the video from the camera is displayed. - You can manipulate the scroll bars to pan, tilt, and zoom.

18

The following is an overview of the operation of the sample application for running the scenario.

Fig. 6-2 [First WebView Application] Sample Application Operation Overview

Assumptions and Notes:

In this sample application, error checking and exception handling have been omitted. Be sure to verify the advance preparation requirements carefully, since essentially no error messages will be generated.

19

6.3.1 Initial Processing of the Application The initial processing of the application consists of tasks such as running info.cgi, initializing the scroll bars with the acquired information, and starting the image acquisition timer.

Note: This sample application displays video by using a timer as a mechanism for running image.cgi continuously at fixed intervals.

Sequence:

Fig. 6-3 [First WebView Application] Initial Processing Sequence

20

Sample code 1 [Initial processing: overall processing] Acquire camera information by running info.cgi. Extract the current values and the upper and lower limits for the pan, tilt, and zoom operations from the information, and initialize the position and upper and lower limit values on the scroll bars. Start a timer to run image.cgi continuously.

Command: [Information acquisition example] http://192.168.0.1/-wvhttp-01-/info.cgi

Sample code: [WvCameraViewer.cs] /// /// Callback function when window is shown. /// Starts communication with camera. /// private void WvCameraViewer_Shown(object sender, EventArgs e) { MessageBox.Show(this, "Connecting to camera [" + REMOTE_HOST + "].\n" + "This may take some time.", "", MessageBoxButtons.OK, MessageBoxIcon.Information); Cursor.Current = Cursors.WaitCursor; // 1: Issue info.cgi command to get camera information. string response = httpSession.SendCommand("info.cgi"); if (string.IsNullOrEmpty(response)) { MessageBox.Show(this, "Could not connect to camera.\n" + "Please quit the application.", "Connection failure", MessageBoxButtons.OK, MessageBoxIcon.Error); Cursor.Current = Cursors.Default; return; } connectionCreated = true; // 2: Initialize the scroll bars. ProcessNotice(response); // 3: Start the timer for image acquisition. imageTimer = new System.Windows.Forms.Timer(); imageTimer.Interval = IMAGE_INTERVAL; imageTimer.Tick += new EventHandler(ImageTimerTick); *1 imageTimer.Enabled = true; Cursor.Current = Cursors.Default; EnableControls(true); }

Note: *1 The first execution of the timer function for running image.cgi occurs at this time.

21

Sample code 2 [Initialization processing: initialize scroll bars] Handle the response from info.cgi. Process the response line by line to extract the current values and the upper and lower limits of the pan, tilt, and zoom, and then initialize the scroll bars.

Sample code: [WvCameraViewer.cs] /// /// Process camera information (response from info.cgi) and update UI. /// void ProcessNotice(string notice) { int pan = int.MaxValue; int tilt = int.MaxValue; int zoom = int.MaxValue; // Because camera information consists of multiple lines of text, // extract the required information line by line. StringReader reader = new StringReader(notice); while (true) { string line = reader.ReadLine(); if (string.IsNullOrEmpty(line)) break; if (line.StartsWith("c.1.pan:=")) *1 pan = GetValue(line); else if (line.StartsWith("c.1.tilt:=")) tilt = GetValue(line); else if (line.StartsWith("c.1.zoom:=")) zoom = GetValue(line); else if (line.StartsWith("c.1.pan.limit.min:=")) *2 panScrollBar.Minimum = GetValue(line); else if (line.StartsWith("c.1.pan.limit.max:=")) panScrollBar.Maximum = GetValue(line); else if (line.StartsWith("c.1.tilt.limit.max:=")) tiltScrollBar.Maximum = GetValue(line); else if (line.StartsWith("c.1.tilt.limit.min:=")) tiltScrollBar.Minimum = GetValue(line); else if (line.StartsWith("c.1.zoom.limit.min:=")) zoomScrollBar.Minimum = GetValue(line); else if (line.StartsWith("c.1.zoom.limit.max:=")) zoomScrollBar.Maximum = GetValue(line); } // Update pan, tilt, and zoom positions in scroll bars. if (pan != int.MaxValue) *2 panScrollBar.Value = pan; if (tilt != int.MaxValue) tiltScrollBar.Value = tiltScrollBar.Maximum + tiltScrollBar.Minimum - tilt; *3 if (zoom != int.MaxValue) zoomScrollBar.Value = zoom; }

Note: *1 Acquire the current values of pan, tilt, and zoom. It extracts the value parts from

the camera information strings, which have the following format. := E.g. “c.pan:=6151” ⇒ 6151

22

*2 As can be seen from the example response shown below, the current values come before the upper and lower limit values in the information acquired from the camera. The scroll bars are therefore not updated until after the upper and lower limit values have been processed.

*3 Since “Image Flip” is enabled on the camera’s Setting page, the image to be displayed is rotated by 180 degrees. Therefore, it sets the value rotated 180 degrees (flipped) with respect to the tilt direction.

Response: [Information acquisition command example] timestamp=76.460 realtime=1390268338.606 s.epoch:=Tue, 21 Jan 2014 10:38:09 +0900 s.hardware:=Canon VB-S30D ..... c.1.zoom:=3120 c.1.zoom.min:=2070 c.1.zoom.max:=7770 c.1.pan:=6151 c.1.pan.min:=-17500 c.1.pan.max:=17500 c.1.tilt:=-1592 c.1.tilt.min:=-9000 c.1.tilt.max:=0 .....

23

6.3.2 Video Acquisition Processing Use a timer event that operates at a fixed interval to repeatedly run image.cgi and display the images.

Sequence:

Fig. 6-4 [First WebView Application] Video Acquisition Processing Sequence

Sample code 1 [Video acquisition processing: timer event] This code handles callback processing for the image acquisition timer. It executes still image acquisition processing and displays the JPEG image that is acquired.

Sample code: [WvCameraViewer.cs] /// /// Callback function of the image acquisition timer. /// private void ImageTimerTick(object sender, EventArgs e) { liveScreen.Image = httpSession.GetImage(); }

Sample code 2 [Video acquisition processing: issue command] Run image.cgi and return the JPEG image.

Command: [Video acquisition example] http://192.168.0.1/-wvhttp-01-/image.cgi

24

Sample code: [WvHTTPSession.cs] /// /// Send WebView HTTP command image.cgi to camera, /// extract image from response, and return it. /// public Image GetImage() { // 1: Acquire video from camera. string command = server + "image.cgi"; HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(command); HttpWebResponse response = (HttpWebResponse)request.GetResponse(); // Return image that was acquired. return new Bitmap(response.GetResponseStream()); *1 }

Note: *1 Since this application uses the .NET Framework, the Bitmap class does the

decoding from stream to bitmap.

25

6.3.3 Pan-Tilt-Zoom Processing [Absolute Positioning] Run control.cgi to perform pan, tilt, and zoom operations.

Sequence:

Fig. 6-5 [First WebView Application] Pan-Tilt-Zoom Processing [Absolute Positioning] Sequence

Sample code 1 [Pan-tilt-zoom processing: run command] The sample code shows callback functions for the pan, tilt, and zoom scroll bars. The command control.cgi is run with the value of the scroll bar specified as an offset angle. The angles are specified in units of 0.01 degrees.

Command: [Pan example] http://192.168.0.1/-wvhttp-01-/control.cgi?c.1.pan=-9000

Command: [Tilt example] http://192.168.0.1/-wvhttp-01-/control.cgi?c.1.tilt=-500

26

Command: [Zoom example] http://192.168.0.1/-wvhttp-01-/control.cgi?c.1.zoom=4000

Note: “pan=-9000” moves 90 degrees to the left, “tilt=-500” moves down 5 degrees, and “zoom=4000” changes the angle of view to 40 degrees.

Sample code: [WvCameraViewer.cs] /// /// Callback function when pan scroll bar is controlled. /// private void panScrollBar_Scroll(object sender, ScrollEventArgs e) { if (e.Type == ScrollEventType.EndScroll) httpSession.SendCommand("control.cgi?c.1.pan=" + e.NewValue); } /// /// Callback function when tilt scroll bar is controlled. /// private void tiltScrollBar_Scroll(object sender, ScrollEventArgs e) { if (e.Type == ScrollEventType.EndScroll) { int t = tiltScrollBar.Maximum + tiltScrollBar.Minimum - e.NewValue; httpSession.SendCommand("control.cgi?c.1.tilt=" + t); } } /// /// Callback function when zoom scroll bar is controlled. /// private void zoomScrollBar_Scroll(object sender, ScrollEventArgs e) { if (e.Type == ScrollEventType.EndScroll) httpSession.SendCommand("control.cgi?c.1.zoom=" + e.NewValue); }

Note: When control.cgi is executed continuously, the commands must be spaced at least 200 msec apart. However, no spacing is implemented in this sample code in order to make it easier to understand. Because the UI thread handles the sending of the command in these examples, you will not be able to control the UI until there is a response from the camera.

27

6.3.4 Running the Scenario Running the scenario [General session: single client]

Start the sample application, check the video from the camera, and try the pan, tilt, and zoom operations. Step 1 Start the sample application and confirm that the video is displayed. Step 2 Try the pan, tilt, and zoom operations and confirm that the changes in

camera direction are reflected in the video.

28

7 Sample Scenarios 7.1 Installation 7.1.1 Discovery VB-Discovery is provided as one of the WebView protocols in order to allow clients to easily acquire device information from the camera over a network. VB-Discovery is implemented in the UDP protocol.

□ Discovery Discovery refers to the ability to find a camera on the network. A client can use the VB-Discovery protocol to broadcast a discovery message in order to get a response from the camera. The client can use the responses to maintain an up-to-date list of available cameras. Discovery messages can also be transmitted by unicast.

Fig. 7-1 Illustration of Discovery and Response Using the VB-Discovery Protocol

Note: For the packet formats of the discovery message and response, refer to the following. “Network Camera Server WebView HTTP Protocol Specifications Appendix F VB-Discovery ”

VB-Discovery Broadcast

VB-Discovery response

Network Camera

Other device Other device

Client Network Camera

Network Camera

29

Scenario and advance preparation Scenario: This example demonstrates an application that broadcasts a discovery message from the client, and then obtains response messages from cameras on the network and displays them as a list.


Before trying out the scenario, make sure the camera settings are configured as indicated below. The IP address of the camera (IPv4) is already set.


Before trying out the scenario, make sure the installation status is as indicated below. At least one camera is installed on the local network.


Fig. 7-2 [Discovery] Sample Application

- When you press the Discover button, it broadcasts a discovery message. - The discovery message and camera response messages are displayed in the

text box.

30

The following is an overview of the operation of the sample application for running the scenario.

Fig. 7-3 [Discovery] Sample Application Operation Overview



31

7.1.1.1 Discovery Processing Discovery processing in the application consists of preparing for the received responses, sending the discovery message, and serially processing the camera responses that are received.

Sequence:

Fig. 7-4 [Discovery] Discovery Processing Sequence

Sample code 1 [Initialization processing: start of asynchronous reception] Bind port 52221 on the client for receiving and then initiate asynchronous reception.

Sample code: [VBDiscovery.cs] /// Local port private const int LOCAL_PORT = 52221; /// /// Callback function when window is shown. /// Bind the receive port and start asynchronous reception. /// private void VBDiscoveryViewer_Shown(object sender, EventArgs e) { localUdpSocket = new System.Net.Sockets.UdpClient(LOCAL_PORT); localUdpSocket.BeginReceive(ReceiveCallback, localUdpSocket); }

32

Sample code 2 [Transmission processing: send discovery message] Broadcast a discovery message to UDP port 52220.

Command: [Discovery message example] MV-SEARCH * HTTPU

ST: VB

Sample code: [VBDiscovery.cs] /// Broadcast address private const string BROADCAST_ADDRESS = "192.168.0.255"; *1 /// UDP port private const int UDP_PORT = 52220; /// /// Callback function when Discover button is pressed. /// Broadcast the discovery message. /// private void searchButton_Click(object sender, EventArgs e) { receiveMessageText.Clear(); String sendMessage = "MV-SEARCH * HTTPU\r\nST: VB"; Encoding asciiEncoder = Encoding.ASCII; byte[] sndBytes = asciiEncoder.GetBytes(sendMessage); // 1: Send discovery message. localUdpSocket.Send(sndBytes, sndBytes.Length, BROADCAST_ADDRESS, UDP_PORT); // Display discovery message. receiveMessageText.AppendText("Sended:\n" + sendMessage + "\n\n"); }

Note: *1 Change the address to reflect the local network before running the sample code.

33

Sample code 3 [Reception processing: receive response message] Asynchronously receive a discovery response message from a camera on UDP port 52221.

Response: [Response message] HTTPU 200 OK LOCATION: /-wvhttp-01-/GetCameraServerInfo SERVER: VB-S30D/1.1.0 ST: VB PORT: 80

Sample code: [VBDiscovery.cs] /// /// Callback function for asynchronous reception on UDP client socket. /// Receive response message from camera. /// private void ReceiveCallback(IAsyncResult asyncResult) { if (localUdpSocket.Client != null) { Encoding asciiEncoder = Encoding.ASCII; IPEndPoint ipAny = new System.Net.IPEndPoint(System.Net.IPAddress.Any, LOCAL_PORT); // 2: Receive response message. Byte[] rcvBytes = localUdpSocket.EndReceive(asyncResult, ref ipAny); string rcvMessage = asciiEncoder.GetString(rcvBytes); this.Invoke(new MethodInvoker(delegate { // Display response message. receiveMessageText.AppendText("Received: " + ipAny.ToString() + "\n" + rcvMessage.ToString() + "\n"); })); // Resume asynchronous reception localUdpSocket.BeginReceive(ReceiveCallback, localUdpSocket); } }

34

7.1.1.2 Running the Scenario

Running the scenario [Discovery] Start the sample application and try sending the discovery message and receiving the camera response messages.

Step 1 Start the sample application. Step 2 Press the Discover button. Make sure that there are responses from the

cameras connected to the local network, and that the response messages are displayed in the sample application.

35

7.2 Camera Control 7.2.1 Operating the Camera [Acquiring Control] When multiple clients try to operate the camera at the same time, a conflict occurs, and the results might not be as intended. To prevent these conflicts, the WebView HTTP protocol introduces the concept of “camera control privileges” by which only the client that has acquired authority can operate the camera.

□ Camera Control Privileges Camera control privileges are acquired and released by the following procedure: - Clients obtain camera control privileges in order to operate the camera. If a client is

able to obtain control privileges, it will be allowed to operate the camera for a fixed period of time.

- If a client already has control privileges, other clients can wait in a queue for their turn to be granted control privileges.

- If no clients are waiting for control privileges, it is possible to retain privileges beyond the fixed time period. Control privileges can transfer to another client when the time expires, or a client can relinquish control privileges on its own.

To implement the concept behind camera control privileges, which is that a client with control privileges can operate the camera, the WebView HTTP protocol uses the mechanism known as “sessions” in order to identify clients.

□ Sessions - When a session is generated, a unique identifier called a “session ID” is assigned to a

client. - The client identifies itself to the camera by giving a “session ID” as a parameter to the

WebView HTTP protocol command. - In order to create a session to control the camera, the client must acquire camera

control privileges.

Each session has a “priority” value. Camera control privileges can be acquired preferentially by a session with higher priority. For example, when a session with priority 10 claims camera control privileges that are held by a session with priority 5, the session with priority 10 will immediately gain the privileges. Conversely, it cannot take camera control privileges from a session with priority 20. In addition, when a priority 0 session has time remaining on its control privileges, it cannot be stripped of its privileges during this time by a session with the same priority of 0. The session that was unable to seize camera control privileges is given a waiting time corresponding to the time remaining in the other session’s privileges.

36

□ Priority - The priority is specified when a session is created. - You can specify 0 as the priority, or a value from 5 to 50. - A priority of 0 does not require user authentication. - A priority of 5 to 50 requires authentication by an authorized user.

Note: Refer to the following for further details related to camera control privileges, sessions, priorities, and user authentication. “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.1 Client and Session Management ” “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.2 User Type of User Access Control Function ” “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.3 Privilege Settings and Session Priority ” “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.4 Creating a Session and Applied Restrictions ”

Note: This example was created based on ‘6.3 First WebView Application ’.


Scenario:

This sample code demonstrates an application that can create a session with a specified priority and acquire camera control privileges. The application lets you acquire camera control privileges in order to perform pan, tilt, and zoom operations, so if there is more than one client, you can experiment with behaviors such as waiting for or seizing camera control privileges based on differences in priority.



Guest User Camera Control Yes Video Distribution Yes

Create an authorized user on the Setting Page.

37


Before trying out the scenario, make sure the installation status is as indicated below. At least one camera is installed on the local network. The camera is not being accessed by another application with control

privileges, such as the Admin Viewer.


No.

Keyword Explanation

†1 General session A session with priority 0 that does not require authentication. See “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.3 Privilege Settings and Session Priority ”

†2 Privileged session A session with a priority from 5 to 50. See “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.3 Privilege Settings and Session Priority ”

†3 Management session

A session with no priority specified that takes precedence over privileged sessions. See “Network Camera Server WebView HTTP Protocol Specifications 5.1.4.3 Privilege Settings and Session Priority ”

†4 open.cgi The session creation command. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.1.1 Creating a Session [open.cgi] ”

†5 Session-based One of the ways of running info.cgi. “Network Camera Server WebView HTTP Protocol Specifications 5.2.3.1 Information Acquisition [info.cgi] ”

†6 claim.cgi Command to claim camera control privileges. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.1.3 Camera Control Privilege Request [claim.cgi] ”

†7 yield.cgi Command to yield camera control privileges. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.1.4 Releasing Camera Control Privileges [yield.cgi] ”

†8 close.cgi Command to discard a session. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.1.2 Closing a Session [close.cgi] ”

38


Fig. 7-5 Authentication Dialog Box

- When the application starts, an authentication dialog box is displayed. - Select a session priority from the [Priority] drop-down list. - To use a general session†1, press [OK] without making a selection, and the

application will start directly. - If a privileged session†2 is selected, an authorized user name and password

must be entered. - If a management session†3 is selected, an administrator user name and

password must be entered. - If user authentication fails, the authentication dialog box is displayed again. If

you want to escape the dialog box, for example to correct the IP address of the camera, press the [Cancel] button to exit the application.

39

Fig. 7-6 [Operating the Camera [Acquiring Control]] Sample Application

- The application starts working and the video from the camera appears. - If you press the [Control Privileges] button labeled “Acquire control privileges”,

it requests control privileges and the button turns green. In the case of a general session, it displays the remaining time and begins counting down. If the client must wait for control privileges, the button turns pale yellow, and then turns green once control privileges are able to be acquired. In this case, it displays the required waiting time and counts down until control privileges become available.

- Once you have gained control privileges, you will be able to manipulate the scroll bars to pan, tilt, and zoom.

- If you press the [Control Privileges] button labeled “Yield control privileges”, camera control privileges are released, and the button is grayed out. This also happens if another client obtains camera control privileges.

40

The following is an overview of the operation of the sample application for running the scenario. It omits the parts that are the same as ‘6.3 First WebView Application ’.

Fig. 7-7 [Operating the Camera [Acquiring Control]] Sample Application Operation Overview

The following sections describe the sample application program by following an outline of how the program works.



41

7.2.1.1 Initial Processing of the Application The initial processing of the application includes authentication input, creation of credentials, session creation, initial information acquisition, thread creation, starting an image acquisition timer, and starting a control privilege timer for displaying the time remaining or waiting time.

Sequence:

Fig. 7-8 [Operating the Camera [Acquiring Control]] Application Initial Processing Sequence

42

Sample code 1 [Initial processing: create session] Display an authentication dialog box and create a session using the credentials entered by the user.

Command: [Session creation example (specifying the priority)] http://192.168.0.1/-wvhttp-01-/open.cgi?s.priority=10

Command: [Session creation example (specifying a management session)] http://192.168.0.1/-wvhttp-01-/open.cgi?type=admin

Sample code: [WvCameraViewer.cs] /// /// Callback function when window is shown. /// Perform authentication and start communication with camera. /// private void WvCameraViewer_Shown(object sender, EventArgs e) { while (!sessionCreated) { Cursor.Current = Cursors.Default; // 1: Enter credentials. authDialog.ShowDialog(this); if (authDialog.DialogResult == DialogResult.Cancel) { MessageBox.Show(this, "Authentication procedure has been canceled.\n" + "Please quit the application.", "", MessageBoxButtons.OK, MessageBoxIcon.Exclamation); return; } Cursor.Current = Cursors.WaitCursor; // Set information entered by user. httpSession.CreateCredentials(authDialog.Priority, authDialog.UserName, authDialog.Password); priorityLabel.Text = httpSession.GetAuthLevelString(); // 2: Create the session. sessionCreated = httpSession.CreateSession(); if (!sessionCreated) MessageBox.Show(this, "Could not connect to camera.", "Connection failure", MessageBoxButtons.OK, MessageBoxIcon.Error); } ･････

The following code handles session creation. It runs open.cgi†3 and extracts the session ID from the response.

43

Sample code: [WvHTTPSession.cs：CreateSession()] /// /// Create WebView HTTP session. /// public bool CreateSession() { // Create the URL of the command. string command = "open.cgi"; if (!string.IsNullOrEmpty(priority)) { if (priority.Equals("admin")) command += ("?type=admin"); *1 else command += ("?priority=" + priority); *2 } // Run the command. string httpResponse = SendCommand(command); // Extract session ID from response. if (!string.IsNullOrEmpty(httpResponse)) { Match m = Regex.Match(httpResponse, "s:=(.+)"); *3 if (m.Success) { sessionID = m.Groups[1].Value; // Session created successfully return true; } } // Failed to create session return false; }

Note: *1 In the case of a management session, “type=admin” is specified. *2 In the case of a privileged session, the priority is set using “priority=”. *3 From the response to the open.cgi command, extract the session ID from the line

matching “s:=”. E.g. “s:=8a96-c09b18f0” ⇒ “8a96-c09b18f0”

Response: [Example of response to session creation] s:=8a96-c09b18f0 s.origin:=192.168.0.1:80 s.duration:=0 s.priority:=0 v:=jpg:1920x1080:3:30000

Sample code 2 [Initial processing: create thread and timers] When a session is created, it creates a thread for executing info.cgi, an image acquisition timer, and a control privilege timer for indicating the remaining time or waiting time.

44

Note: In order to update the UI to reflect changes to control privileges and the direction of the camera, this sample code executes info.cgi on a session basis†4. The session-based info.cgi returns all the information on its initial execution, and then subsequently returns only differential information when there is a change in the status of the camera. If this were done on the UI thread, the UI would be unusable while waiting for the responses. Session-based information acquisition therefore requires creation of a thread. In addition, a timer is used to keep track of the remaining time and waiting time for control privileges, since these cannot be monitored with the information acquisition command.

Sample code: [WvCameraViewer.cs] ･････ // Register event processing function. httpSession.OnGetNotice += new WvGetNoticeCallback(ProcessNoticeByThread); *1 // 3: Refresh scroll bars etc. string httpResponse = httpSession.SendCommand("info.cgi"); ProcessNotice(httpResponse); *1 // 4: Initiate event loop. httpSession.StartEventLoop(); // 5: Start timer for image acquisition. imageTimer = new System.Windows.Forms.Timer(); imageTimer.Interval = IMAGE_INTERVAL; imageTimer.Tick += new EventHandler(ImageTimerTick); imageTimer.Enabled = true; // 5: Start control privileges timer for updating remaining time/waiting time. controlTimer = new System.Windows.Forms.Timer(); controlTimer.Interval = 1000; controlTimer.Tick += new EventHandler(ControlTimerTick); controlTimer.Enabled = true; // Enable operation of control. this.Enabled = true; Cursor.Current = Cursors.Default; }

Note: *1 Responses from info.cgi are handled by the ProcessNotice function both upon

initialization and when it is polled. However, due to a C# restriction that processing must be mediated by the Invoke function in order to update the UI from a thread outside the UI thread, the polling callback specifies the wrapper function ProcessNoticeByThread, which is mediated by the Invoke function.

45

Sample code: [WvCameraViewer.cs：ProcessNoticeByThread()] /// /// Wrapper function for using ProcessNotice function from non-UI thread. /// void ProcessNoticeByThread(string notice) { WvGetNoticeCallback getNotice = new WvGetNoticeCallback(ProcessNotice); this.Invoke(getNotice, new object[] { notice, }); }

Sample code: [WvHTTPSession.cs：StartEventLoop()] /// /// Start polling info.cgi for camera information. /// public void StartEventLoop() { thread = new Thread(new ThreadStart(GetNotice)); thread.Start(); }

Sample code: [WvHTTPSession.cs：GetNotice()] /// /// Thread processing for info.cgi. /// Listen for stream response, and notify the results to the window. /// private void GetNotice() { while (thread != null) { string notice = SendCommand("info.cgi"); if (OnGetNotice != null) OnGetNotice(notice); } }

Note: This processing is covered in greater detail in the next section.

46

7.2.1.2 Information Acquisition Processing In order to monitor the granting and revocation of control privileges and pan, tilt, and zoom operations, info.cgi is polled on a session basis.

Note: When info.cgi is executed on a session basis, the camera waits without returning a response if there is no change in the state of the camera. When executing polling, there is no need to implement a polling interval because the camera returns a response when a change occurs.

Sequence:

Fig. 7-9 [Operating the Camera [Acquiring Control]] Information Acquisition Processing Sequence

47

Sample code 1 [Information acquisition processing: information acquisition thread] Execute info.cgi with a session ID specified, and delegate responses to the callback function.

Command: [Information acquisition example (session-based)] http://192.168.0.1/-wvhttp-01-/info.cgi?s=8a96-c09b18f0

Sample code: [WvHTTPSession.cs] /// /// Thread processing for info.cgi. /// Listen for stream response, and notify the results to the window. /// private void GetNotice() { while (thread != null) { string notice = SendCommand("info.cgi"); if (OnGetNotice != null) OnGetNotice(notice); } }

48

Sample code 2 [Information acquisition processing: response processing callback] Process the response from info.cgi and update the scroll bars and the camera control privileges display.

Sample code: [WvCameraViewer.cs] /// /// Process camera information (response from info.cgi) and update UI. /// void ProcessNotice(string httpResponse) { ・・・ if (line.StartsWith("c.1.pan:=")) *1 *2 pan = GetIntValue(line); else if (line.StartsWith("c.1.tilt:=")) tilt = GetIntValue(line); else if (line.StartsWith("c.1.zoom:=")) zoom = GetIntValue(line); else if (line.StartsWith("c.1.pan.limit.min:=")) panScrollBar.Minimum = GetIntValue(line); else if (line.StartsWith("c.1.pan.limit.max:=")) panScrollBar.Maximum = GetIntValue(line); else if (line.StartsWith("c.1.tilt.limit.max:=")) tiltScrollBar.Maximum = GetIntValue(line); else if (line.StartsWith("c.1.tilt.limit.min:=")) tiltScrollBar.Minimum = GetIntValue(line); else if (line.StartsWith("c.1.zoom.limit.min:=")) zoomScrollBar.Minimum = GetIntValue(line); else if (line.StartsWith("c.1.zoom.limit.max:=")) zoomScrollBar.Maximum = GetIntValue(line); else if (line.StartsWith("s.control:=enabled") || *2 line.StartsWith("s.control==enabled")) { controlTime = GetSecond(line); *3 ProcessControlTime(ControlRightConditions.Enable); } else if (line.StartsWith("s.control:=disabled") || line.StartsWith("s.control==disabled")) { controlTime = GetSecond(line); ProcessControlTime(ControlRightConditions.Disable); } else if (line.StartsWith("s.control:=waiting") || line.StartsWith("s.control==waiting")) { controlTime = GetSecond(line); ProcessControlTime(ControlRightConditions.Wait); }

} // Update pan, tilt, and zoom positions in scroll bars. if (pan != int.MaxValue) panScrollBar.Value = pan; if (tilt != int.MaxValue) tiltScrollBar.Value = tiltScrollBar.Maximum + tiltScrollBar.Minimum - tilt; if (zoom != int.MaxValue) zoomScrollBar.Value = zoom; }

Note: *1 There is no guarantee that the pan, tilt, and zoom values reported by info.cgi will

exactly match the values set using control.cgi.

49

*2 The response from the session-based info.cgi exhibits two patterns, “ := ” and “ == ”, depending on the cause of the change in the value. The pattern “ == ” indicates that the value was changed by the local session command. The pattern “ := ” indicates the initial response from info.cgi, or that the value was changed by something outside the local session. Because the positions of the scroll bars in the UI are already moving to the values specified in the local command during UI operations, when the values from info.cgi differ from the control results, only those specified with := need to be dealt with. This also has the effect of suppressing unwanted scroll bar behavior, such as when the scroll button is hit continuously.

*3 If control privileges were acquired, or are being waited for, the line will have the format “s.control:=xxxx:time”, and the remaining time or waiting time is extracted. E.g. “s.control:=enabled:20000” ⇒ 20000

50

7.2.1.3 Control Privilege Management Processing When you press the [Control Privileges] button, control privileges are either claimed or yielded, depending on their current state. Whether control privileges were gained or lost is determined from the results of information acquisition, because the acquisition/release and deprivation of control privileges are managed centrally.

Sequence:

Fig. 7-10 [Operating the Camera [Acquiring Control]] Control Privilege Management Processing

Sequence

Note: In the above sequence, note that the results from the claim.cgi command itself are reported using the pattern “ == ”, while the notification that control privileges were stripped uses the format “ := ”.

51

Sample code 1 [Control privilege management processing: claim/yield control privileges] This sample code shows the callback function for the [Control Privileges] button. It runs claim.cgi†6 or yield.cgi†7, depending on the current state of control privileges.

Command: [Example of claiming camera control privileges] http://192.168.0.1/-wvhttp-01-/claim.cgi?s=8a96-c09b18f0

Command: [Example of yielding camera control privileges] http://192.168.0.1/-wvhttp-01-/yield.cgi?s=8a96-c09b18f0

Sample code: [WvCameraViewer.cs] /// /// Callback function when the control privileges acquisition button is pressed. /// private void claimButton_Click(object sender, EventArgs e) { if (controlRight == ControlRightConditions.Disable) httpSession.SendCommand("claim.cgi"); else httpSession.SendCommand("yield.cgi"); }

Response: [Example of notification of acquisition of camera control privileges] s.control:=enabled:20000

52

7.2.1.4 Termination Processing Discard the session upon termination of the application.

Sample code 1 [Termination processing: discard session] Run close.cgi†8, specifying the session ID as the argument.

Command: [Discard session example] http://192.168.0.1/-wvhttp-01-/close.cgi?s=8a96-c09b18f0

Sample code: [WvCameraViewer.cs] /// /// Callback function when window is closed. /// Discards session. /// private void WvCameraViewer_FormClosing(object sender, FormClosingEventArgs e) { if (sessionCreated) { imageTimer.Enabled = false; httpSession.OnGetNotice -= new WvGetNoticeCallback(ProcessNoticeByThread); httpSession.SendCommand("close.cgi"); } authDialog.Dispose(); httpSession.Dispose(); }

53

7.2.1.5 Running the Scenario Try out the scenario after checking the camera connection and confirming that the camera is not being accessed by another application with control privileges, such as the Admin Viewer.

Running the scenario [General session: single client] Start the sample application, and try panning, tilting and zooming the camera in the general session. Step 1 Start the sample application and choose [General session] in the

authentication input. Step 2 Obtain camera control privileges and confirm that it is possible to perform

pan, tilt, and zoom operations. Step 3 Yield camera control privileges and confirm that it is not possible to

perform pan, tilt, and zoom operations.

Running the scenario [General session: multiple clients] Experiment with operations by multiple clients. Start two sample applications connected to the same camera and operate them in general sessions. Let [APP1] and [APP2] be the two sample applications. Step 1 Start [APP1] and [APP2], and choose [General session] in the

authentication input. Verify that the same video appears in both [APP1] and [APP2].

Step 2 Obtain camera control privileges in [APP1] and try the pan, tilt, and zoom operations. Verify that the video and scroll bar positions in [APP2] reflect the operations in [APP1].

Step 3 Make sure the remaining control time in [APP1] is 0 seconds, and then try obtaining camera control privileges in [APP2]. Verify that camera control privileges are immediately transferred to [APP2].

Step 4 Try to obtain camera control privileges in [APP2] while there is control time remaining in [APP1]. Confirm that the control privileges button in [APP2] switches to [Waiting for control privileges], and that when the remaining control time in [APP1] and the waiting time in [APP2] are at 0 seconds, camera control privileges are transferred to [APP2].

Step 5 Try to obtain camera control privileges in [APP2] while there is control time remaining in [APP1]. Make sure [APP2] shows [Waiting for control privileges], and then press the control privileges button in [APP1] to release the control privileges. The released camera control privileges are then transferred to [APP2].

54

Running the scenario [Privileged session: multiple clients] Start two sample applications connected to the same camera and operate them in privileged sessions. Let [APP1] and [APP2] be the two sample applications. Step 1 Start [APP1] and [APP2], and select [Privileged session [10]] in the

authentication input for [APP1] and [Privileged session [20]] for [APP2]. Step 2 Obtain camera control privileges in [APP1]. Try to obtain camera control

privileges in [APP2] while there is control time remaining in [APP1]. Confirm that camera control privileges are transferred immediately between the privileged sessions with no waiting.

Step 3 Obtain camera control privileges in [APP2]. Try to obtain camera control privileges in [APP1], and verify that camera control privileges are not transferred regardless of whether there is control time remaining in [APP2]. Verify that between privileged sessions, the higher-priority session maintains camera control privileges.

55

7.2.2 Operating the Camera [Pan-Tilt-Zoom] The WebView HTTP protocol offers other ways to pan, tilt, and zoom besides the ones tried in ‘6.3 First WebView Application ’. It also lets you specify the speed at which the camera works when panning, tilting, and zooming.

□ Pan, tilt, and zoom operations

The WebView HTTP protocol offers the following methods for performing pan, tilt, and zoom operations.

- Absolute positioning Specify the angle of the pan, tilt, or zoom.

Fig. 7-11 Absolute Positioning

Specify the positions of the → and ↑ arrows as angles in units of 0.01 degrees.

56

- Differential positioning Specify the angle of the pan, tilt, or zoom as a displacement from its current position.

Fig. 7-12 Differential Positioning

Specify the displacements of the → and ↑ arrows as angles in units of 0.01 degrees.

- Relative positioning (percentage) Specify the position of the pan, tilt, or zoom in a range of ±100, with 0 as the current position.

Fig. 7-13 Relative Positioning (percentage)

The relative position on the display image can be specified. For example, if you specify pan +100, and tilt +100, the upper right of the image will become the center position.

- Directional You can specify the direction of movement of the pan, tilt, or zoom. The movement ends when stop is specified or when the end of the control range is reached.

57

□ Pan, tilt, and zoom speed The following two types of operating speed are used:

- Positional speed Speed of absolute positioning, differential positioning, and relative positioning (percentage).

- Directional speed Speed when specifying direction.

Note: The pan-tilt-zoom operating speed becomes a set value belonging to the session. The speed can be changed without affecting the other clients and without obtaining control privileges.

Note: This example was created based on ‘7.2.1 Operating the Camera [Acquiring Control] ’.


Scenario:

This sample code demonstrates an application that performs pan, tilt, and zoom operations in a specified direction. Because the operating speed can also be changed directionally, you can experiment with differences in pan, tilt, and zoom operations at specified positions and changes to the operating speed under multiple clients.


Before trying out the scenario, make sure the camera settings are configured as indicated below. Check the values of the camera settings on the Setting Page. [Server] Video Server

Camera Control Time (sec.) 20

[User Restrictions] User Authority Guest User

Camera Control Yes Video Distribution Yes

58


Before trying out the scenario, make sure the installation status is as indicated below. At least one camera is installed on the local network. The camera is not being accessed by another application with control

privileges, such as the Admin Viewer.


No.

Keyword Explanation

†1 Stream format One of the execution formats for info.cgi in which the type=stream parameter is specified. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.3.1 Information Acquisition [info.cgi] ”

†2 c.1.pan.speed.dir A parameter of control.cgi that changes the speed of panning when the direction is specified. Replace pan with tilt or zoom to change the respective tilt and zoom speeds. See “Network Camera Server WebView HTTP Protocol Specifications 5.2.4.1 Camera Control [control.cgi] ”


Fig. 7-14 [Operating the Camera [Pan-Tilt-Zoom]] Sample Application

59

Note: An authentication dialog box is displayed at startup, just as in ‘7.2.1 Operating the Camera [Acquiring Control] ’.

- The application starts working and the video from the camera appears. - The functions of the control privileges button are the same as in ‘7.2.1

Operating the Camera [Acquiring Control] ’. - Once you have gained control privileges, you can perform the following

operations: Pan, tilt, and zoom operations by absolute positioning using the scroll bars. Panning to the left or right using the [L] and [R] buttons. Movement

continues while you hold down the button and stops when you release the button.

Tilting up or down using the [U] and [D] buttons. Zooming to telephoto or wide-angle using the [T] and [W] buttons.

- You can change the directional operating speed by selecting from a drop-down list of pan-tilt-zoom speeds.

- The label in auto flip status indicates the current flip status of the camera.

Note: Auto flip is the function for inverting the image automatically when the camera tilt angle approaches -100° during camera tilt operation. For details on auto flip, refer to the following. “Network Camera Server WebView HTTP Protocol Specifications 5.2.4.1 Camera Control [control.cgi] ”

The following is an overview of the operation of the sample application for running the scenario. It omits the parts that are the same as ‘7.2.1 Operating the Camera [Acquiring Control] ’.

Fig. 7-15 [Operating the Camera [Pan-Tilt-Zoom]] Sample Application Operation Overview

60

The following sections describe the sample application program by following an outline of how the program works.



61

7.2.2.1 Information Acquisition Processing To monitor the granting and revocation of control privileges, pan, tilt, and zoom operations, and flip status, info.cgi is executed on a session basis using the stream format†1.

Note: When executing info.cgi in the stream format rather than the polling format, a single command is executed, and a response is returned whenever the camera state changes. This sample is an example of an implementation that uses the stream format.

Sequence:

Fig. 7-16 [Operating the Camera [Pan-Tilt-Zoom]] Information Acquisition Processing Sequence

62

Sample code 1 [Information acquisition processing: information acquisition thread] Execute the info.cgi command in stream format, extract the response, and delegate to the response processing callback function.

Command: [Information acquisition example (session-based)] http://192.168.0.1/-wvhttp-01-/info.cgi?s=8a96-c09b18f0&type=stream

63

Sample code: [WvHTTPSession.cs:GetNotice()] /// /// Thread processing for info.cgi. /// Listen for stream response, and notify the results to the window. /// private void GetNotice() { try { // Create URL of command and run it. string command = server + "info.cgi?s=" + sessionID + "&type=stream"; HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(command); if (credentials != null) request.Credentials = credentials; HttpWebResponse response = (HttpWebResponse)request.GetResponse(); StreamReader reader = new StreamReader(response.GetResponseStream()); // Extract required part from response and notify registered delegate. int contentLength = -1; int responseLength = -1; bool effectiveContent = false; string notice = string.Empty; while (thread != null) { string line = reader.ReadLine(); if (line == null ) break; if (effectiveContent) { notice += (line + "\r\n"); responseLength += (line.Length + "\n".Length); if (responseLength >= contentLength) { if (OnGetNotice != null) OnGetNotice(notice); notice = string.Empty; contentLength = -1; responseLength = -1; effectiveContent = false; } } if (line.StartsWith("Content-Length: ")) *1 contentLength = int.Parse(line.Replace("Content-Length: ", "")); else if (line.StartsWith("timestamp=")) { responseLength += ("\n".Length + line.Length + "\n".Length); effectiveContent = true; } } } catch (Exception) { } }

Note: *1 Because the size of the response is stored in the form “Content-Length:

”, it reads the post-extraction size and size part of the response and delegates to the callback function. E.g. “Content-Length: 128” ⇒ 128

64

Note: Exception handling has been omitted from the code samples in this chapter. Normally, if the connection is lost or an error occurs, the information acquisition thread is terminated and must be re-executed.

Sample code 2 [Information acquisition processing: response processing callback] This is the callback function for processing responses from info.cgi. This sample code adds processing for updating the drop-down list by obtaining the pan-tilt-zoom operating speed, and updating the label by identifying the flip status.

Sample code: [WvCameraViewer.cs:ProcessNotice()] void ProcessNotice(string httpResponse) { ･････ StringReader reader = new StringReader(httpResponse); while (true) { ･････ else if (line.StartsWith("c.1.pan.speed.dir:=")) *1 panSpeedCombo.SelectedIndex = httpSession.GetPanDirectionSpeedIndex(GetIntValue(line)); else if (line.StartsWith("c.1.tilt.speed.dir:=")) tiltSpeedCombo.SelectedIndex = httpSession.GetTiltDirectionSpeedIndex(GetIntValue(line)); else if (line.StartsWith("c.1.zoom.speed.dir:=")) zoomSpeedCombo.SelectedIndex = httpSession.GetZoomDirectionSpeedIndex(GetIntValue(line)); else if (line.StartsWith("c.1.eflip:=")) *2 { // If auto flip status is supported, enable label. autoFlipGroup.Enabled = true; // Update auto flip status. string eflipValue = GetValue(line); if (eflipValue == "on") autoFlipLabel.Text = "Auto flip On"; else if (eflipValue == "off") autoFlipLabel.Text = "Auto flip Off"; } } ･････ }

Note: *1 When you select a speed using the UI, the drop-down list is updated with the

results, so here it checks only the patterns “ := ” in the initial response from info.cgi, in order to set the values set in the startup session to the drop-down list.

*2 Use this determination to identify the auto flip status.

65

Note: During pan-tilt-zoom operations in the specified direction, the values are not reported until the operations have stopped.

66

7.2.2.2 Pan-Tilt-Zoom Processing [Directional] Run control.cgi to perform directional pan-tilt-zoom operations and specify the speed.

Sequence:

Fig. 7-17 [Operating the Camera [Pan-Tilt-Zoom]] Pan-Tilt-Zoom Processing Sequence

Note: This sequence describes only panning in a specified direction. The tilt and zoom sequences are similar.

Sample code 1 [Pan-tilt-zoom processing: run command] These are the callback functions for the buttons that do pan-tilt-zoom operations in a specified direction. The command control.cgi is executed when the button is pressed and when it is released.

67

In the case of panning, hold down the [L] or [R] button to pan the camera to the “left” or “right”. Release the button to “stop” panning. Only panning is described here. Tilting (with the [U] and [D] buttons) and zooming (with the [T] and [W] buttons) behave similarly.

Command: [Directional panning [left] example] http://192.168.0.1/-wvhttp-01-/control.cgi?s=8a96-c09b18f0&c.1.pan=left

Command: [Directional panning [stop] example] http://192.168.0.1/-wvhttp-01-/control.cgi?s=8a96-c09b18f0&c.1.pan=stop

Sample code: [WvCameraViewer.cs] /// /// Callback function when right pan button is pressed. /// private void rightButton_MouseDown(object sender, MouseEventArgs e) *1 { // 1: Specify "right" to move to the right. httpSession.SendCommand("control.cgi?c.1.pan=right"); } /// /// Callback function when right pan button is released. /// private void rightButton_MouseUp(object sender, MouseEventArgs e) { // 2: Specify "stop" to stop. httpSession.SendCommand("control.cgi?c.1.pan=stop"); } /// /// Callback function when left pan button is pressed. /// private void leftButton_MouseDown(object sender, MouseEventArgs e) { // Specify "left" to move to the left. httpSession.SendCommand("control.cgi?c.1.pan=left"); } /// /// Callback function when left pan button is released. /// private void leftButton_MouseUp(object sender, MouseEventArgs e) { // Specify "stop" to stop. httpSession.SendCommand("control.cgi?c.1.pan=stop"); }

Note: *1 For the sake of simplicity, this sample code uses only MouseDown/MouseUp UI

events to manipulate the pan-tilt-zoom direction. KeyDown events and similar events could also be implemented, but non-mouse events are omitted here because C# offers no way to detect a button press independent of the means, such as mouse/keyboard.

68

Sample code 2 [Pan-tilt-zoom speed: run command] This is the callback function for the drop-down list for selecting the speed of the directional pan-tilt-zoom operations. It runs control.cgi to change the directional operating speed.

Note: The choices in the drop-down list are [Fast], [Normal], and [Slow], but in this example the speed is converted to a defined value and executed as a parameter of control.cgi. Only changes to the pan speed (c.1.pan.speed.dir†2) are described here. The same processing is done for the tilt speed and zoom speed.

Command: [Example of specifying the speed for directional panning] http://192.168.0.1/-wvhttp-01-/control.cgi?s=8a96-c09b18f0& c.1.pan.speed.dir=12000

Sample code: [WvCameraViewer.cs] /// /// Callback function when selecting directional panning speed in drop-down list. /// private void panSpeedCombo_SelectionChangeCommitted(object sender, EventArgs e) { // 3: Execute change of pan speed. httpSession.SendCommand("control.cgi?c.1.pan.speed.dir=" + httpSession.GetPanDirectionSpeedValue(panSpeedCombo.SelectedIndex)); }

69

Sample code: [WvHTTPSession.cs：GetPanDirectionSpeedValue()] /// List for specifying directional panning speed public enum PanDirectionSpeedMode { Fast = 0, Normal = 1, Slow = 2 } /// List of speed values for directional panning public enum PanDirectionSpeedList { FastValue = 12000, FastBorder = 9500, NormalValue = 7000, NormalBorder = 4000, SlowValue = 1000 } /// /// Convert directional panning index value to speed value. /// public int GetPanDirectionSpeedValue(int panDirectionSpeedIndex) { if (panDirectionSpeedIndex == (int)PanDirectionSpeedMode.Fast) return (int)PanDirectionSpeedList.FastValue; else if (panDirectionSpeedIndex == (int)PanDirectionSpeedMode.Normal) return (int)PanDirectionSpeedList.NormalValue; else return (int)PanDirectionSpeedList.SlowValue; }

70

7.2.2.3 Running the Scenario Try out the scenario after confirming that the camera is not being accessed by another application with control privileges, such as the Admin Viewer.

Running the scenario [General session: single client] Start the sample application, and try panning, tilting and zooming the camera in the general session. Step 1 Start the sample application and choose [General session] in the

authentication input. Step 2 Acquire camera control privileges, and verify that directional pan, tilt, and

zoom operations can be performed only after you have gained control privileges.

Step 3 Experiment with positional and directional pan, tilt, and zoom operations, and check the differences in their behavior.

Step 4 Experiment with changing the directional pan, tilt, and zoom speed, and verify that the operating speed actually changes.

Step 5 Release camera control privileges, and verify that you can change the directional pan, tilt, and zoom speed.

Running the scenario [General session: multiple clients] Experiment with operations by multiple clients. Start two sample applications connected to the same camera and operate them in general sessions. Let [APP1] and [APP2] be the two sample applications. Step 1 Start [APP1] and [APP2], and choose [General session] in the

authentication input. Verify that the same video appears in both [APP1] and [APP2].

Step 2 Obtain camera control privileges in [APP1], and try out the directional pan, tilt, and zoom operations. Verify that the video and scroll bar positions in [APP2] reflect the operations in [APP1].

Step 3 Change the directional pan, tilt, and zoom speed in [APP1]. Verify that the speed of [APP2] does not change.

Step 4 Change the directional pan, tilt, and zoom speed in [APP2]. Verify that the speed of [APP1] does not change.

71

Running the scenario [Auto flip] Start the sample application, tilt the camera, and check the auto flip operation in the general session. Use a camera that supports the auto flip function. Also, suspend the camera. Check the values of the auto flip settings on the Setting Page.

[Camera Settings] Camera Control Auto Flip Enable

Step 1 Start the sample application and choose [General session] in the authentication input.

Step 2 Acquire camera control privileges, and move the lens position so that auto flip turns off.

Step 3 Tilt the camera, and move the lens position until it is almost directly below (near -100°). Check that auto flip turns on and the image is inverted.

72

7.2.3 Operating the Camera [Various Correction Settings]

This sample code lets you use the WebView HTTP protocol to experiment with changes to settings, such as corrections to the video. When changing settings, some items cannot be ch