Skip to content

Search

Search service implementation.

Search

Bases: ONVIFService

0.0.1 2.0

Search service client.

Property Details
First introduced ONVIF 2.0 (November 2010)
Binding name SearchBinding (ver10/search.wsdl)
Operations search.wsdl
Spec RecordingSearch

GetServiceCapabilities 

GetServiceCapabilities()

Returns the capabilities of the search service.

The result is returned in a typed answer.

Output
  • Capabilities [Capabilities]
    The capabilities for the search service is returned in the Capabilities element.
    • MetadataSearch - optional; [boolean]
    • GeneralStartEvents - optional; [boolean]
      Indicates support for general virtual property events in the FindEvents method.
    • NLSearch - optional; [boolean]
      Indicates support for natural language based search.
    • ImageSearch - optional; [boolean]
      Indicates support for image based search.

GetRecordingSummary 

GetRecordingSummary()

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.

Output
  • Summary [RecordingSummary]
    • DataFrom [dateTime]
      The earliest point in time where there is recorded data on the device.
    • DataUntil [dateTime]
      The most recent point in time where there is recorded data on the device.
    • NumberRecordings [int]
      The device contains this many recordings.

GetRecordingInformation 

GetRecordingInformation(RecordingToken)

Returns information about a single Recording specified by a RecordingToken.

This operation is mandatory to support for a device implementing the recording search service.

Input
  • RecordingToken [RecordingReference]
Output
  • RecordingInformation [RecordingInformation]
    • RecordingToken [RecordingReference]
    • Source [RecordingSourceInformation]
      Information about the source of the recording. This gives a description of where the data in the recording comes from. Since a single recording is intended to record related material, there is just one source. It is indicates the physical location or the major data source for the recording. Currently the recordingconfiguration cannot describe each individual data source.
      • SourceId [anyURI]
        Identifier for the source chosen by the client that creates the structure. This identifier is opaque to the device. Clients may use any type of URI for this field. A device shall support at least 128 characters.
      • Name [Name]
        Informative user readable name of the source, e.g. "Camera23". A device shall support at least 20 characters.
        Maximum length: 64
      • Location [Description]
        Informative description of the physical location of the source, e.g. the coordinates on a map.
      • Description [Description]
        Informative description of the source.
      • Address [anyURI]
        URI provided by the service supplying data to be recorded. A device shall support at least 128 characters.
      • VideoSourceToken - optional; [ReferenceToken]
        The video source token of all recordings that will use this configuration.
        Maximum length: 64
    • EarliestRecording - optional; [dateTime]
    • LatestRecording - optional; [dateTime]
    • Content [Description]
    • Track - optional, unbounded; [TrackInformation]
      Basic information about the track. Note that a track may represent a single contiguous time span or consist of multiple slices.
      • TrackToken [TrackReference]
      • TrackType [TrackType]
        Type of the track: "Video", "Audio" or "Metadata". The track shall only be able to hold data of that type.
        Enum Value Enum Description
        Video —
        Audio —
        Metadata —
        Extended Placeholder for future extension.
      • Description [Description]
        Informative description of the contents of the track.
      • DataFrom [dateTime]
        The start date and time of the oldest recorded data in the track.
      • DataTo [dateTime]
        The stop date and time of the newest recorded data in the track.
    • RecordingStatus [RecordingStatus]
      Enum Value Enum Description
      Initiated —
      Recording —
      Stopped —
      Removing —
      Removed —
      Unknown This case should never happen.

GetMediaAttributes 

GetMediaAttributes(Time, RecordingTokens=None)

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 causes this operation to block. See MediaAttributes structure for more information. This operation is mandatory to support for a device implementing the recording search service.

Input
  • RecordingTokens - optional, unbounded; [RecordingReference]
  • Time [dateTime]
