Android
android.content
public class

android.content.SearchRecentSuggestionsProvider

java.lang.Object
android.content.ContentProvider ComponentCallbacks
android.content.SearchRecentSuggestionsProvider

This superclass can be used to create a simple search suggestions provider for your application. It creates suggestions (as the user types) based on recent queries and/or recent views.

In order to use this class, you must do the following.

  • Implement and test query search, as described in SearchManager. (This provider will send any suggested queries via the standard ACTION_SEARCH Intent, which you'll already support once you have implemented and tested basic searchability.)
  • Create a Provider within your application by extending SearchRecentSuggestionsProvider. The class you create will be very simple - typically, it will have only a constructor. But it has a very important responsibility: When your constructor calls setupSuggestions(String, int) it configures the provider to match the requirements of your searchable activity.
  • Create a manifest entry describing your provider. Typically this would be as simple as adding the following lines:
         <!-- Content provider for search suggestions -->
         <provider android:name="YourSuggestionProviderClass"
                   android:authorities="your.suggestion.authority" />
  • Update your searchable activity's XML configuration file with information about your provider. The following additions are usually sufficient:
         android:searchSuggestAuthority="your.suggestion.authority"
         android:searchSuggestSelection=" ? "
  • In your searchable activities, capture any user-generated queries and record them for future searches by calling SearchRecentSuggestions.saveRecentQuery().

Summary

Constants

      Value  
int  DATABASE_MODE_2LINES  This mode bit configures the database to include a 2nd annotation line with each entry.  0x00000002 
int  DATABASE_MODE_QUERIES  This mode bit configures the database to record recent queries.  0x00000001 

Public Constructors

            SearchRecentSuggestionsProvider()

Public Methods

          int  delete(Uri uri, String selection, String[] selectionArgs)
A request to delete one or more rows.
          String  getType(Uri uri)
Return the MIME type of the data at the given URI.
          Uri  insert(Uri uri, ContentValues values)
Note: This table has on-conflict-replace semantics so this insert() may actually replace()
          boolean  onCreate()
Called when the provider is being started.
          Cursor  query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)
Receives a query request from a client in a local process, and returns a Cursor.
          int  update(Uri uri, ContentValues values, String selection, String[] selectionArgs)
Update a content URI.

Protected Methods

          void  setupSuggestions(String authority, int mode)
In order to use this class, you must extend it, and call this setup function from your constructor.
Methods inherited from class android.content.ContentProvider
Methods inherited from class java.lang.Object
Methods inherited from interface android.content.ComponentCallbacks

Details

Constants

public static final int DATABASE_MODE_2LINES

This mode bit configures the database to include a 2nd annotation line with each entry. optional
Constant Value: 2 (0x00000002)

public static final int DATABASE_MODE_QUERIES

This mode bit configures the database to record recent queries. required
Constant Value: 1 (0x00000001)

Public Constructors

public SearchRecentSuggestionsProvider()

Public Methods

public int delete(Uri uri, String selection, String[] selectionArgs)

A request to delete one or more rows. The selection clause is applied when performing the deletion, allowing the operation to affect multiple rows in a directory. As a courtesy, call notifyDelete() after deleting. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

The implementation is responsible for parsing out a row ID at the end of the URI, if a specific row is being deleted. That is, the client would pass in content://contacts/people/22 and the implementation is responsible for parsing the record number (22) when creating a SQL statement.

Parameters

uri The full URI to query, including a row ID (if a specific record is requested).
selection An optional restriction to apply to rows when deleting.

Returns

  • The number of rows affected.

public String getType(Uri uri)

Return the MIME type of the data at the given URI. This should start with vnd.android.cursor.item for a single record, or vnd.android.cursor.dir/ for multiple items. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Parameters

uri the URI to query.

Returns

  • a MIME type string, or null if there is no type.

public Uri insert(Uri uri, ContentValues values)

Note: This table has on-conflict-replace semantics so this insert() may actually replace()

Parameters

uri The content:// URI of the insertion request.
values A set of column_name/value pairs to add to the database.

Returns

  • The URI for the newly inserted item.

public boolean onCreate()

Called when the provider is being started.

Returns

  • true if the provider was successfully loaded, false otherwise

public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder)

Receives a query request from a client in a local process, and returns a Cursor. This is called internally by the ContentResolver. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Example client call:

// Request a specific record.
 Cursor managedCursor = managedQuery(
                Contacts.People.CONTENT_URI.addId(2),
                projection,    // Which columns to return.
                null,          // WHERE clause.
                People.NAME + " ASC");   // Sort order.
Example implementation:

// SQLiteQueryBuilder is a helper class that creates the
        // proper SQL syntax for us.
        SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();

        // Set the table we're querying.
        qBuilder.setTables(DATABASE_TABLE_NAME);

        // If the query ends in a specific record number, we're
        // being asked for a specific record, so set the
        // WHERE clause in our query.
        if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
            qBuilder.appendWhere("_id=" + uri.getPathLeafId());
        }

        // Make the query.
        Cursor c = qBuilder.query(mDb,
                projection,
                selection,
                selectionArgs,
                groupBy,
                having,
                sortOrder);
        c.setNotificationUri(getContext().getContentResolver(), uri);
        return c;

Parameters

uri The URI to query. This will be the full URI sent by the client; if the client is requesting a specific record, the URI will end in a record number that the implementation should parse and add to a WHERE or HAVING clause, specifying that _id value.
projection The list of columns to put into the cursor. If null all columns are included.
selection A selection criteria to apply when filtering rows. If null then all rows are included.
sortOrder How the rows in the cursor should be sorted. If null then the provider is free to define the sort order.

Returns

  • a Cursor or null.

public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs)

Update a content URI. All rows matching the optionally provided selection will have their columns listed as the keys in the values map with the values of those keys. As a courtesy, call notifyChange() after updating. This method can be called from multiple threads, as described in the Threading section of the Application Model overview.

Parameters

uri The URI to query. This can potentially have a record ID if this is an update request for a specific record.
values A Bundle mapping from column names to new column values (NULL is a valid value).
selection An optional filter to match rows to update.

Returns

  • the number of rows affected.

Protected Methods

protected void setupSuggestions(String authority, int mode)

In order to use this class, you must extend it, and call this setup function from your constructor. In your application or activities, you must provide the same values when you create the SearchRecentSuggestions helper.

Parameters

authority This must match the authority that you've declared in your manifest.
mode You can use mode flags here to determine certain functional aspects of your database. Note, this value should not change from run to run, because when it does change, your suggestions database may be wiped.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48