There are 2 problems with this api which I've spotted while using it
from the local (file) addressbook backend (for reference, these problems
presented themselves while working on bug 652172).

For clarity, assume that we are using an EBookBackendSqlitedb object
configured with 'store-vcards' FALSE (the sqlitedb is only used for
stashing quick access virtual 'summary' objects and possibly for listing 
contact uids).

  a.) When _sqlitedb_search() is called and the 'fields-of-interest'
      parameter is NULL, if the query is a valid summary query
      (i.e. it tests one of the summary fields) then shallow 'summary' 
      objects will be constructed and returned.

      This is either wrong or impractical for use from EBookBackendFile.

      The backend should construct virtual 'summary' vcards if and only if
      the 'fields-of-interest' is set to filter the vcard contents.

      For example, if you query for every vcard where the full name 
      contains the text 'jackson', you might be interested in more than
      only the summary fields.

  b.) This might be implicitly solved by tackling the first issue, but
      currently the _sqlitedb_search() api does not tell the caller if
      it actually performed a summary search or not.

      In the current situation the file backend will resort to iteration
      over the BDB even if the query was a valid summary query that returned
      zero results.


Before fixing this we should consider what is the right api, I think we
want the following features/type of integration:

  o If the query is an 'x-evolution-any-field' query, or a query for
    any of the summary fields, then sqlitedb_search() should perform a search.

    Otherwise it should resort to returning the 'stored-vcards' if any or
    NULL.

  o If fields-of-interest is specified, and all the fields of interest specified
    are part of the 'summary' fields, then virtual objects should be constructed
    and returned in the list.

  o If fields-of-interest is NULL or specifies fields that are not part of the
    summary, then the search (if possible) should still be performed.

    But in this case only a list of uids should be returned and not full 
    constructed virtual summary objects.

    In this specific case the backend will use the returned uids (as it did
    with the old EBookBackendSummary object) to pick up the full vcards from
    the BDB.

    Since the query will already be valid from the summary we can use
    e_data_book_notify_prefiltered_vcard() and avoid the extra processing but
    still provide full vcards for a NULL fields-of-interest (or a 
    fields-of-interest that is not covered by the summary).

Perhaps a fully usable api (from my current POV) would look like:

GSList *
e_book_backend_sqlitedb_search(EBookBackendSqliteDB *ebsdb,
			       const gchar *folderid,
			       const gchar *sexp,
			       /* const */ GHashTable *fields_of_interest,
                               gboolean    *searched_summary,
                               gboolean    *full_objects_returned,
			       GError     **error);

Essentially 'searched_summary' would let the caller know if the query
was actually used and performed on the sqlitedb (so the backend can
avoid further processing on a NULL result).

And 'full_objects_returned' would be set to TRUE if the full vcard was
returned (via store-vcards feature) and if all the fields-of-interest
were satisfied and a complete virtual vcard was constructed.

When 'full_objects_returned' is found to be FALSE, the backend can
rely on the returned list of contact UIDs to fetch complete vcards
from the BDB and notify with the 'prefiltered' api.


I am exceedingly sorry for my long and detailed bug reports and comments, I'm
obviously not comfortable enough with the code base to use the right buzzwords
and I'm trying to be extra clear to avoid any unneeded back and forth.