Output
  • MediaAttributes - optional, unbounded; [MediaAttributes]
    • RecordingToken [RecordingReference]
      A reference to the recording that has these attributes.
    • TrackAttributes - optional, unbounded; [TrackAttributes]
      A set of attributes for each track.
      • TrackInformation [TrackInformation]
        The basic information about the track. Note that a track may represent a single contiguous time span or consist of multiple slices.
        • TrackToken [TrackReference]
        • TrackType [TrackType]
          Type of the track: "Video", "Audio" or "Metadata". The track shall only be able to hold data of that type.
          Enum Value Enum Description
          Video —
          Audio —
          Metadata —
          Extended Placeholder for future extension.
        • Description [Description]
          Informative description of the contents of the track.
        • DataFrom [dateTime]
          The start date and time of the oldest recorded data in the track.
        • DataTo [dateTime]
          The stop date and time of the newest recorded data in the track.
      • VideoAttributes - optional; [VideoAttributes]
        If the track is a video track, exactly one of this structure shall be present and contain the video attributes.
        • Bitrate - optional; [int]
          Average bitrate in kbps.
        • Width [int]
          The width of the video in pixels.
        • Height [int]
          The height of the video in pixels.
        • Encoding [string]
          Video encoding of the track. Use value from tt:VideoEncoding for MPEG4. Otherwise use values from tt:VideoEncodingMimeNames and IANA Media Types.
        • Framerate [float]
          Average framerate in frames per second.
      • AudioAttributes - optional; [AudioAttributes]
        If the track is an audio track, exactly one of this structure shall be present and contain the audio attributes.
        • Bitrate - optional; [int]
          The bitrate in kbps.
        • Encoding [string]
          Audio encoding of the track. Use values from tt:AudioEncoding for G711 and AAC. Otherwise use values from tt:AudioEncodingMimeNames and IANA Media Types.
        • Samplerate [int]
          The sample rate in kHz.
      • MetadataAttributes - optional; [MetadataAttributes]
        If the track is an metadata track, exactly one of this structure shall be present and contain the metadata attributes.
        • PtzSpaces - optional; [StringAttrList]
          List of all PTZ spaces active for recording. Note that events are only recorded on position changes and the actual point of recording may not necessarily contain an event of the specified type.
        • CanContainPTZ [boolean]
          Indicates that there can be PTZ data in the metadata track in the specified time interval.
        • CanContainAnalytics [boolean]
          Indicates that there can be analytics data in the metadata track in the specified time interval.
        • CanContainNotifications [boolean]
          Indicates that there can be notifications in the metadata track in the specified time interval.
      • Extension - optional; [TrackAttributesExtension]
    • From [dateTime]
      The attributes are valid from this point in time in the recording.
    • Until [dateTime]
      The attributes are valid until this point in time in the recording. Can be equal to 'From' to indicate that the attributes are only known to be valid for this particular point in time.

FindRecordings 

FindRecordings(Scope, KeepAliveTime, MaxMatches=None)

FindRecordings starts a search session, looking for recordings that matches the scope (See 20.2.4) defined in the request.

Results from the search are acquired using the GetRecordingSearchResults request, specifying the search token returned from this request. The device shall continue searching until one of the following occurs:

  • The entire time range from StartPoint to EndPoint has been searched through.
  • The total number of matches has been found, defined by the MaxMatches parameter.
  • The session has been ended by a client EndSession request.
  • The session has been ended because KeepAliveTime since the last request related to this session has expired.

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.

Input
  • Scope [SearchScope]
    Scope defines the dataset to consider for this search.
    • IncludedSources - optional, unbounded; [SourceReference]
      A list of sources that are included in the scope. If this list is included, only data from one of these sources shall be searched.
      • Type - optional; [anyURI]
      • Token [ReferenceToken]
        Maximum length: 64
    • IncludedRecordings - optional, unbounded; [RecordingReference]
      A list of recordings that are included in the scope. If this list is included, only data from one of these recordings shall be searched.
    • RecordingInformationFilter - optional; [XPathExpression]
      An xpath expression used to specify what recordings to search. Only those recordings with an RecordingInformation structure that matches the filter shall be searched.
    • Extension - optional; [SearchScopeExtension]
      Extension point
  • MaxMatches - optional; [int]
    The search will be completed after this many matches. If not specified, the search will continue until reaching the endpoint or until the session expires.
  • KeepAliveTime [duration]
    The time the search session will be kept alive after responding to this and subsequent requests. A device shall support at least values up to ten seconds.
Output
  • SearchToken [JobToken]

GetRecordingSearchResults 

