RecordingSearch.xml

<?xml version="1.0"?>
<?xml-stylesheet href="docbook.xsl" type="text/xsl" ?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0">
  <info>
    <title>Recording Search Specification</title>
    <titleabbrev>RecordingSearch</titleabbrev>
    <releaseinfo>22.06</releaseinfo>
    <author>
      <orgname>ONVIF™</orgname>
      <uri>www.onvif.org</uri>
    </author>
    <pubdate>June, 2022</pubdate>
    <mediaobject>
      <imageobject>
        <imagedata fileref="media/logo.png" contentwidth="60mm" />
      </imageobject>
    </mediaobject>
    <copyright>
      <year>2008-2021</year>
      <holder>ONVIF™ All rights reserved.</holder>
    </copyright>
    <legalnotice>
      <para>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.</para>
      <para>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.</para>
      <para>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.</para>
    </legalnotice>
    <revhistory>
      <revision>
        <revnumber>2.1</revnumber>
        <date>Jul-2011</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Split from Core 2.0</revremark>
      </revision>
      <revision>
        <revnumber>2.1.1</revnumber>
        <date>Jan-2012</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Change Requests 325, 327, 328, 435, 535</revremark>
      </revision>
      <revision>
        <revnumber>2.2</revnumber>
        <date>Apr-2012</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Change Requests 601, 608, 614, 616, 621, 671, 672</revremark>
      </revision>
      <revision>
        <revnumber>2.2.1</revnumber>
        <date>Sep-2012</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Change Requests 708, 765, 766, 778, 780, 781, 827, 837</revremark>
      </revision>
      <revision>
        <revnumber>2.3</revnumber>
        <date>May-2013</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 884</revremark>
      </revision>
      <revision>
        <revnumber>2.4</revnumber>
        <date>Aug-2013</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1090, 1147, 1152</revremark>
      </revision>
      <revision>
        <revnumber>2.4.1</revnumber>
        <date>Dec-2013</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1190, 1208</revremark>
      </revision>
      <revision>
        <revnumber>2.4.2</revnumber>
        <date>Jun-2014</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1229</revremark>
      </revision>
      <revision>
        <revnumber>2.5</revnumber>
        <date>Dec-2014</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1457</revremark>
      </revision>
      <revision>
        <revnumber>2.6</revnumber>
        <date>Jun-2015</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1651</revremark>
      </revision>
      <revision>
        <revnumber>2.6.1</revnumber>
        <date>Dec-2015</date>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Change Request 1720</revremark>
      </revision>
      <revision>
        <revnumber>16.06</revnumber>
        <date>Jun-2016</date>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Change Request 1695, 1763</revremark>
      </revision>
      <revision>
        <revnumber>17.06</revnumber>
        <date>Jun-2017</date>
        <author>
          <personname>Stefan Andersson</personname>
        </author>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Update method layouts
