[Wasabi Proposal] Live search API

[Magnus Bergman]

First some comments on the current draft[1]
"""""""""""""""""""""""""""""""""""""""""""

  As with the WasabiSearchSimple API[2] the session *is* the D-BUS
  connection. So there really doesn't need to be an explicit session
  object. It might be adequate to have one for the language bindings,
  but then the same thing goes for the simple API.

  If the method GetMetadata should exist I think it would make more
  sense to make it belong to a document object, rename it GetProperty
  and include it in the metadata storage API instead.

  And as I said before, I think it makes sense to treat queries and
  searches as different objects, which means renaming Query.Start to
  something like NewSearch. It also means that a query doesn't need to
  belong to anything (like the session), it could exist independently
  (unlike a search). I have left out possible functions dealing with
  queries (like constructing an XML query from a simple query string)
  since functions like that rather belong in a library.

  Apart from ShowConfiguration(), all functions of the simple API seems
  to be in the live API as well. All of them identical except for
  Query/Query.Start (which I would like to call Search), which takes a
  string in the simple API and a query object in the live API (and
  blocks until the search is done for the simple API). So, would it be
  possible and desirable to define the simple API as a subset of the
  live API?

The actual proposal
"""""""""""""""""""

SetProperty ( in s property , in s value )

    Set a global (session) property. This method can be used for
    several things.
      o Setting default properties for Query objects.
      o Authentication/encryption
      o Generally be flexible for future needs
    * property: Name of the property.
    * value: New value for the property.

GetProperty ( in s property , out s value)

    Get the value of a global (session) property.
    * property: Name of the property.
    * value: Current value of the property.

NewSearchFromXML ( in s query_xml , out s search )

    Start a new search from an XML query. 
    * query_xml: The query to execute.
    * search: A handle that is used to uniquely identify this search.



SearchClose ( in s search)

    Close the given query for any further requests. The search engine
    can free all resources related to the query. This function is also
    included in the simple search API.

SearchSetProperty ( in s search , in s property , in s value)

    Set the given property of the search object. Examples of usage:
      o Set the metadata fields to return with the Query. GetHits
        method. the value argument is semi-colon separated list of
        metadata field names
      o Set sort order
      o Insert arbitrary tweak of Query behavior
    * search: A handle that is used to uniquely identify a search.
    * property: Name of the property.
    * value: New value for the property.

SearchGetProperty ( in s search , in s property , out s value)

    Get the value of a search property.
    * search: A handle that is used to uniquely identify a search.
    * property: Name of the property.
    * value: Current value of the property.

SearchCountHits ( in s search , out i count )

    Count the current number of items found. Used for paging and
    suggestion popups with hit counts. The count is not guaranteed to
    be exact since it might change at any time. To get the exact count,
    it must be calculated from the signals SearchHitsAdded() and
    SearchHitsRemoved(). This function is also included in the simple
    search API (but then it's completely reliable).
    * search: A handle that is used to uniquely identify a search.
    * count: The number of objects that match the query.

SearchGetHitProperties ( in s search, in i offset, in i limit,
                         in as properties, out a{sa{sas}} response )

    Get properties for the given hits. The range of hits might include
    index numbers for hits that have been invalidated, the properties
    will be empty for those. This function is also included in the
    simple search API.
    * search: A handle that is used to uniquely identify a search.
    * offset: The offset in the result list for the first returned
              result.
    * limit: The maximum number of results that should be returned.
    * properties: A list of properties to return. An empty list is a
                  request for all properties.
    * response: A map mapping each hit (sequence number) to a map of
                property-list of values pairs.



signal SearchHitsAdded ( s search , i count)

    New hits have been added to the search.
    * search: A handle that is used to uniquely identify a search.
    * count: Number of new items. The first one has the index
      number one higher than the previously highest one (even if the
      old one is no longer valid).

signal SearchHitsRemoved ( s search , ai offsets )

    Hits have been removed from the search.
    * search: A handle that is used to uniquely identify a search.
    * offsets: A list of offsets (aka index numbers) which are no
      longer valid hits.

signal HitsHitsModified ( s search , ai offsets )

    Hits have been modified but are still valid. Some of the properties
    might have changed.
    * search: A handle that is used to uniquely identify a search.
    * offsets: A list of offsets (aka index numbers) which have changed.



[1] http://www.freedesktop.org/wiki/WasabiSearchLive
[2] http://www.freedesktop.org/wiki/WasabiSearchSimple