GetRecordingSearchResults(
    SearchToken,
    MinResults=None,
    MaxResults=None,
    WaitTime=None,
)

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 MaxResults is specified, the response shall not contain more than MaxResults results. The number of results relates to the number of recordings. For viewing individual recorded data for a signal track use the FindEvents method.

GetRecordingSearchResults shall block until:

  • MaxResults results are available for the response if MaxResults is specified.
  • MinResults results are available for the response if MinResults is specified.
  • WaitTime has expired.
  • Search is completed or stopped.

This operation is mandatory to support for a device implementing the recording search service.

Input

Gets results from a particular recording listing session.

  • SearchToken [JobToken]
    The search session to get results from.
  • MinResults - optional; [int]
    The minimum number of results to return in one response.
  • MaxResults - optional; [int]
    The maximum number of results to return in one response.
  • WaitTime - optional; [duration]
    The maximum time before responding to the request, even if the MinResults parameter is not fulfilled.
Output
  • ResultList [FindRecordingResultList]
    • SearchState [SearchState]
      The state of the search when the result is returned. Indicates if there can be more results, or if the search is completed.
      Enum Value Enum Description
      Queued The search is queued and not yet started.
      Searching The search is underway and not yet completed.
      Completed The search has been completed and no new results will be found.
      Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)
    • RecordingInformation - optional, unbounded; [RecordingInformation]
      A RecordingInformation structure for each found recording matching the search.
      • RecordingToken [RecordingReference]
      • Source [RecordingSourceInformation]
        Information about the source of the recording. This gives a description of where the data in the recording comes from. Since a single recording is intended to record related material, there is just one source. It is indicates the physical location or the major data source for the recording. Currently the recordingconfiguration cannot describe each individual data source.
        • SourceId [anyURI]
          Identifier for the source chosen by the client that creates the structure. This identifier is opaque to the device. Clients may use any type of URI for this field. A device shall support at least 128 characters.
        • Name [Name]
          Informative user readable name of the source, e.g. "Camera23". A device shall support at least 20 characters.
          Maximum length: 64
        • Location [Description]
          Informative description of the physical location of the source, e.g. the coordinates on a map.
        • Description [Description]
          Informative description of the source.
        • Address [anyURI]
          URI provided by the service supplying data to be recorded. A device shall support at least 128 characters.
        • VideoSourceToken - optional; [ReferenceToken]
          The video source token of all recordings that will use this configuration.
          Maximum length: 64
      • EarliestRecording - optional; [dateTime]
      • LatestRecording - optional; [dateTime]
      • Content [Description]
      • Track - optional, unbounded; [TrackInformation]
        Basic information about the track. Note that a track may represent a single contiguous time span or consist of multiple slices.
        • TrackToken [TrackReference]
        • TrackType [TrackType]
          Type of the track: "Video", "Audio" or "Metadata". The track shall only be able to hold data of that type.
          Enum Value Enum Description
          Video —
          Audio —
          Metadata —
          Extended Placeholder for future extension.
        • Description [Description]
          Informative description of the contents of the track.
        • DataFrom [dateTime]
          The start date and time of the oldest recorded data in the track.
        • DataTo [dateTime]
          The stop date and time of the newest recorded data in the track.
      • RecordingStatus [RecordingStatus]
        Enum Value Enum Description
        Initiated —
        Recording —
        Stopped —
        Removing —
        Removed —
        Unknown This case should never happen.

FindEvents 

FindEvents(
    StartPoint,
    Scope,
    SearchFilter,
    IncludeStartState,
    KeepAliveTime,
    EndPoint=None,
    MaxMatches=None,
)