Change Request 1843, 2050, 2053, 2055, 2065</revremark>
      </revision>
      <revision>
        <revnumber>18.12</revnumber>
        <date>Dec-2018</date>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Change Request 2382</revremark>
      </revision>
      <revision>
        <revnumber>21.12</revnumber>
        <date>Dec-2021</date>
        <author>
          <personname>Sergey Bogdanov</personname>
        </author>
        <revremark>Change the "role" attribute for request access class.</revremark>
      </revision>
      <revision>
        <revnumber>22.06</revnumber>
        <date>June-2022</date>
        <author>
          <personname>Fredrik Svensson</personname>
        </author>
        <revremark>Change the "role" attribute for request access class.</revremark>
      </revision>
    </revhistory>
  </info>
  <chapter>
    <title>Scope</title>
    <para>This document defines the web service interface for searching for recorded Video, Audio and Metadata. </para>
    <para>For a definition of the storage model see the ONVIF Recording Control Specification.</para>
    <para>Web service usage is outside of the scope of this document. Please refer to the ONVIF core specification.</para>
  </chapter>
  <chapter>
    <title>Normative references</title>
    <para>ONVIF Core Specification</para>
    <para role="reference">&lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/specs/core/ONVIF-Core-Specification.pdf"></link>&gt;</para>
    <para>ONVIF Recording Control Specification</para>
    <para role="reference">&lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/specs/srv/rec/ONVIF-RecordingControl-Service-Spec.pdf"></link>&gt;</para>
    <para>W3C XML Path Language (XPath) Version 1.0</para>
    <para role="reference">&lt;​<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.w3.org/TR/1999/REC-xpath-19991116"></link>&gt;</para>
  </chapter>
  <chapter>
    <title>Terms and Definitions</title>
    <section>
      <title>Definitions</title>
      <informaltable>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="24*" />
          <colspec colname="c2" colwidth="76*" />
          <tbody valign="top">
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Metadata</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>All streaming data except video and audio, including video analytics results, PTZ position data and other <phrase>metadata (such as textual data from POS applications)</phrase>.</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Recording</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>A container for a set of audio, video and metadata tracks. A recording can hold one or more tracks. A track is viewed as an infinite timeline that holds data at certain times.</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Recording Event</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>An event associated with a Recording, represented by a notification message in the APIs</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Recording Job</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>A job performs the transfer of data from a data source to a particular recording using a particular configuration</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Track</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>An individual data channel consisting of video, audio, or metadata. This definition is consistent with the definition of track in [RFC 2326]</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Video Analytics</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>Algorithms or programs used to analyze video data and to generate data describing object location and behaviour.</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
  </chapter>
  <chapter>
    <title>Overview</title>
    <para>The search service enables a client to find information about the recordings on the storage device, for example to construct a “timeline” view, and to find data of interest within a set of recordings. The latter is achieved by searching for events and other information that is included in the metadata track recording.</para>
    <para>The search service provides the following functionality:</para>
    <itemizedlist>
      <listitem>
        <para>Find recordings and information about each recording</para>
      </listitem>
      <listitem>
        <para>Find events in the metadata and among the historical events</para>
      </listitem>
      <listitem>
        <para>Find PTZ positions in the metadata</para>
      </listitem>
      <listitem>
        <para>Find other information in the metadata e.g. text from EPOS (electronic point-of-sale) systems</para>
      </listitem>
    </itemizedlist>
    <para>The actual searching is done by coupled find and result operations and is asynchronous. Each find operation initiates a search session. The client can then acquire the results from the search session in increments, or all at once, depending on implementation and the scale of the search. There are four pairs of search operations for recordings, recording events, PTZ positions and metadata.</para>
    <para>FindRecordings and GetRecordingSearchResults</para>
    <para>FindEvents and GetEventSearchResults</para>
    <para>FindPTZPosition and GetPTZPositionSearchResults</para>
    <para>FindMetadata and GetMetadataSearchResults</para>
    <para>WSDL for this service is specified in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/ver10/search.wsdl">http://www.onvif.org/ver10/search.wsdl</link>.</para>
    <table>
      <title>Referenced namespaces (with prefix)</title>
      <tgroup cols="2">
        <colspec colname="c1" colwidth="13*" />
        <colspec colname="c2" colwidth="87*" />
        <thead>
          <row>
            <entry>
              <para>Prefix</para>
            </entry>
            <entry>
              <para>Namespace URI</para>
            </entry>
          </row>
        </thead>
        <tbody valign="top">
          <row>
            <entry>
              <para>env</para>
            </entry>
            <entry>
              <para>http://www.w3.org/2003/05/soap-envelope</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>ter</para>
            </entry>
            <entry>
              <para>http://www.onvif.org/ver10/error</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>xs </para>
            </entry>
            <entry>
              <para>http://www.w3.org/2001/XMLSchema </para>
            </entry>
          </row>
          <row>
            <entry>
              <para>tt</para>
            </entry>
            <entry>
              <para>http://www.onvif.org/ver10/schema</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>tse</para>
            </entry>
            <entry>
              <para>http://www.onvif.org/ver10/search/wsdl</para>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </chapter>
  <chapter>
    <title>Service</title>
    <section>
      <title>Introduction</title>
      <para>The search service provides a number of operations for finding data of interest within a set of recordings. The most common way of doing this would be to search for events that are either included in the metadata track of a recording, or are otherwise associated with a recording in the device (see Recording Events below). </para>
      <para>GetRecordingSummary returns a summary for all recording, and can be used to provide the scale of a timeline.</para>
      <para>GetRecordingInformation returns information about a single recording, such as start time and current status.</para>
      <para>GetMediaAttributes returns the media attributes of a recording at a specific point in time.</para>
      <para>The actual search is done by coupled find and result operations. Each find operation initiates a search session. The client can then acquire the results from the search session in increments, or all at once, depending on implementation and the scale of the search. There are four pairs of search operations for Recordings, Recording Events, PTZ Positions and Metadata.</para>
      <para>GetSearchState returns the state of a search session.</para>
      <para>EndSearch ends a search session, halting search and returning any blocking result operations.</para>
    </section>
    <section>
      <title>Concepts</title>
      <section>
        <title>Search Direction</title>
        <para>Search is performed from a start point on the time line, towards an end point. If the end point is prior to the start point, search will be performed backwards. This can be useful if only the newest matching event is of interest, or if it is otherwise convenient to get the results in newest to oldest order.</para>
        <para>If no end point is specified, the search will always be performed forward in time from the start point.</para>
      </section>
      <section xml:id="_Toc247178878">
        <title>Recording Event</title>
        <para>Describes a discrete event related to the recording. It is represented as a notification message, but this does not necessarily mean it has been recorded as a notification. Recording events can either be notifications included in a recorded metadata track, it can be created by the recording device as a result of an internal event or mechanism, or it can be inserted by a client using a WebService request or a metadata stream. However the recording event has been created and associated with a particular recording, this specification makes no implications on how it is stored internally on a device, only how it should be represented in the interface.</para>
        <para>However created, recording events are always treated as notifications in regards to search filters and results returned. Each recording event has a notification topic as defined in the Topic Structure section of the ONVIF Core Specification. Predefined recording events are described in section <xref linkend="_Ref300655850" />.</para>
        <para>To communicate the original state of property events, virtual start state events can be returned in a search result containing the value of one or more properties at the start point of the search interval. Such start state events are virtual events in the sense that they are created on the fly by the server, rather than being collected from recorded data. If the client indicates that such events are desired by setting the appropriate flag, virtual events matching the topics defined in the search filter shall be returned for any recording in the search scope.</para>
      </section>
      <section>
        <title>Search Session</title>
        <para>A search session is started asynchronously by a Find-operation and is identified by a search token unique for that session. Results are returned in increments using GetResult-operations referring to the session created by the Find-operation. The search can be terminated in three ways:</para>
        <itemizedlist>
          <listitem>
            <para>KeepAlive time expires – If no request from a client has been made that refers to a particular session within the specified time interval, it will terminate.</para>
          </listitem>
          <listitem>
            <para>A GetResult method returns the last data for the search session by setting the search state in its result to “<phrase>Completed”.</phrase></para>
          </listitem>
          <listitem>
            <para>EndSearch – The client explicitly ends a session.</para>
          </listitem>
        </itemizedlist>
        <para>Ending a session will cancel an ongoing search, immediately return and make further requests to the same session result in an error message. A device shall not reuse search token immediately as it would confuse clients unaware that a session had ended.</para>
      </section>
      <section xml:id="_Toc247178880">
        <title>Search Scope</title>
        <para>The scope contains a number of optional elements, together limiting the set of data to look into when performing searches.</para>
        <section>
          <title>Included data</title>
          <para>Optionally, the client can define sources and recordings to search in by specifying lists of tokens for each type. If several types are given, the union of the specified tokens shall be used. If there are no sources or recordings tokens specified, all recordings shall be included. The scope is further refined by the Recording Information Filter. However, if recordings are specified the filters will only be applied to that subset of recordings.</para>
        </section>
        <section>
          <title>Recording Information Filter</title>
          <para>Rather than specifying a list of recording tokens, the recordings can be filtered by an Xpath filter operating on the RecordingInformation structure. This allows the client to filter on all elements present in the RecordingInformation structure, using comparisons according to the Xpath dialect defined in section <xref linkend="_Toc247178908" />. If a recording information filter is supplied, only recordings matching the filter shall be part of the scope.</para>
          <para>Example of a filter that includes only recordings containing audio in the search scope:</para>
          <programlisting><![CDATA[boolean(//Track[TrackType = “Audio”])
]]></programlisting>
        </section>
      </section>
      <section>
        <title>
          <literal>
          </literal>Search Filters</title>
        <para>Search filters are specific for the type of search operation. See FindEvents, FindPTZPosition, FindMetadata respectively. They all act on the recordings defined by the scope.</para>
      </section>
      <section>
        <title>
          <literal>
          </literal>Time Information</title>
        <para>An ONVIF compliant device shall support time values in request parameters that are given in utc with the 'Z' indicator and respond all time values as utc including the 'Z' indicator.</para>
      </section>
    </section>
    <section>
      <title>Data Structures</title>
      <section>
        <title>RecordingInformation Structure</title>
        <para>RecordingInformation contains information about a recording, the tracks it consists of and the source.</para>
        <variablelist>
          <varlistentry>
            <term>RecordingToken</term>
              <listitem>
                <para>a unique identifier of the recording.</para>
              </listitem>
          </varlistentry>
          <varlistentry>
            <term>EarliestRecording</term>
            <listitem><para>the date and time of the oldest data in the recording</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>LatestRecording</term>
              <listitem><para>the date and time of the newest data in the recording.</para>
              </listitem>
          </varlistentry>
          <varlistentry>
            <term>Content</term>
            <listitem><para> informative description of content. If the content is unknown this field is empty</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>RecordingStatus</term>
            <listitem>
                <para>current status of recording, can be any of: Initiated,
                  Recording, Stopped, Removing, Removed, Unknown.</para>
              </listitem>
          </varlistentry>
          <varlistentry>
            <term>RecordingSourceInformation</term>
          <listitem>
                <para> a structure containing information about the source of the recording.</para>
              </listitem>
          </varlistentry>
          <varlistentry>
            <term>TrackInformation</term>
            <listitem><para> a list of track information structures.</para></listitem>
          </varlistentry>
        </variablelist>
        <figure>
          <title>Recording state chart.</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="media/RecordingSearch/image2.svg" contentwidth="116.60mm" contentdepth="64.78mm" />
            </imageobject>
          </mediaobject>
        </figure>
        <para>Figure 1 shows the state changes for the RecordingStatus. The following adds additional explanation:</para>
        <variablelist>
          <varlistentry>
            <term>Initiated</term>
            <listitem>
              <para>The new recording is created and the specified recording has not jet started to record.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Recording</term>
            <listitem>
            <para>The recording job is executing the specified recording.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>Stopped</term>
            <listitem>
            <para>The recording job is pausing the specified recording. This case requires that the job has started recording before at least once.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>Removing</term>
            <listitem>
            <para>The specified recording is in the process of being deleted.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>Removed</term>
            <listitem>
            <para>The specified recording has been removed.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>Unknown</term>
            <listitem>
            <para>This case should never happen.</para>
          </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>RecordingSourceInformation Structure</title>
        <para>Contains information about the source of a recording.</para>
        <variablelist>
          <varlistentry>
            <term>SourceId</term>
            <listitem>
              <para>an identifier for the source chosen by the client that creates the recording. This identifier is opaque to the device. Clients may use any type of URI for this field. If this identifier is not present this field is empty.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Name</term>
            <listitem>
              <para>informative name of the source. If the name is unknown this field is empty.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Location</term>
            <listitem>
              <para>informative description of the location of the source. If the description is not available this string is empty.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Description</term>
            <listitem>
              <para>informative description of the source. If this description is not present, the description is empty.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Address</term>
            <listitem>
              <para>informative URI of the source.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>TrackInformation Structure</title>
        <para>Contains information about a single track in a recording. Note that a track may represent a single contiguous time span or consist of multiple slices as shown in the introduction of the ONVIF Recording Control Specification. If there is no recorded data for a track the TrackInformation shall not be provided.</para>
        <variablelist>
          <varlistentry>
            <term>TrackToken</term>
            <listitem>
              <para>An identifier of the track. The TrackToken is unique between all TrackTokens used within a recording.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>TrackType</term>
            <listitem>
              <para>Identifies the type of track (video, audio or metadata)</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Description</term>
            <listitem>
              <para>Informative description of the track. If this information is not present, this field is empty.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>DataFrom</term>
            <listitem>
              <para>The start date and time of the oldest recorded data in the track.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>DataTo</term>
            <listitem>
              <para>The stop date and time of the newest recorded data in the track.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>SearchState Enumeration</title>
        <para>The search state can be one of the following</para>
        <variablelist>
          <varlistentry>
            <term>Searching</term>
            <listitem>
              <para>The database search is in progress and there may be results available  		that can be fetched via the method GetEventSearchResults.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Completed</term>
            <listitem>
              <para>Search has been completed and all results have been delivered via  		GetEventSearchResults.</para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>The usage of the additionally defined state "Queued" is deprecated.</para>
      </section>
      <section>
        <title>MediaAttributes Structure</title>
        <para>The MediaAttributes contains information about the media tracks of a particular recording for a particular time frame. The time frame can be a single point in time, in which case the <emphasis>From</emphasis> and <emphasis>Until</emphasis> elements are identical.</para>
        <variablelist>
          <varlistentry>
            <term>RecordingToken</term>
            <listitem>
              <para>A reference to the recording that this structure concerns.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>From</term>
            <listitem>
              <para>A point in time from when the attributes are valid for the recording.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Until</term>
            <listitem>
              <para>A point in time until when the specified attributes are valid for the recording.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>VideoAttributes</term>
            <listitem>
              <para>A set of video attributes, describing the data of a recorded video track.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>AudioAttributes</term>
            <listitem>
              <para>A set of audio attributes, describing the data of a recorded audio track.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>MetadataAttributes</term>
            <listitem>
              <para>A set of attributes, describing the possible metadata content of a recorded metadata track.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>FindEventResult Structure</title>
        <variablelist>
          <varlistentry>
            <term>RecordingToken</term>
            <listitem>
              <para>Identifying the recording containing the found event.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>TrackToken</term>
            <listitem>
            <para>Identifying the track containing the found event.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>Time</term>
            <listitem>
            <para>The date and time of the found event.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>Event</term>
            <listitem>
            <para>The event message found.</para>
          </listitem>
          </varlistentry>
          <varlistentry>
            <term>StartStateEvent</term>
            <listitem>
            <para>If true, indicates the event represents the start state of one or more properties in the recording.</para>
          </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>FindPTZPositionResult Structure</title>
        <variablelist>
          <varlistentry>
            <term>RecordingToken</term>
            <listitem>
              <para> – identifying the recording containing the matching position.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>TrackToken</term>
            <listitem>
              <para>Identifying the track containing the matching position.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Time</term>
            <listitem>
              <para>The date and time of the matching position.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Position</term>
            <listitem>
              <para>The matching PTZ vector.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>PTZPositionFilter Structure</title>
        <para>Contains the necessary elements to define what PTZ positions to search for. The PTZ vectors shall be in the same coordinate space as the PTZ coordinates stored in the recording.</para>
        <variablelist>
          <varlistentry>
            <term>MinPosition</term>
            <listitem>
              <para>The lower boundary of the PTZ volume to look for.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>MaxPosition</term>
            <listitem>
              <para>The upper boundary of the PTZ volume to look for.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>EnterOrExit</term>
            <listitem>
              <para>If true, report the positions when entering or exiting the specified PTZ volume. Otherwise report all recorded positions within the specified PTZ range. </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>MetadataFilter Structure</title>
        <para>Contains an Xpath expression to be applied to the MetadataStream structure.</para>
        <para>Example of an expression searching for objects overlapping the lower right quadrant of the scene:</para>
        <programlisting><![CDATA[boolean(//Object/Appearance/Shape/BoundingBox[@right > ”0.5”]) and 
boolean(//Object/Appearance/Shape/BoundingBox[@bottom > ”0.5”])
]]></programlisting>
      </section>
      <section>
        <title>FindMetadataResult Structure</title>
        <variablelist>
          <varlistentry>
            <term>RecordingToken</term>
            <listitem><para>Identifying the recording containing the matching metadata.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>TrackToken</term>
            <listitem>
              <para>Identifying the track containing the matching metadata.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Time</term>
            <listitem>
              <para>The date and time of the matching metadata.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
    </section>
    <section>
      <title>GetRecordingSummary</title>
      <para>GetRecordingSummary is used to get a summary description of all recorded data. This operation is mandatory to support for a device implementing the recording search service. If a device returns NumberRecordings as zero, both DataFrom and DataUntil can be safely ignored.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="text">This is an empty message.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Summary [tt:RecordingSummary]</para>
            <para role="text">A structure containing: DataFrom specifying the first time when there is recorded data on the device; DataUntil specifying the last point in time where there is data recorded on the device; the total number of recordings on the device.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">None</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetRecordingInformation</title>
      <para>Returns information about a single <emphasis>Recording</emphasis> specified by a <emphasis>RecordingToken.</emphasis> This operation is mandatory to support for a device implementing the recording search service.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:ReferenceToken]</para>
            <para role="text">Identifies  the recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">RecordingInformation [tt:RecordingInformation]</para>
            <para role="text">Information about the recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The recording token is not valid</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetMediaAttributes</title>
      <para>Returns a set of media attributes for all tracks of the specified recordings at a specified point in time. Clients using this operation shall be able to use it as a non-blocking operation. A device shall set the starttime and endtime of the MediaAttributes structure to equal values if calculating this range would cause this operation to block. See MediaAttributes structure for more information. This operation is mandatory to support for a device implementing the recording search service.</para>
      <para>Devices indicating CanContainPTZ shall report the PTZ spaces in use at the specified point in time (including generic spaces). For optimal interoperability device implementations should use generic spaces. The generic spaces are the following:</para>
      <programlisting><![CDATA[http://www.onvif.org/ver10/tptz/PanTiltSpaces/PositionGenericSpace
http://www.onvif.org/ver10/tptz/ZoomSpaces/PositionGenericSpace
]]></programlisting>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingTokens – optional, unbounded [tt:ReferenceToken]</para>
            <para role="text">A list of references to the recordings to query. If no recording tokens are provided all recordings should be queried.</para>
            <para role="param">Time [xs:dateTime]</para>
            <para role="text">The point in time from where the information is requested.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">MediaAttributes – optional, unbounded [tt:MediaAttributes]</para>
            <para role="text">Contains a MediaAttributes structure for the RecordingToken specified in the request. Note that each RecordingToken can result in zero or one MediaAttributes.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The recording token is not valid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>FindRecordings</title>
      <para>FindRecordings starts a search session, looking for recordings that match the scope (See <xref linkend="_Toc247178880" />) defined in the request. Results from the search are acquired using the GetRecordingSearchResults request, specifying the search token returned from this request.</para>
      <para>The device shall continue searching until one of the following occurs:</para>
      <itemizedlist>
        <listitem>
          <para>The total number of matches has been found, defined by the <emphasis>MaxMatches</emphasis> parameter.</para>
        </listitem>
        <listitem>
          <para>The session has been ended by a client EndSearch request.</para>
        </listitem>
        <listitem>
          <para>The session has been ended because <emphasis>KeepAliveTime</emphasis> since the last request related to this session has expired.</para>
        </listitem>
      </itemizedlist>
      <para>The order of the results is undefined, to allow the device to return results in any order they are found. This operation is mandatory to support for a device implementing the recording search service. </para>
      <para>For the KeepAliveTime a device shall support at least values up to ten seconds. A device may adapt larger values.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">Scope [tt:SearchScope]</para>
            <para role="text">Defines the dataset to consider for this search</para>
            <para role="param">MaxMatches - optional [xs:int]</para>
            <para role="text">The search ends after MaxMatches.</para>
            <para role="param">KeepAliveTimeout [xs:duration]</para>
            <para role="text">The session timeout after each request concerning this session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">SearchToken [tt:Jobtoken]</para>
            <para role="text">Identifies the search session created by this request.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The recording token is not valid.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidSource</para>
            <para role="text">The recording source is not valid.</para>
            <para role="param">env:Receiver - ter:Action - ter:ResourceProblem</para>
            <para role="text">Device is unable to create a new search session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetRecordingSearchResults</title>
      <para>GetRecordingSearchResults acquires the results from a recording search session previously initiated by a FindRecordings operation. The response shall not include results already returned in previous requests for the same session. If <emphasis>MaxResults</emphasis> is specified, the response shall not contain more than <emphasis>MaxResults</emphasis> results. The number of results relates to the number of recordings. For viewing individual recorded data for a signal track use the FindEvents method.</para>
      <para>GetRecordingSearchResults shall block until:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis>MaxResults</emphasis> results are available for the response if <emphasis>MaxResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>MinResults</emphasis> results are available for the response if <emphasis>MinResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>WaitTime</emphasis> has expired.</para>
        </listitem>
        <listitem>
          <para>Search is completed or stopped.</para>
        </listitem>
      </itemizedlist>
      <para>This operation is mandatory to support for a device implementing the recording search service. If any of the specified parameters MinResults and WaitTime exceed the supported range a device shall adapt them instead of responding an error.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Specifies the search session.</para>
            <para role="param">MinResults - optional [xs:int]</para>
            <para role="text">Specifies the minimum number of results that should be returned. If the total number of results is lower than MinResults in a completed search, all results should be returned.</para>
            <para role="param">MaxResults – optional [xs:int]</para>
            <para role="text">Specifies the maximum number of results to return.</para>
            <para role="param">WaitTime – optional [xs:duration]</para>
            <para role="text">Defines the maximum time to block, waiting for results.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The search token is invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>RESPONE:</para>
      <itemizedlist>
        <listitem>
          <para>ResultList [tt:FindRecordingResultList]</para>
          <para>A structure containing the current SearchState and a list of RecordingInformation structures.</para>
        </listitem>
      </itemizedlist>
    </section>
    <section>
      <title>FindEvents</title>
      <para>FindEvents starts a search session, looking for events in the <emphasis>scope</emphasis> (See <xref linkend="_Toc247178880" />) that match the search filter defined in the request. Events are recording events (see <xref linkend="_Toc247178878" />) and other events that are available in the track. Results from the search are acquired using the GetEventSearchResults request, specifying the search token returned from this request.</para>
      <para>The device shall continue searching until one of the following occurs:</para>
      <itemizedlist>
        <listitem>
          <para>The entire time range from <emphasis>StartPoint</emphasis> to <emphasis>EndPoint </emphasis>has been searched through.</para>
        </listitem>
        <listitem>
          <para>The total number of matches has been found, defined by the <emphasis>MaxMatches</emphasis> parameter.</para>
        </listitem>
        <listitem>
          <para>The session has been ended by a client EndSearch request.</para>
        </listitem>
        <listitem>
          <para>The session has been ended because <emphasis>KeepAliveTime</emphasis> since the last request related to this session has expired.</para>
        </listitem>
      </itemizedlist>
      <para>Results shall be ordered by time, ascending in case of forward search, or descending in case of backward search. This operation is mandatory to support for a device implementing the recording search service. Although the values of property events refer to the forward direction, they shall be reported identically in reverse search mode.</para>
      <para>For the KeepAliveTime a device shall support at least values up to ten seconds. A device may adapt larger values.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">StartPoint [xs:dateTime]</para>
            <para role="text">The point of time where the search will start.</para>
            <para role="param">EndPoint – optional [xs:dateTime]</para>
            <para role="text">The point of time where the search will stop. This can be a time before the StartPoint, in which case the search is performed backwards in time. If EndPoint is omitted, search will go forward from the StartPoint.</para>
            <para role="param">Scope [tt:SearchScope]</para>
            <para role="text">Defines the dataset to consider for this search.</para>
            <para role="param">SearchFilter [tt:EventFilter]</para>
            <para role="text">Contains the topic and message filter needed to define what events to search for.</para>
            <para role="param">IncludeStartState [xs:boolean]</para>
            <para role="text">By setting the IncludeStartState to true, the client indicates that virtual events at the time of StartPoint should be returned to represent the state in the recording. In case of a backward search, virtual events at the time of EndPoint and StartPoint should be returned. Support for virtual events is mandatory for recording events. Support for additional virtual events is signalled via the GeneralStartEvents capability.</para>
            <para role="param">MaxMatches – optional [xs:int]</para>
            <para role="text">The search ends after MaxMatches.</para>
            <para role="param">KeepAliveTime [xs:duration]</para>
            <para role="text">The session timeout after each request concerning this session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Identifies the search session created by this request.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Receiver - ter:Action - ter:ResourceProblem</para>
            <para role="text">Device is unable to create a new search session.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidFilterFault</para>
            <para role="text">Provided Search filter expression was not understood or supported by the device.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetEventSearchResults</title>
      <para>GetEventSearchResults acquires the results from a recording event search session previously initiated by a FindEvents operation. The response shall not include results already returned in previous requests for the same session. If <emphasis>MaxResults</emphasis> is specified, the response shall not contain more than <emphasis>MaxResults</emphasis> results.</para>
      <para>GetEventSearchResults shall block until:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis>MaxResults</emphasis> results are available for the response if <emphasis>MaxResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>MinResults</emphasis> results are available for the response if <emphasis>MinResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>WaitTime</emphasis> has expired.</para>
        </listitem>
        <listitem>
          <para>Search is completed or stopped.</para>
        </listitem>
      </itemizedlist>
      <para>This operation is mandatory to support for a device implementing the recording search service. If any of the specified parameters MinResults and WaitTime exceed the supported range a device shall adapt them instead of responding an error.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Specifies the search session.</para>
            <para role="param">MinResults - optional [xs:int]</para>
            <para role="text">Specifies the minimum number of results that should be returned. If the total number of remaining event is lower than MinResults in a completed search, all remaining events should be returned.</para>
            <para role="param">MaxResults – optional [xs:int]</para>
            <para role="text">Specifies the maximum number of results to return.</para>
            <para role="param">WaitTime – optional [xs:duration]</para>
            <para role="text">Defines the maximum time to block, waiting for results.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">ResultList [tt: FindEventResultList]</para>
            <para role="text">A structure containing:</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The search token is invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>FindPTZPosition</title>
      <para>FindPTZPosition starts a search session, looking for ptz positions in the <emphasis>scope</emphasis> (See <xref linkend="_Toc247178880" />)  that matches the search filter defined in the request. Results from the search are acquired using the GetPTZPositionSearchResults request, specifying the search token returned from this request.</para>
      <para>The device shall continue searching until one of the following occurs:</para>
      <itemizedlist>
        <listitem>
          <para>The entire time range from <emphasis>StartPoint</emphasis> to <emphasis>EndPoint </emphasis>has been searched through.</para>
        </listitem>
        <listitem>
          <para>The total number of matches has been found, defined by the <emphasis>MaxMatches</emphasis> parameter.</para>
        </listitem>
        <listitem>
          <para>The session has been ended by a client EndSearch request.</para>
        </listitem>
        <listitem>
          <para>The session has been ended because <emphasis>KeepAliveTime</emphasis> since the last request related to this session has expired.</para>
        </listitem>
      </itemizedlist>
      <para>This operation is mandatory to support whenever CanContainPTZ is true for any metadata track in any recording on the device.</para>
      <para>For the KeepAliveTime a device shall support at least values up to ten seconds. A device may adapt larger values.</para>
      <para>A device shall only match the search criteria against PTZ status updates available between the time interval given in the search, i.e. the device shall not locate the PTZ position at the start of the search interval.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">StartPoint [xs:dateTime]</para>
            <para role="text">The point of time where the search will start.</para>
            <para role="param">EndPoint – optional [xs:dateTime]</para>
            <para role="text">The point of time where the search will stop. This can be a time before the StartPoint, in which case the search is performed backwards in time. If EndPoint is omitted, search will go forward from the StartPoint.</para>
            <para role="param">Scope [tt:SearchScope]</para>
            <para role="text">Defines the dataset to consider for this search.</para>
            <para role="param">SearchFilter [tt: PTZPositionFilter]</para>
            <para role="text">Contains the search criteria needed to define the PTZ position to search for.</para>
            <para role="param">MaxMatches – optional [xs:int]</para>
            <para role="text">The search ends after MaxMatches.</para>
            <para role="param">KeepAliveTime [xs:duration]</para>
            <para role="text">The session timeout after each request concerning this session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Identifies the search session created by this request.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Receiver - ter:Action - ter:ResourceProblem</para>
            <para role="text">Device is unable to create a new search session.</para>
            <para role="param">env:Receiver - ter:ActionNotSupported - ter:NotImplemented</para>
            <para role="text">This optional method is not implemented.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetPTZPositionSearchResults</title>
      <para>GetPTZPositionSearchResults acquires the results from a PTZ position search session previously initiated by a FindPTZPosition operation. The response shall not include results already returned in previous requests for the same session. If <emphasis>MaxResults</emphasis> is specified, the response shall not contain more than <emphasis>MaxResults</emphasis> results.</para>
      <para>GetPTZPositionSearchResults shall block until:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis>MaxResults</emphasis> results are available for the response if <emphasis>MaxResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>MinResults</emphasis> results are available for the response if <emphasis>MinResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>WaitTime</emphasis> has expired.</para>
        </listitem>
        <listitem>
          <para>Search is completed or stopped.</para>
        </listitem>
      </itemizedlist>
      <para>This operation is mandatory to support whenever CanContainPTZ is true for any metadata track in any recording on the device. If any of the specified parameters MinResults and WaitTime exceed the supported range a device shall adapt them instead of responding an error.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Specifies the search session.</para>
            <para role="param">MinResults - optional [xs:int]</para>
            <para role="text">Specifies the minimum number of results that should be returned. If the total number of results is lower than MinResults in a completed search, all results should be returned.</para>
            <para role="param">MaxResults – optional [xs:int]</para>
            <para role="text">Specifies the maximum number of results to return.</para>
            <para role="param">WaitTime – optional [xs:duration]</para>
            <para role="text">Defines the maximum time to block, waiting for results.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">ResultList [tt:FindPTZPositionResultList]</para>
            <para role="text">A structure containing:</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The search token is invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>FindMetadata</title>
      <para>FindMetadata starts a search session, looking for metadata in the scope (See <xref linkend="_Toc247178880" />) that matches the search filter defined in the request. Results from the search are acquired using the GetMetadataSearchResults request, specifying the search token returned from this request.</para>
      <para>The device shall continue searching until one of the following occurs:</para>
      <itemizedlist>
        <listitem>
          <para>The entire time range from <emphasis>StartPoint</emphasis> to <emphasis>EndPoint </emphasis>has been searched through.</para>
        </listitem>
        <listitem>
          <para>The total number of matches has been found, defined by the <emphasis>MaxMatches</emphasis> parameter.</para>
        </listitem>
        <listitem>
          <para>The session has been ended by a client EndSearch request.</para>
        </listitem>
        <listitem>
          <para>The session has been ended because <emphasis>KeepAliveTime</emphasis> since the last request related to this session has expired.</para>
        </listitem>
      </itemizedlist>
      <para>This operation is mandatory to support if the MetaDataSearch capability is set to true in the SearchCapabilities structure return by the GetCapabilities command in the Device service.</para>
      <para>For the KeepAliveTime a device shall support at least values up to ten seconds. A device may adapt larger values.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">StartPoint [xs:dateTime]</para>
            <para role="text">The point of time where the search will start.</para>
            <para role="param">EndPoint – optional [xs:dateTime]</para>
            <para role="text">The point of time where the search will stop. This can be a time before the StartPoint, in which case the search is performed backwards in time. If EndPoint is omitted, search will go forward from the StartPoint.</para>
            <para role="param">Scope [tt:SearchScope]</para>
            <para role="text">Defines the dataset to consider for this search.</para>
            <para role="param">SearchFilter [tt: MetadataFilter]</para>
            <para role="text">Contains the search criteria needed to define the metadata to search for.</para>
            <para role="param">MaxMatches – optional [xs:int]</para>
            <para role="text">The search ends after MaxMatches.</para>
            <para role="param">KeepAliveTime [xs:duration]</para>
            <para role="text">The session timeout after each request concerning this session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Identifies the search session created by this request.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Receiver - ter:Action - ter:ResourceProblem</para>
            <para role="text">Device is unable to create a new search session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetMetadataSearchResults</title>
      <para>GetMetadataSearchResults acquires the results from a recording search session previously initiated by a FindMetadata operation. The response shall not include results already returned in previous requests for the same session. If <emphasis>MaxResults</emphasis> is specified, the response shall not contain more than <emphasis>MaxResults</emphasis> results.</para>
      <para>GetMetadataSearchResults shall block until:</para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis>MaxResults</emphasis> results are available for the response if <emphasis>MaxResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>MinResults</emphasis> results are available for the response if <emphasis>MinResults</emphasis> is specified.</para>
        </listitem>
        <listitem>
          <para>
            <emphasis>WaitTime</emphasis> has expired.</para>
        </listitem>
        <listitem>
          <para>Search is completed or stopped.</para>
        </listitem>
      </itemizedlist>
      <para>This operation is mandatory to support if the MetaDataSearch capability is set to true in the SearchCapabilities structure return by the GetCapabilities command in the Device service. If any of the specified parameters MinResults and WaitTime exceed the supported range a device shall adapt them instead of responding an error.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">SearchToken [tt:JobToken]</para>
            <para role="text">Specifies the search session.</para>
            <para role="param">MinResults - optional [xs:int]</para>
            <para role="text">Specifies the minimum number of results that should be returned. If the total number of results is lower than MinResults in a completed search, all results should be returned.</para>
            <para role="param">MaxResults – optional [xs:int]</para>
            <para role="text">Specifies the maximum number of results to return.</para>
            <para role="param">WaitTime – optional [xs:duration]</para>
            <para role="text">Defines the maximum time to block, waiting for results.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">ResultList [tt: FindMetadataResultList]</para>
            <para role="text">A structure containing:</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The search token is invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>EndSearch</title>
      <para>EndSearch stops an ongoing search session, causing any blocking result request to return and the <emphasis>SearchToken</emphasis> to become invalid. If the search was interrupted before completion, the point in time that the search had reached shall be returned. If the search had not yet begun, the <emphasis>StartPoint</emphasis> shall be returned. Note that an error message will occur if the search session has been already completed before this request. If the search was completed the original <emphasis>EndPoint</emphasis> supplied by the Find operation shall be returned. When issuing EndSearch on a FindRecordings request the <emphasis>EndPoint</emphasis> is undefined and shall not be used since the FindRecordings request doesn't have StartPoint/EndPoint. This operation is mandatory to support for a device implementing the recording search service.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">SearchToken [tt:Jobtoken]</para>
            <para role="text">Specifies the search session.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">EndPoint [xs:dateTime]</para>
            <para role="text">The point in time where the search was at when ended.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidToken</para>
            <para role="text">The search token is invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetServiceCapabilities</title>
      <para>The capabilities reflect optional functions and functionality of a service. The information is static and does not change during device operation.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="text">This is an empty message.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Capabilities [tse:Capabilities]</para>
            <para role="text">Contains the requested service capabilities using a hierarchical XML capability structure.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">PRE_AUTH</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following capabilites are available:</para>
      <variablelist>
        <varlistentry>
          <term>MetadataSearch</term>
          <listitem><para>Indication if the device supports generic search of recorded metadata,</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>GeneralStartEvents</term>
          <listitem><para>Indicates support for general virtual property events in the FindEvents method</para></listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section xml:id="_Ref300655850">
      <title>Recording Event Descriptions</title>
      <para>A device shall generate the following events with the corresponding event message descriptions. A device supporting the recording search service shall record these notification messages so that clients can use FindEvents to search for these messages. All recording events that are generated by the device and inserted into the recording history shall have a root topic of tns1:RecordingHistory.</para>
      <para>The time of all recording events shall specify the actual time relating to recording regardless of the sending time of the event.</para>
      <programlisting><![CDATA[Topic: tns1:RecordingHistory/Recording/State
<tt:MessageDescription IsProperty="true">
  <tt:Source>
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:ReferenceToken"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="IsRecording" Type="xs:boolean"/>
  </tt:Data>
</tt:MessageDescription>
]]></programlisting>
      <para>This message is sent whenever a client starts or stops recording for a specific recording. At start recording, IsRecording shall be set to true. At stop recording, IsRecording shall be set to false.</para>
      <programlisting><![CDATA[Topic: tns1:RecordingHistory/Track/State
<tt:MessageDescription IsProperty="true">
  <tt:Source>
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:ReferenceToken"/>
    <tt:SimpleItemDescription Name="Track" Type="tt:ReferenceToken"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="IsDataPresent" Type="xs:boolean"/>
  </tt:Data>
</tt:MessageDescription>
]]></programlisting>
      <para>This message signals when the data for a track is present. When the data becomes present, a message with IsDataPresent set to true shall be sent. When the data becomes unavailable, The message with IsDataPresent set to false shall be sent.</para>
      <para>A device MAY generate the following events. If the device supports these events, it shall always automatically record these notification messages so that clients can always use FindEvent for these messages.</para>
      <para>Topic: tns1:RecordingHistory/Track/<phrase>Video</phrase>Parameters</para>
      <programlisting><![CDATA[<tt:MessageDescription IsProperty="true">
  <tt:Source>
    <tt:SimpleItemDescription Name="Recording" Type="tt:ReferenceToken"/>
    <tt:SimpleItemDescription Name="Track" Type="tt:ReferenceToken"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="VideoEncoding" 			Type="tt:VideoEncoding"/>
    <tt:SimpleItemDescription Name="VideoWidth" Type="xs:int"/>
    <tt:SimpleItemDescription Name="VideoHeight" Type="xs:int"/>
    <tt:ElementItemDescription Name="VideoRateControl" 			Type="tt:VideoRateControl"/>
  </tt:Data>
</tt:MessageDescription>
]]></programlisting>
      <para>Topic: tns1:RecordingHistory/Track/AudioParameters </para>
      <programlisting><![CDATA[<tt:MessageDescription IsProperty="true">
  <tt:Source>
    <tt:SimpleItemDescription Name="Recording" Type="tt:ReferenceToken"/>
    <tt:SimpleItemDescription Name="Track" Type="tt:ReferenceToken"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="AudioEncoding" 			Type="tt:AudioEncoding"/>
    <tt:SimpleItemDescription Name="AudioSampleRate" Type="xs:int"/>
    <tt:SimpleItemDescription Name="AudioBitrate" Type="xs:int"/>
  </tt:Data>
</tt:MessageDescription>
]]></programlisting>
      <para>The device shall send either message (depending on the track data type) whenever any of these properties change.</para>
    </section>
    <section xml:id="_Toc247178908">
      <title>Xpath dialect</title>
      <para>This section defines the [W3C XPATH 1.0] dialect that a device that realises the search service shall implement to parse the Xpath strings that are passed to the methods of the search service. </para>
      <programlisting><![CDATA[Dialect=http://www.onvif.org/ver10/tse/searchFilter
[1] Expression ::= BoolExpr | Expression 'and' Expression
    | Expression 'or' Expression | '('Expression')' | 'not''('Expression')' 
[2] BoolExpr ::= 'boolean''('PathExpr')' | 'contains''(' ElementPath ',' '"' String '"' ')'  
[3] PathExpr ::= '//SimpleItem' NodeTest | '//ElementItem' NodeTest | 	ElementTest 
[4] NodeTest ::= '['AttrExpr']' 
[5] AttrExpr ::= NameComp | ValueComp | AttrExpr 'and' AttrExpr | 
    AttrExpr 'or' AttrExpr | 'not''(AttrExpr')' 
[6] NameComp ::= NameAttr'=''"'String'"' 
[7] ValueComp ::= ValueAttr Operator '"'String'"' 
[8] Operator ::= '=' | '!=' | '<' | '<=' | '>' | '>=' 
[9] NameAttr ::= '@Name' 
[10] ValueAttr ::='@Value' 
[11] ElementTest ::= '/' ElementPath '['NodeComp']'  
[12] ElementPath ::= ElementName ElementName* 
[13] ElementName ::= '/' String 
[14] NodeComp ::= NodeName Operator '"' String '"' 
[15] NodeName ::= '@' String | String
]]></programlisting>
      <para>Example of an Xpath expression used to find recordings from the basement where there is at least one track containing video:</para>
      <programlisting><![CDATA[boolean(//Source[Location = “Basement”]) and boolean(//Track[TrackType = “Video”])
]]></programlisting>
    </section>
  </chapter>
  <appendix>
    <title>Deprecated Interfaces</title>
    <section>
      <title>Method for returning search status</title>
      <para>The definition and interface for the returning search status have been deprecated with release 16.06. The following interfaces have been removed from the specification:</para>
      <itemizedlist>
        <listitem>
          <para>GetSearchState</para>
        </listitem>
      </itemizedlist>
      <para>The definition is available via the link &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.onvif.org/specs/srv/rsrch/ONVIF-RecordingSearch-Service-Spec-v1606.pdf">https://www.onvif.org/specs/srv/rsrch/ONVIF-RecordingSearch-Service-Spec-v1606.pdf</link>&gt;.</para>
    </section>
  </appendix>
  <appendix role="revhistory">
    <title>Revision History</title>
    <para />
  </appendix>
</book>