ONVIF Receiver Service Specification

ONVIF™
–1–
Receiver Spec. – Ver. 2.2.1
ONVIF™
Receiver Service Specification
Version 2.2.1
December, 2012
ONVIF™
–2–
Receiver Spec. – Ver. 2.2.1
 2008-2011 by ONVIF: Open Network Video Interface Forum Inc.. All rights reserved.
Recipients of this document may copy, distribute, publish, or display this document so long as this
copyright notice, license and disclaimer are retained with all copies of the document. No license is
granted to modify this document.
THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND
THEIR AFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS
DOCUMENT ARE SUITABLE FOR ANY PURPOSE; OR THAT THE IMPLEMENTATION OF SUCH
CONTENTS WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER
RIGHTS.
IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE
FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL
DAMAGES, ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS
DOCUMENT, WHETHER OR NOT (1) THE CORPORATION, MEMBERS OR THEIR AFFILIATES
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR (2) SUCH DAMAGES
WERE REASONABLY FORESEEABLE, AND ARISING OUT OF OR RELATING TO ANY USE OR
DISTRIBUTION OF THIS DOCUMENT. THE FOREGOING DISCLAIMER AND LIMITATION ON
LIABILITY DO NOT APPLY TO, INVALIDATE, OR LIMIT REPRESENTATIONS AND WARRANTIES
MADE BY THE MEMBERS AND THEIR RESPECTIVE AFFILIATES TO THE CORPORATION AND
OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OF THE CORPORATION.
ONVIF™
–3–
Receiver Spec. – Ver. 2.2.1
CONTENTS
1
Scope
4
2
Normative references
4
3
Terms and Definitions
4
3.1
Definitions........................................................................................................................ 4
3.2
Abbreviations .................................................................................................................. 4
4
Overview
4
4.1.1 Synchronization Points ............................................................................................... 5
5
Service
6
5.1
Persistence...................................................................................................................... 6
5.2
Receiver modes .............................................................................................................. 6
5.3
Receiver commands ....................................................................................................... 6
5.3.1 Get Receivers ............................................................................................................. 6
5.3.2 Get Receiver ............................................................................................................... 7
5.3.3 Create Receiver .......................................................................................................... 7
5.3.4 Delete Receiver .......................................................................................................... 8
5.3.5 Configure Receiver ..................................................................................................... 8
5.3.6 SetReceiverMode ....................................................................................................... 8
5.3.7 GetReceiverState ....................................................................................................... 9
5.4
Capabilities ...................................................................................................................... 9
5.5
Events ........................................................................................................................... 10
5.5.1 ChangeState ............................................................................................................. 10
5.5.2 Connection Failed ..................................................................................................... 10
5.6
Service specific data types............................................................................................ 10
5.6.1 • Receiver ................................................................................................................ 10
5.6.2 • ReceiverConfiguration........................................................................................... 11
5.6.3 • ReceiverStateInformation...................................................................................... 11
5.7
Service specific fault codes ........................................................................................... 12
Annex A. Revision History
13
ONVIF™
1
–4–
Receiver Spec. – Ver. 2.2.1
Scope
This document defines the web service interface for configuration a network streaming
receiver. The receiver is used for displaying and recording audio video streams. Additionally
the associated events are defined.
Web service usage is outside of the scope of this document. Please refer to the ONVIF core
specification.
2 Normative references
ONVIF Core Specification
<http://www.onvif.org/specs/core/ONVIF-Core-Specification-v220.pdf>
ONVIF DeviceIO Service Specification
<http://www.onvif.org/specs/srv/io/ONVIF-DeviceIo-Service-Spec-v220.pdf>
ONVIF Streaming Specification
<http://www.onvif.org/specs/stream/ONVIF-Streaming-Spec-v220.pdf>
3 Terms and Definitions
3.1 Definitions
Metadata
All streaming data except video and audio, including video analytics results, PTZ
position data and other metadata (such as textual data from POS applications).
3.2 Abbreviations
JPEG
MPEG-4
RTSP
4
Joint Photographic Expert Group
Moving Picture Experts Group - 4
Real Time Streaming Protocol
Overview
A receiver is an object that acts as an RTSP client endpoint. Receivers are used by other
services that consume media streams, such as the Display, Recording and Analytics Device
services. A receiver has a configuration that determines the RTSP endpoint to which it should
connect and the connection parameters it should use.
A receiver can operate in three distinct modes:
AlwaysConnect. The receiver attempts to maintain a persistent connection to the configured
endpoint.
NeverConnect. The receiver does not attempt to connect.
AutoConnect. The receiver connects on demand, as required by consumers of the media
streams.
A single receiver may be used by more than one consumer. For example, in order to record a
stream and also perform analytics on it, both a recording job and an analytics engine could be
attached to the same receiver. If the receiver uses the “Auto Connect” mode, it will connect
whenever either the recording job or the analytics engine is active, and disconnect when
neither of them are active.
Receivers may be created and deleted either manually, by calling the CreateReceiver and
DeleteReceiver operations in the Receiver Service, or automatically by other services. For
ONVIF™
–5–
Receiver Spec. – Ver. 2.2.1
example, if a recording job is created with the “AutoCreateReceiver” option, it will
automatically create and attach to a Receiver. Deleting the recording job will also delete the
receiver.
WSDL for this service is specified in http://www.onvif.org/onvif/ver10/receiver.wsdl.
Table 1: Referenced namespaces (with prefix)
Prefix
Namespace URI
env
http://www.w3.org/2003/05/soap-envelope
ter
http://www.onvif.org/ver10/error
xs
http://www.w3.org/2001/XMLSchema
tt
http://www.onvif.org/ver10/schema
trv
http://www.onvif.org/ver10/receiver/wsdl
4.1.1 Synchronization Points
Because receivers use RTSP addresses to specify the source of the stream, they do not
necessarily have access to the web services interface of the transmitter. This means that they
cannot use the SetSynchronizationPoint command described in the section ”Synchonization
Point” of the ONVIF Streaming Specification..
Instead, receivers should use the PLI message described in [RFC 4585] to request a
synchronization point.
ONVIF™
5
–6–
Receiver Spec. – Ver. 2.2.1
Service
This service offers commands to manage Receiver objects, which are used to receive media
streams from other devices. A Receiver object contains the information how to setup the
stream, the mode of the receiver and the Stream Uri (MediaUri). A device shall at least
support Media Uris of 128 octet length. The Receiver - MaximumRTSPURILength capability
indicates the maximum length supported by the device. The Receiver Service shall be
implemented by devices that can receive media streams.
The IP or DNS address in the transmit URI given to the receiver, is the address that the
device hosting the receiver service will use to access the transmit device. If, for example, the
client has to communicate through a NAT router to access the transmitter and the receiver,
the transmitter address that the client gives the receiver (in this case a local network address)
may not be the same address that the client would use to access the transmitter (in this case
an external network address).
A device shall support RTP transfer via RTP and RTP transfer via RTSP/HTTP/TCP, see
ONVIF Streaming Specification. A device may support other RTP transport protocols and shall
indicate what it supports with the appropriate capability, see 5.4.
5.1
Persistence
All the objects created within the receiver service shall be persistent – i.e. they shall survive a
power cycle. Likewise, all the configuration data in the objects shall be persistent.
5.2
Receiver modes
A receiver can operate in three distinct modes:
AlwaysConnect. The receiver attempts to maintain a persistent connection to the configured
endpoint.
NeverConnect. The receiver does not attempt to connect.
AutoConnect. The receiver connects on demand, as required by consumers of the media
streams.
5.3
Receiver commands
This section describes the commands offered by the Receiver Service.
5.3.1
Get Receivers
This operation lists all receivers that currently exist on the device. The Receiver Service shall
support this command.
Table 2: GetReceivers command
GetReceivers
Message name
GetReceiversRequest
Access Class: READ_MEDIA
Description
This message is empty.
ONVIF™
GetReceiversResponse
Fault codes
No specific fault codes.
5.3.2
–7–
Receiver Spec. – Ver. 2.2.1
Contains a list of receivers.
tt:Receiver Receivers [0][unbounded]
Description
Get Receiver
This operation retrieves the details of a specific receiver whose token is known to the client.
The Receiver Service shall support this command.
Table 3: GetReceiver command
GetReceiver
Message name
GetReceiverRequest
Access Class: READ_MEDIA
Description
Contains the token of the requested receiver.
tt:ReferenceToken ReceiverToken [1][1]
GetReceiverResponse
Fault codes
env:Sender
ter:InvalidArgVal
ter:UnknownToken
5.3.3
Contains the details of the requested receiver.
tt:Receiver Receiver [1][1]
Description
The receiver indicated by ReceiverToken does not exist.
Create Receiver
This operation creates a new receiver. The Receiver Service shall support this command.
Table 4: CreateReceiver command
CreateReceiver
Message name
CreateReceiverRequest
Access Class: ACTUATE
Description
Contains the initial configuration of the receiver.
tt:ReceiverConfiguration Configuration [1][1]
CreateReceiverResponse
Fault codes
env:Sender
ter:InvalidArgVal
ter:BadConfiguration
env:Receiver
ter:Action
ter:MaxReceivers
Contains the details of the receiver that was created.
tt:Receiver Receiver [1][1]
Description
The specified configuration is invalid.
The maximum supported number of receivers has been
reached.
ONVIF™
5.3.4
–8–
Receiver Spec. – Ver. 2.2.1
Delete Receiver
This operation deletes an existing receiver. A receiver MAY NOT be deleted if it is in use. The
Receiver Service shall support this command.
Table 5: DeleteReceiver command
DeleteReceiver
Access Class: ACTUATE
Message name
DeleteReceiverRequest
Description
Contains the token of the receiver to be deleted.
tt:ReferenceToken ReceiverToken [1][1]
DeleteReceiverResponse
This message is empty.
Fault codes
env:Sender
ter:InvalidArgVal
ter:UnknownToken
env: Receiver
ter:Action
ter:CannotDeleteReceiver
Description
The receiver indicated by ReceiverToken does not exist.
5.3.5
It is not possible to delete the specified receiver, for example
because it is currently in use.
Configure Receiver
This operation configures a receiver. The Receiver Service shall support this command.
Table 6: ConfigureReceiver command
ConfigureReceiver
Message name
ConfigureReceiverRequest
Access Class: ACTUATE
Description
Contains the token of the requested receiver and the new
configuration.
tt:ReferenceToken ReceiverToken [1][1]
tt:ReceiverConfiguration Configuration [1][1]
ConfigureReceiverResponse
This message is empty.
Fault codes
env:Sender
ter:InvalidArgVal
ter:UnknownToken
Description
The receiver indicated by ReceiverToken does not exist.
env:Sender
ter:InvalidArgVal
ter:BadConfiguration
The specified configuration is invalid.
5.3.6
SetReceiverMode
This operation may be used to set the mode of the receiver independently of the rest of its
configuration. The Receiver Service shall support this command.
ONVIF™
–9–
Receiver Spec. – Ver. 2.2.1
Table 7: SetReceiverMode command
SetReceiverMode
Message name
SetReceiverModeRequest
Access Class: ACTUATE
Description
Contains the token of the requested receiver and the new
mode.
tt:ReferenceToken ReceiverToken [1][1]
tt:ReceiverMode ReceiverMode [1][1]
SetReceiverModeResponse
This message is empty.
Fault codes
env:Sender
ter:InvalidArgVal
ter:UnknownToken
Description
The receiver indicated by ReceiverToken does not exist.
5.3.7
GetReceiverState
This operation determines whether the receiver is currently disconnected, connected or
attempting to connect. The Receiver Service shall support this command.
Table 8: GetReceiverState command
GetReceiverState
Access Class: READ_MEDIA
Message name
GetReceiverStateRequest
Description
Contains the token of the requested receiver.
GetReceiverStateResponse
tt:ReferenceToken ReceiverToken [1][1]
Contains the current state of the receiver.
Fault codes
env:Sender
ter:InvalidArgVal
ter:UnknownToken
5.4
tt:ReceiverState State [1][1]
Description
The receiver indicated by ReceiverToken does not exist.
Capabilities
The capabilities reflect optional functions and functionality of a service. The information is
static and does not change during device operation. The following capabilites are available:
RTP_Multicast:
Indication if the device supports receiving of RTP Multicast.
RTP_TCP:
Indication if the device supports receiving of RTP over TCP.
RTP_RTSP_TCP:
Indication if the device supports receiving of RTP over RTSP
over TCP.
SupportedReceivers:
The maximum number of receivers the device supports..
ONVIF™
– 10 –
Receiver Spec. – Ver. 2.2.1
MaximumRTSPURILength: The maximum length allowed for RTSP URIs.
Table 9: GetServiceCapabilities command
GetServiceCapabilities
Access Class: PRE_AUTH
Message name
Description
GetServiceCapabilitiesReque
st
This is an empty message.
GetServiceCapabilitiesRespo
nse
The capability response message contains the requested service
capabilities using a hierarchical XML capability structure.
trv:Capabilities Capabilities [1][1]
Fault codes
Description
No command specific faults!
5.5
Events
The receiver service shall dispatch events through the event service. It shall be capable of
generating the events listed in this chapter whenever the condition that fires the event occurs.
5.5.1
ChangeState
Whenever a receiver changes state, the device shall dispatch the following event:
Topic: tns1: Receiver/ChangeState
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="ReceiverToken" Type="tt:ReferenceToken"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="NewState" Type="tt:ReceiverState"/>
<tt:SimpleItemDescription Name="MediaUri" Type="tt:MediaUri" minOccurs="0"/>
</tt:Data>
</tt:MessageDescription>
5.5.2
Connection Failed
If a receiver fails to establish a connection, the device shall dispatch the following event:
Topic: tns1: Receiver/ConnectionFailed
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="ReceiverToken" Type="tt:ReferenceToken"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="MediaUri" Type="tt:MediaUri"/>
</tt:Data>
</tt:MessageDescription>
5.6 Service specific data types
5.6.1 • Receiver
Description of a receiver, including its token and configuration.
<xs:complexType name="Receiver"/>
ONVIF™
– 11 –
Receiver Spec. – Ver. 2.2.1
<xs:element name="Token" type= "tt:ReferenceToken"/>
<xs:element name="Configuration" type= "tt:ReceiverConfiguration"/>
</xs:complexType>
•
Token
Unique identifier of the receiver.
•
Configuration
Describes the configuration of the receiver.
5.6.2 • ReceiverConfiguration
Describes the configuration of a receiver.
<xs:complexType name="ReceiverConfiguration"/>
<xs:element name="Mode" type= "tt:ReceiverMode"/>
<xs:element name="MediaUri" type="xs:anyURI"/>
<xs:element name="StreamSetup" type= "tt:StreamSetup"/>
</xs:complexType>
•
Mode
The following connection modes are defined: AlwaysConnect, NeverConnect,
AutoConnect.
•
MediaUri
Details of the URI to which the receiver should connect.
•
StreamSetup
Stream connection parameters.
5.6.3 • ReceiverStateInformation
Contains information about a receiver's current state.
<xs:complexType name="ReceiverStateInformation"/>
<xs:element name="State" type= "tt:ReceiverState"/>
<xs:element name="AutoCreated" type="xs:boolean"/>
</xs:complexType>
•
State
The connection state of the receiver may have one of the following states:
NotConnected, Connecting, Connected.
•
AutoCreated
Indicates whether or not the receiver was created automatically.
ONVIF™
– 12 –
Receiver Spec. – Ver. 2.2.1
5.7 Service specific fault codes
Table 10 lists the receiver service specific fault codes. Additionally, each command can also
generate a generic fault.
The specific faults are defined as subcode of a generic fault. The parent generic subcode is
the subcode at the top of each row below and the specific fault subcode is at the bottom of
the cell.
Table 10: Service specific fault codes
Fault Code
Parent Subcode
Fault Reason
Description
Receiver does not
exist.
The receiver indicated by
ReceiverToken does not
exist.
Maximum number of
receivers has been
reached.
The maximum supported
number of receivers has
been reached.
The StreamSetup is
not supported.
Specification of
StreamType or Transport
part in
ReceiverConfiguration
StreamSetup is not
supported.
It is not possible to
delete the receiver.
It is not possible to delete
the specified receiver, for
example because it is
currently in use.
Subcode
Env:Sender
ter:InvalidArgVal
ter:UnknownToken
Env:Sender
ter:Action
ter:MaxReceivers
Env:Sender
ter:InvalidArgVal
ter:BadConfiguration
Env:Sender
ter:Action
ter:CannotDeleteReceiver
ONVIF™
– 13 –
Annex A. Revision History
Rev.
Date
Editor
Changes
2.1
Jul-2011
Hans Busch
Split from Core 2.0
Change Request 173
2.1.1
Jan-2012
Hans Busch
Change Request 535
2.2
May-2012
Hans Busch
Change Request 677
2.2.1
Dec-2012
Hans Busch
Change Request 708, 709
Receiver Spec. – Ver. 2.2.1

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project