FindEvents starts a search session, looking for recording events (in the scope that matches the search filter defined in the request.

Results from the search are acquired using the GetEventSearchResults request, specifying the search token returned from this request.

The device shall continue searching until one of the following occurs:

  • The entire time range from StartPoint to EndPoint has been searched through.
  • The total number of matches has been found, defined by the MaxMatches parameter.
  • The session has been ended by a client EndSession request.
  • The session has been ended because KeepAliveTime since the last request related to this session has expired.

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.

Input

Starts a search session and specifies the search parameters.

  • StartPoint [dateTime]
    The point of time where the search will start.
  • EndPoint - optional; [dateTime]
    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.
  • Scope [SearchScope]
    • IncludedSources - optional, unbounded; [SourceReference]
      A list of sources that are included in the scope. If this list is included, only data from one of these sources shall be searched.
      • Type - optional; [anyURI]
      • Token [ReferenceToken]
        Maximum length: 64
    • IncludedRecordings - optional, unbounded; [RecordingReference]
      A list of recordings that are included in the scope. If this list is included, only data from one of these recordings shall be searched.
    • RecordingInformationFilter - optional; [XPathExpression]
      An xpath expression used to specify what recordings to search. Only those recordings with an RecordingInformation structure that matches the filter shall be searched.
    • Extension - optional; [SearchScopeExtension]
      Extension point
  • SearchFilter [EventFilter]
  • IncludeStartState [boolean]
    Setting IncludeStartState to true means that the server should return virtual events representing the start state for any recording included in the scope. Start state events are limited to the topics defined in the SearchFilter that have the IsProperty flag set to true.
  • MaxMatches - optional; [int]
    The search will be completed after this many matches. If not specified, the search will continue until reaching the endpoint or until the session expires.
  • KeepAliveTime [duration]
    The time the search session will be kept alive after responding to this and subsequent requests. A device shall support at least values up to ten seconds.
Output
  • SearchToken [JobToken]
    A unique reference to the search session created by this request.

GetEventSearchResults 

GetEventSearchResults(
    SearchToken,
    MinResults=None,
    MaxResults=None,
    WaitTime=None,
)

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 MaxResults is specified, the response shall not contain more than MaxResults results.

GetEventSearchResults shall block until:

  • MaxResults results are available for the response if MaxResults is specified.
  • MinResults results are available for the response if MinResults is specified.
  • WaitTime has expired.
  • Search is completed or stopped.

This operation is mandatory to support for a device implementing the recording search service.

Input

Gets results from a particular search session.

  • SearchToken [JobToken]
    The search session to get results from.
  • MinResults - optional; [int]
    The minimum number of results to return in one response.
  • MaxResults - optional; [int]
    The maximum number of results to return in one response.
  • WaitTime - optional; [duration]
    The maximum time before responding to the request, even if the MinResults parameter is not fulfilled.
Output
  • ResultList [FindEventResultList]
    • SearchState [SearchState]
      The state of the search when the result is returned. Indicates if there can be more results, or if the search is completed.
      Enum Value Enum Description
      Queued The search is queued and not yet started.
      Searching The search is underway and not yet completed.
      Completed The search has been completed and no new results will be found.
      Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)
    • Result - optional, unbounded; [FindEventResult]
      A FindEventResult structure for each found event matching the search.
      • RecordingToken [RecordingReference]
        The recording where this event was found. Empty string if no recording is associated with this event.
      • TrackToken [TrackReference]
        A reference to the track where this event was found. Empty string if no track is associated with this event.
      • Time [dateTime]
        The time when the event occurred.
      • Event [NotificationMessageHolderType]
        The description of the event.
        • SubscriptionReference - optional; [EndpointReferenceType]
          • Address [AttributedURIType]
          • ReferenceParameters - optional; [ReferenceParametersType]
          • Metadata - optional; [MetadataType]
        • Topic - optional; [TopicExpressionType]
          • Dialect - required; [anyURI]
        • ProducerReference - optional; [EndpointReferenceType]
          • Address [AttributedURIType]
          • ReferenceParameters - optional; [ReferenceParametersType]
          • Metadata - optional; [MetadataType]
        • Message [complexType]
      • StartStateEvent [boolean]
        If true, indicates that the event is a virtual event generated for this particular search session to give the state of a property at the start time of the search.

FindPTZPosition 

FindPTZPosition(
    StartPoint,
    Scope,
    SearchFilter,
    KeepAliveTime,
    EndPoint=None,
    MaxMatches=None,
)

FindPTZPosition starts a search session, looking for ptz positions in the scope (See 20.2.4) 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.

The device shall continue searching until one of the following occurs:

  • The entire time range from StartPoint to EndPoint has been searched through.
  • The total number of matches has been found, defined by the MaxMatches parameter.
  • The session has been ended by a client EndSession request.
  • The session has been ended because KeepAliveTime since the last request related to this session has expired.

This operation is mandatory to support whenever CanContainPTZ is true for any metadata track in any recording on the device.

Input

Starts a search session and specifies the search parameters.

  • StartPoint [dateTime]
    The point of time where the search will start.
  • EndPoint - optional; [dateTime]
    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.
  • Scope [SearchScope]
    • IncludedSources - optional, unbounded; [SourceReference]
      A list of sources that are included in the scope. If this list is included, only data from one of these sources shall be searched.
      • Type - optional; [anyURI]
      • Token [ReferenceToken]
        Maximum length: 64
    • IncludedRecordings - optional, unbounded; [RecordingReference]
      A list of recordings that are included in the scope. If this list is included, only data from one of these recordings shall be searched.
    • RecordingInformationFilter - optional; [XPathExpression]
      An xpath expression used to specify what recordings to search. Only those recordings with an RecordingInformation structure that matches the filter shall be searched.
    • Extension - optional; [SearchScopeExtension]
      Extension point
  • SearchFilter [PTZPositionFilter]
    • MinPosition [PTZVector]
      The lower boundary of the PTZ volume to look for.
      • PanTilt - optional; [Vector2D]
        Pan and tilt position. The x component corresponds to pan and the y component to tilt.
        • x - required; [float]
        • y - required; [float]
        • space - optional; [anyURI]
          Pan/tilt coordinate space selector. The following options are defined:
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/PositionGenericSpace
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/TranslationGenericSpace
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/VelocityGenericSpace
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/GenericSpeedSpace
      • Zoom - optional; [Vector1D]
        A zoom position.
        • x - required; [float]
        • space - optional; [anyURI]
          Zoom coordinate space selector. The following options are defined:
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/PositionGenericSpace
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/TranslationGenericSpace
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/VelocityGenericSpace
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/ZoomGenericSpeedSpace
    • MaxPosition [PTZVector]
      The upper boundary of the PTZ volume to look for.
      • PanTilt - optional; [Vector2D]
        Pan and tilt position. The x component corresponds to pan and the y component to tilt.
        • x - required; [float]
        • y - required; [float]
        • space - optional; [anyURI]
          Pan/tilt coordinate space selector. The following options are defined:
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/PositionGenericSpace
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/TranslationGenericSpace
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/VelocityGenericSpace
          • http://www.onvif.org/ver10/tptz/PanTiltSpaces/GenericSpeedSpace
      • Zoom - optional; [Vector1D]
        A zoom position.
        • x - required; [float]
        • space - optional; [anyURI]
          Zoom coordinate space selector. The following options are defined:
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/PositionGenericSpace
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/TranslationGenericSpace
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/VelocityGenericSpace
          • http://www.onvif.org/ver10/tptz/ZoomSpaces/ZoomGenericSpeedSpace
    • EnterOrExit [boolean]
      If true, search for when entering the specified PTZ volume.
  • MaxMatches - optional; [int]
    The search will be completed after this many matches. If not specified, the search will continue until reaching the endpoint or until the session expires.
  • KeepAliveTime [duration]
    The time the search session will be kept alive after responding to this and subsequent requests. A device shall support at least values up to ten seconds.
Output
  • SearchToken [JobToken]
    A unique reference to the search session created by this request.

GetPTZPositionSearchResults 

GetPTZPositionSearchResults(
    SearchToken,
    MinResults=None,
    MaxResults=None,
    WaitTime=None,
)

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 MaxResults is specified, the response shall not contain more than MaxResults results.

GetPTZPositionSearchResults shall block until:

  • MaxResults results are available for the response if MaxResults is specified.
  • MinResults results are available for the response if MinResults is specified.
  • WaitTime has expired.
  • Search is completed or stopped.

This operation is mandatory to support whenever CanContainPTZ is true for any metadata track in any recording on the device.

Input

Gets results from a particular search session.

  • SearchToken [JobToken]
    The search session to get results from.
  • MinResults - optional; [int]
    The minimum number of results to return in one response.
  • MaxResults - optional; [int]
    The maximum number of results to return in one response.
  • WaitTime - optional; [duration]
    The maximum time before responding to the request, even if the MinResults parameter is not fulfilled.
Output
  • ResultList [FindPTZPositionResultList]
    • SearchState [SearchState]
      The state of the search when the result is returned. Indicates if there can be more results, or if the search is completed.
      Enum Value Enum Description
      Queued The search is queued and not yet started.
      Searching The search is underway and not yet completed.
      Completed The search has been completed and no new results will be found.
      Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)
    • Result - optional, unbounded; [FindPTZPositionResult]
      A FindPTZPositionResult structure for each found PTZ position matching the search.
      • RecordingToken [RecordingReference]
        A reference to the recording containing the PTZ position.
      • TrackToken [TrackReference]
        A reference to the metadata track containing the PTZ position.
      • Time [dateTime]
        The time when the PTZ position was valid.
      • Position [PTZVector]
        The PTZ position.
        • PanTilt - optional; [Vector2D]
          Pan and tilt position. The x component corresponds to pan and the y component to tilt.
          • x - required; [float]
          • y - required; [float]
          • space - optional; [anyURI]
            Pan/tilt coordinate space selector. The following options are defined:
            • http://www.onvif.org/ver10/tptz/PanTiltSpaces/PositionGenericSpace
            • http://www.onvif.org/ver10/tptz/PanTiltSpaces/TranslationGenericSpace
            • http://www.onvif.org/ver10/tptz/PanTiltSpaces/VelocityGenericSpace
            • http://www.onvif.org/ver10/tptz/PanTiltSpaces/GenericSpeedSpace
        • Zoom - optional; [Vector1D]
          A zoom position.
          • x - required; [float]
          • space - optional; [anyURI]
            Zoom coordinate space selector. The following options are defined:
            • http://www.onvif.org/ver10/tptz/ZoomSpaces/PositionGenericSpace
            • http://www.onvif.org/ver10/tptz/ZoomSpaces/TranslationGenericSpace
            • http://www.onvif.org/ver10/tptz/ZoomSpaces/VelocityGenericSpace
            • http://www.onvif.org/ver10/tptz/ZoomSpaces/ZoomGenericSpeedSpace

GetSearchState 

GetSearchState(SearchToken)

GetSearchState returns the current state of the specified search session.

This command is deprecated .

Input

Returns the state of an ongoing search session.

  • SearchToken [JobToken]
    The search session to get the state from.
Output
  • State [SearchState]
    Enum Value Enum Description
    Queued The search is queued and not yet started.
    Searching The search is underway and not yet completed.
    Completed The search has been completed and no new results will be found.
    Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)

EndSearch 

EndSearch(SearchToken)

EndSearch stops and ongoing search session, causing any blocking result request to return and the SearchToken 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 StartPoint shall be returned. If the search was completed the original EndPoint supplied by the Find operation shall be returned. When issuing EndSearch on a FindRecordings request the EndPoint 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.

Input

Ends an ongoing search session, freeing any resources.

  • SearchToken [JobToken]
    The search session to end.
Output
  • Endpoint [dateTime]
    The point of time the search had reached when it was ended. It is equal to the EndPoint specified in Find-operation if the search was completed.

FindMetadata 

FindMetadata(
    StartPoint,
    Scope,
    MetadataFilter,
    KeepAliveTime,
    EndPoint=None,
    MaxMatches=None,
)

FindMetadata starts a search session, looking for metadata in the scope (See 20.2.4) 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.

The device shall continue searching until one of the following occurs:

  • The entire time range from StartPoint to EndPoint has been searched through.
  • The total number of matches has been found, defined by the MaxMatches parameter.
  • The session has been ended by a client EndSession request.
  • The session has been ended because KeepAliveTime since the last request related to this session has expired.

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.

Input

Starts a search session and specifies the search parameters.

  • StartPoint [dateTime]
    The point of time where the search will start.
  • EndPoint - optional; [dateTime]
    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.
  • Scope [SearchScope]
    • IncludedSources - optional, unbounded; [SourceReference]
      A list of sources that are included in the scope. If this list is included, only data from one of these sources shall be searched.
      • Type - optional; [anyURI]
      • Token [ReferenceToken]
        Maximum length: 64
    • IncludedRecordings - optional, unbounded; [RecordingReference]
      A list of recordings that are included in the scope. If this list is included, only data from one of these recordings shall be searched.
    • RecordingInformationFilter - optional; [XPathExpression]
      An xpath expression used to specify what recordings to search. Only those recordings with an RecordingInformation structure that matches the filter shall be searched.
    • Extension - optional; [SearchScopeExtension]
      Extension point
  • MetadataFilter [MetadataFilter]
    • MetadataStreamFilter [XPathExpression]
  • MaxMatches - optional; [int]
    The search will be completed after this many matches. If not specified, the search will continue until reaching the endpoint or until the session expires.
  • KeepAliveTime [duration]
    The time the search session will be kept alive after responding to this and subsequent requests. A device shall support at least values up to ten seconds.
Output
  • SearchToken [JobToken]
    A unique reference to the search session created by this request.

GetMetadataSearchResults 

GetMetadataSearchResults(
    SearchToken,
    MinResults=None,
    MaxResults=None,
    WaitTime=None,
)

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 MaxResults is specified, the response shall not contain more than MaxResults results.

GetMetadataSearchResults shall block until:

  • MaxResults results are available for the response if MaxResults is specified.
  • MinResults results are available for the response if MinResults is specified.
  • WaitTime has expired.
  • Search is completed or stopped.

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.

Input

Gets results from a particular search session.

  • SearchToken [JobToken]
    The search session to get results from.
  • MinResults - optional; [int]
    The minimum number of results to return in one response.
  • MaxResults - optional; [int]
    The maximum number of results to return in one response.
  • WaitTime - optional; [duration]
    The maximum time before responding to the request, even if the MinResults parameter is not fulfilled.
Output
  • ResultList [FindMetadataResultList]
    • SearchState [SearchState]
      The state of the search when the result is returned. Indicates if there can be more results, or if the search is completed.
      Enum Value Enum Description
      Queued The search is queued and not yet started.
      Searching The search is underway and not yet completed.
      Completed The search has been completed and no new results will be found.
      Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)
    • Result - optional, unbounded; [FindMetadataResult]
      A FindMetadataResult structure for each found set of Metadata matching the search.
      • RecordingToken [RecordingReference]
        A reference to the recording containing the metadata.
      • TrackToken [TrackReference]
        A reference to the metadata track containing the matching metadata.
      • Time [dateTime]
        The point in time when the matching metadata occurs in the metadata track.

SearchImageByNL 

SearchImageByNL(
    StartPoint,
    Text,
    KeepAliveTime,
    EndPoint=None,
    RecordingToken=None,
    Similarity=None,
    MaxMatches=None,
)

0.2.11

Starts a natural language search session and specifies the search parameters.

Input

Starts a search session and specifies the search parameters.

  • StartPoint [dateTime]
    Start time for the search.
  • EndPoint - optional; [dateTime]
    The point of time where the search will stop. If EndPoint is omitted, the search will continue up to the latest recorded data available on the device.
  • RecordingToken - optional; [RecordingReference]
    Token for the recording to search.
  • Text [string]
    Natural language description for the search (e.g., "person with red hat").
  • Similarity - optional; [float]
    It represents the similarity between two vectors, which is used to measure the similarity of the directions of the vectors. The closer the value is to 1, the higher the similarity; the closer the value is to 0, the lower the similarity.
  • MaxMatches - optional; [int]
    Maximum number of matches to return in the response.
  • KeepAliveTime [duration]
    The time the search session will be kept alive after responding to this and subsequent requests.
Output
  • SearchToken [JobToken]
    A unique reference to the search session created by this request.

GetNLSearchResults 

GetNLSearchResults(
    SearchToken,
    MinResults=None,
    MaxResults=None,
    WaitTime=None,
)

0.2.11

Gets results from a natural language search session.

Input

Gets results from a particular search session.

  • SearchToken [JobToken]
    The search session to get results from.
  • MinResults - optional; [int]
    The minimum number of results to return in one response.
  • MaxResults - optional; [int]
    The maximum number of results to return in one response.
  • WaitTime - optional; [duration]
    The maximum time before responding to the request, even if the MinResults parameter is not fulfilled.
Output
  • ResultList [FindNLSearchResultList]
    • SearchState [SearchState]
      The state of the search when the result is returned. Indicates if there can be more results, or if the search is completed.
      Enum Value Enum Description
      Queued The search is queued and not yet started.
      Searching The search is underway and not yet completed.
      Completed The search has been completed and no new results will be found.
      Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)
    • Result - optional, unbounded; [FindNLSearchResult]
      A FindNLSearchResult structure for each found set of image matching the search.
      • ObjectUUID [string]
        Object unique identifier.
      • TargetImageURI [anyURI]
        The URI of the detected target object image stored in the Target Image repository (LocalStorage format).
      • Time [dateTime]
        The time when the target was found. Users can use this as a reference point to search records that occurred before and after this specific time point.
      • Similarity [float]
        It represents the similarity between two vectors, which is used to measure the similarity of the directions of the vectors. The closer the value is to 1, the higher the similarity; the closer the value is to 0, the lower the similarity.
      • RecordingToken [RecordingReference]
        The recording where this result was found.

SearchImageByImage 

SearchImageByImage(
    StartPoint,
    KeepAliveTime,
    EndPoint=None,
    RecordingToken=None,
    TargetImageURI=None,
    TargetImageData=None,
    MaxMatches=None,
)

0.2.11

Starts an image-based search session and specifies the search parameters.

Input

Starts a search session and specifies the search parameters.

  • StartPoint [dateTime]
    Start time for the search.
  • EndPoint - optional; [dateTime]
    The point of time where the search will stop. If EndPoint is omitted, the search will continue up to the latest recorded data available on the device.
  • RecordingToken - optional; [RecordingReference]
    Token for the recording to search.
  • TargetImageURI - optional; [anyURI]
    Exactly one of TargetImageURI or TargetImageData shall be provided. If both are provided, the device shall use TargetImageData. If neither is provided, the device shall respond with an InvalidArgVal fault. The URI of the detected target object image stored in the Target Image repository (LocalStorage format).
  • TargetImageData - optional; [base64Binary]
    Exactly one of TargetImageURI or TargetImageData shall be provided. If both are provided, the device shall use TargetImageData. If neither is provided, the device shall respond with an InvalidArgVal fault. Base64-encoded target object image used for visual search.
  • MaxMatches - optional; [int]
    Maximum number of matches to return in the response.
  • KeepAliveTime [duration]
    The time the search session will be kept alive after responding to this and subsequent requests.
Output
  • SearchToken [JobToken]
    A unique reference to the search session created by this request.

GetImageSearchResults 

GetImageSearchResults(
    SearchToken,
    MinResults=None,
    MaxResults=None,
    WaitTime=None,
)

0.2.11

Gets results from an image-based search session.

Input
  • SearchToken [JobToken]
    The search session to get results from.
  • MinResults - optional; [int]
    The minimum number of results to return in one response.
  • MaxResults - optional; [int]
    The maximum number of results to return in one response.
  • WaitTime - optional; [duration]
    The maximum time before responding to the request, even if the MinResults parameter is not fulfilled.
Output
  • ResultList [FindObjectImageResultList]
    • SearchState [SearchState]
      The state of the search when the result is returned. Indicates if there can be more results, or if the search is completed.
      Enum Value Enum Description
      Queued The search is queued and not yet started.
      Searching The search is underway and not yet completed.
      Completed The search has been completed and no new results will be found.
      Unknown The state of the search is unknown. (This is not a valid response from GetSearchState.)
    • Result - optional, unbounded; [FindObjectImageResult]
      A FindObjectImageResult structure for each found set of image matching the search.
      • ObjectUUID [string]
        Object unique identifier.
      • TargetImageURI [anyURI]
        The URI of the detected target object image stored in the Target Image repository (LocalStorage format).
      • Time [dateTime]
        The time when the target was found. Users can use this as a reference point to search records that occurred before and after this specific time point.
      • Similarity [float]
        It represents the similarity between two vectors, which is used to measure the similarity of the directions of the vectors. The closer the value is to 1, the higher the similarity; the closer the value is to 0, the lower the similarity.
      • RecordingToken [RecordingReference]
        The recording where this result was found.